Intro

Modern .NET applications offer a convenient default configuration pipeline, but many teams struggle with its intricacies. A common problem arises when using appsettings.json\ for configuration: developers often modify it with local development settings and inadvertently commit these changes to version control. This can lead to unintended consequences, such as accidentally enabling verbose logging in production or, more seriously, exposing sensitive information like API keys, requiring cleanup of the Git history. It's crucial to understand the configuration pipeline to avoid these pitfalls.

TLDR

Avoid modifying appsettings.json\ for local development to prevent accidentally committing changes to version control. Instead, use .NET User Secrets. Initialize User Secrets via CLI (dotnet user-secrets init\) or IDE tools. Secrets are stored in a secrets.json\ file in a user-specific directory. Manage secrets using CLI (set\, remove\, clear\, list\) or by directly editing secrets.json\. This keeps local configurations separate and prevents issues in production.

So what should I do?

You may say, “But my team has always done it this way, and now you’re telling me to stop. What the heck am I supposed to do?.”

Good question - .NET User Secrets is the answer.

By default, when the .NET environment is set to development the pipeline will pull in and prioritize a special sort of appsettings file defined by a GUID in your project file. The GUID and corresponding secrets.json file gets created when you request to edit it from your IDE.

Important note

Its important to note that user secrets management is specifically designed for local development and not production. The pipeline does its best to prevent this by only using this method of configuration when the proper environment variables are present, but there are ways around it.

Getting started

Initializing user secrets in your project:

.NET CLI

dotnet user-secrets init

Jetbrains Rider

Right click project > Tools > .NET User Secrets

VSCode (w/ C# Dev Kit)

Right click project > Manage User Secrets

Visual Studio

Right click project > Manage User Secrets

What happens after initialization?

If you open your .csproj file after initializing user secrets, you will notice some new info:

This GUID value corresponds to a directory containing a single file called secrets.json buried in your user level application data directories.

Windows

%APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json

Linux/Mac

~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

You can think of this file as a local version of the appsettings.json file that will override any values defined in your project’s baseline appsettings.json file. This allows you to have your own personal configuration without affecting the baseline configuration for the rest of your team.

Managing secrets:

If you’re a visual person and prefer just editing the file, your IDE will open the file for you using one of the methods defined above depending on your IDE. From there you can just edit everything like you would the normal appsettings file.

If your preferred method of doing things in your .NET projects is via the CLI tooling, managing the values in your secrets file is pretty straightforward.

Setting a secret

dotnet user-secrets set "ExistingKeyName" "LocalEnvValue"

// or for nested config objects

dotnet user-secrets set "ExistingKeyParent:NestedKey" "LocalEnvValue"

Removing a secret

dotnet user-secrets remove "KeyToRemove"

Removing all of the secrets

dotnet user-secrets clear

Listing all of the secrets

dotnet user-secrets list

Wrapping up

This is not the only option you have in the spirit of not modifying the baseline appsettings file for local development, but I feel that it's a great one and easy to adopt into your development workflow. This post is by no means supposed to be an exhaustive explanation of this feature, feel free to dive deeper into the msdn documentation here (https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets)