dotnet tool install --global vs-secrets --version 2.0.0
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local vs-secrets --version 2.0.0
nuke :add-package vs-secrets --version 2.0.0
Visual Studio Solution Secrets
Synchronize solution secrets across different development machines.
- Get Started
- Best Practices
- The Problem
- The Solution
- How to install
- Configure the encryption key and authorizations
- Repository configuration
- Push solution secrets
- Pull solution secrets
- Utility commands
- Configuration files
If you already know it, here are the quick start commands.
dotnet tool install --global vs-secrets
vs-secrets init -p <your-passphrase>
- Pull secrets
As a good practices in DevOps, you must not store secrets (sensitive data like passwords, connection strings, access keys, etc.) in your source code that is committed in a shared repository and secrets must not be deployed with the apps.
Fortunately Visual Studio and .Net help us in separating secrets from our code with the User Secrets Manager that let us store secrets out of the solution folder. The User Secrets Manager hides implementation details, but essentially it stores secrets in files located in the machine's user profile folder.
You can find the User Secrets Manager documentation here.
The User Secrets Manager is a great tool, but when you change your development machine, usually you clone your project code from a remote repository and then you would like to be up and running for coding and testing in a matter of seconds.
But if you have managed secrets with the User Secrets Manager you will not be immediatly able to test your code because you will miss something very important on your new machine: the secret settings that let your code work.
For being ready to start coding and testing on the new development machine, you have three choices.
- Manually copy secret files from the old machine to the new one, if you still have access to the old machine.
- Recreate the secret settings on your new machine for each project of the solution, but this can be tedious because you have to recover passwords, keys, etc. from different resources and it can be time consuming.
- **New** : use Visual Studio Solution Secrets to synchronize secret settings through the cloud in a quick and secure way.
Visual Studio Solution Secrets synchronizes secret settings through the cloud in a quick and secure way.
The idea is to use a secure repository in the cloud for storing secret settings, so that when you change the development machine, you don't have to copy any file from the old one.
Just install the tool, configure it and pull the solutions secrets on your new machine and you are ready to code.
Visual Studio Solution Secrets support two kinds of remote repositories:
- GitHub Gists
- Azure Key Vault
A "gist" is a snippet of code that can either be public or secret. Visual Studio Solution Secrets uses only secret gists.
GitHub Gists is the default repository used by Visual Studio Solution Secrets for storing solutions secrets. Secrets are collected, encrypted and pushed on your GitHub account in a secret gist, so that only you can see them. The encryption key is generated from a passphrase or a key file that you specify during the one time initialization phase of the tool.
GitHub Gists fits very well for personal use.
Azure Key Vault
Azure Key Vault is a cloud service for securely storing and accessing secrets. Secrets are encrypted at rest and can be accessed only be authorized accounts. No one else can read their contents.
Since the secrets are encrypted at rest and communication with the key vault is secure because it is enforced as HTTPS / TLS 1.2, Visual Studio Solution Secrets does not encrypt the secrets by itself before sending them to the key vault, therefore it is not necessary to use the encryption key on the local machine.
This opens the scenario in which you can share the secrets of the solution with the development team. You just need to authorize the team with read or read/write access to the Azure Key Vault secrets, so that the team can pull secrets.
Azure Key Vault fits better for enterprise use and is the recommended way for sharing solution secrets within the team.
You can read the Azure Key Vault documentation here
How to install
The tool is installed using the dotnet command line interface:
dotnet tool install --global vs-secrets
For upgrading to the latest version, use the command:
dotnet tool update --global vs-secrets
Configure the encryption key and authorizations
In case you use GitHub Gists as secrets repository, after the tool is installed, you need to create the encryption key and then authorize the use of your GitHub Gists.
The local encryption key is not necessary with Azure Key Vault.
Create the encryption key from a passphrase:
vs-secrets init -p <your-passphrase>
Otherwise, you can create the encryption key from a key file with the command below:
vs-secrets init --keyfile <file-path>
In case the encryption key is compromised you can change it.
vs-secrets changekey --passphrase <new-passphrase> vs-secrets changekey --keyfile <file-path>
When you change the encryption key with one of the above commands, any secret already encrypted on GitHub Gists is re-encrypted with the new key. In this way the compromised key becomes useless.
As said, GitHub Gists is the default repository, but in case you need, any solution can use a different repository for storing its secret settings.
For example, you can set up your own projects to use GitHub Gists and work projects to use Azure Key Vault.
For configuring the solution to use GitHub Gists:
vs-secrets configure --repo github
For configuring the solution to use Azure Key Vault:
vs-secrets configure --repo azurekv --name <vault-name | vault-uri>
--name option works only for Azure Key Vault repositories and can accept the key vault URI (ex:
https://my-keyvault.vault.azure.net) or the resource name (ex:
my-keyvault). In case you use the key vault resource name, it is then completed in its URI (ex:
For changing the default repository, use one of the commands below:
vs-secrets configure --default --repo github vs-secrets configure --default --repo azurekv --name <vault-name | vault-uri>
Sometimes you need to check what is the default repository, or if the solution has a custom repository configuration.
configure list serves to this purpose.
vs-secrets configure list [<folder-path>] [--all]
Push solution secrets
For pushing the secrets of the solution in the current folder:
For pushing the secrets of the solution in another folder:
vs-secrets push <solution-path>
For pushing the secrets of all the solutions in a folder tree:
vs-secrets push --all vs-secrets push <path> --all
Pull solution secrets
For pulling the secrets of the solution in the current folder:
For pulling the secrets of the solution in another folder:
vs-secrets pull <solution-path>
For pulling the secrets of all the solutions in a folder tree:
vs-secrets pull --all vs-secrets pull <path> --all
Search for solutions that use secrets
You can use the tool for just searching solutions and projects that use secrets
vs-secrets search [<solution-path>] [--all]
Checking the status
status command you can check for the status of the tool. The command below checks if the encryption key has been defined and if the tool has been authorized to access GitHub Gists:
If the current folder contains a solution, the
status command will show also the synchronization status for the secrets of the solutions.
Optionally you can check the synchronization status in another folder specifying the folder path or in an entire folder tree adding the
--all parameter. Here are some examples:
vs-secrets status --all vs-secrets status c:\projects\my-project-folder vs-secrets status c:\projects --all
Clear secret settings from the local machine
If there are secrets that you need to clear locally, the
clear command erases the solution secrets from the local machine. It is equivalent to applying the command
dotnet user-secrets clear to each project in the solution.
vs-secrets clear vs-secrets clear .\my-solution.sln
Visual Studio Solution Secrets stores its configuration files in the machine's user profile folder.
The files generated by the tool are listed below.
|cipher.json||Contains the encryption key|
|github.json||Contains the access token for managing user's GitHub Gists|
|configuration.json||Contains the settings for the repository to use by default and for each solution configured with the command
|.NET||net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows|
This package has no dependencies.