ASP.NET Core (Not That Secret) User Secrets Explained

In my previous post, Individual developer settings in ASP.NET Core, I showed you how to create per-developer settings using Windows environment variables. While environment variables are both fast to produce and script friendly, there is a better approach available in ASP.NET Core called User Secrets.

Unlike environment variables, user secrets are placed in a settings file similar to appsettings.json. Having similar structured off-project settings is great when you need to copy keys and values between files and there is support for adding, removing and listing values as I will show you later in this post.

To understand user secrets, let's resume the example from the previous post. In there I had an appsettings.json file looking like this,

In order to override the AppSettings:ConnectionString setting on individual machines, each user needs to add a user secret with the same name. The easiest approach is to right-click the project and select Manage User Secrets:

This creates and opens a new empty JSON file named secrets.json. The file is placed beneath C:\Users\<username>\AppData\Roaming\Microsoft\UserSecrets\<id> where <username> matches your Windows user and <id> is a randomly generated GUID. The important thing to notice here is that the file is located outside your project directory. In order to "bind" the secrets.json file location to your project, Visual Studio added a bit of markup to the csproj file:

In case you want to override the AppSettings:ConnectionString setting, add a similar structure to the secrets.json file:

I recommend the second approach since you probably only need to override a few settings and since using dotnet from the command line to modify the file, will collapse settings anyway.

While we are already talking about using dotnet to administrate user secrets, let me show you the three commands you will need to learn,

The list command shows you a complete list of keys and values in the secrets.json file.

This command set the AppSettings:ConnectionString key to the specified value.

As you already guessed, this command removes the AppSettings:ConnectionString key and value.

With this knowledge, you are ready to rock and roll. As long as you initialize your web application using the WebHost.CreateDefaultBuilder-method, ASP.NET Core automatically pick up your configuration from the secrets.json file. If you initialize your application manually, make sure to call the AddUserSecrets-method,