What are secrets, and why would you want to use them?
Secrets are hidden configuration values that are not checked into source control or deployed. These commonly include values such as passwords, API keys, and certificates. In .NET Core, Microsoft provides a package to set up secrets on the level of individual projects. These secrets can also be shared across projects in the same solution, allowing developers to have a single location on their local machines to store these secret configuration values.
Let’s start setting up your solution to use user secrets!
This guide assumes that you’re using the ConfigurationBuilder class provided through the
1. Updating NuGet
Right-click your solution file and select Manage NuGet Packages. Grab the NuGet package
Microsoft.Extensions.Configuration.UserSecrets and install it to any projects for which you would like to be able to use your user secrets in addition to the default configuration files. This package allows you to store a local user secrets file on a per-project basis. However, this file can be reused between projects, and we’ll set that up soon.
Common examples of projects where you may want to install the package include:
- DbUp projects
- Db seeder projects
- Common / Configuration projects
- Accessor testing and Integration testing projects
2. Generate Your User Secrets File
To generate your user secrets file, right-click on the common/config project (whichever utilizes connection strings) and select Manage User Secrets. A file named
secrets.json should be opened. Any configuration values you want to store for local use should be stored here.
You should start by copying over your typical
appsettings.json (or other similar) file and paste the contents here. You can then trim down the settings stored here to only the ones for which you need custom values. While going through this, consider which fields other people may want to have custom values for – later, we will make an example secrets file for other people to use when they set up their own user secrets in this Solution.
As implied by the name of the file, these configuration values are secrets! They will not be committed to your git repo, and you should not see the
secrets.json file show up in your pending changes.
3. Update Your Config.cs
Next, you’ll want to update your
ConfigurationBuilder to pull the secret configuration values for use in the application. Thankfully, this functionality is already built in! Look for where the
ConfigurationBuilder object is instantiated in your project(s). Between where the JSON files are added and where the environment variables are added, add this line and then update your imports if necessary:
The resulting code should look something like this:
4. Update Project Files
Next up, we will update the
UserSecretsId field in your project files. This field stores a GUID used to reference the unique
secrets.json file for each project. We want to update each project to reference the same
secrets.json file to avoid storing duplicate or mismatched configuration files.
In Step 2, we updated the contents of our new
secrets.json file. This file is linked to the project we selected in that step, but now we want to reuse this file in our other projects. Open the .csproj file for the project you used in that step. You can do this in Visual Studio by either double-clicking the project name or by right-clicking the project and selecting “Edit Project File”. You should see the
UserSecretsId field near the top of the document structure, nested under the tags: Project > PropertyGroup. It should look something like this:
UserSecretsId field and paste it into the other project files for which you installed the NuGet package in Step 1.
5. Test Changes
At this point, you should be all set up to use your user secrets, but of course you will want to verify that they actually work. The simplest way to do so is through manual testing.
For example, you can move a connection string value to your user secrets and disable it in the default configuration file. Then run your program to make sure that it can still connect to your database using the updated configuration.
6. Sharing is Caring
We also want other people in the project to be able to set this up easily, so we’ll set up an example
secrets.json file in the solution.
- Add a new file to your project and name it
example-user-secrets.jsonor something similar. If you have a documentation folder in your project, that would be a good location for this file. Overall, putting it in an easily accessible location and documenting its location is the most important part.
- Copy the contents of your
secrets.jsonfile and paste them into this example file
Note: This file will be committed to your repository! Make sure to modify any relevant secrets as necessary before committing your changes.
Lastly, you’ll want to update the project’s README to inform other users how to set up their own user secrets. Make sure to tell them to set their values based on the example secrets file we just created in Step 6 and to make any custom modifications per your project requirements.