How to Set Up User Secrets for .NET Core Projects in Visual Studio

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!

0. Assumptions

This guide assumes that you’re using the ConfigurationBuilder class provided through the Microsoft.Extensions.Configuration namespace.

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:

.AddUserSecrets(Assembly.GetExecutingAssembly(), true)

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:

Copy 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.

1. Add a new file to your project and name it example-user-secrets.json or 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.
2. Copy the contents of your secrets.json file 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.

7. Documentation

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.