Manage .NET user secrets

Working with secure keys in .NET requires a careful balance of convenience and safety. It is easy to add a production database connection string to your application's configuration for quick testing, only to accidentally check it into source control. .NET User Secrets provide a straightforward way to store sensitive information during local development, significantly reducing the chance of exposing secrets.

The .NET Secrets Manager

Starting with .NET Core 3.1, the SDK includes the Secrets Manager — a command-line utility that creates a unique store for project-related secrets. When initialized, .NET stores your project secrets in a user-specific directory outside the current project. Depending on your host operating system, the location differs:

Windows: %APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json
Linux/macOS: ~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

Keeping secrets outside your project reduces the chance of accidentally committing them to source control. The folder containing your secrets is unique to each project and uses a UserSecretsId MSBuild element in your project file. The value can be any unique identifier, and .NET templates typically initialize it for you.

You can also use MSBuild properties as your UserSecretsId value. For example, you can use the ProjectName property. Just make sure your project names are unique across your development environment.

Initialize user secrets

If your project is missing the UserSecretsId element, you can initialize it in two ways.

Initialize from the terminal

Open the terminal in JetBrains Rider and navigate to the project directory.
Run the following command:
dotnet user-secrets init

Initialize from the Solution Explorer

In the Solution Explorer, right-click the project node.
Navigate to Tools | .NET User Secrets.
JetBrains Rider will initialize the project by adding a UserSecretsId element to the project file and open the secrets.json file in your user directory.

Most project templates in .NET already have User Secrets initialized, which means their secret values are ready for you to use immediately.

Manage secrets

Once you have initialized your project, you can manage your secrets by editing the secrets.json file. This file is similar to the appsettings.json configuration file used in many .NET projects. You can have complex structured configuration data, but typically you will find key-value pairs in these files.

To open the secrets.json file, right-click the project in the Solution Explorer and choose Tools | .NET User Secrets.

When editing the secrets.json file, make sure that you follow the JSON format. You may get a warning about editing a non-project file, which is there to prevent you from accidentally editing files outside your project and source control. Click OK to allow file editing.

Use user secrets in a console application

Console application projects typically lack configuration dependencies, so you need to add them manually.

Create a new Console Application project.
Add the Microsoft.Extensions.Configuration.UserSecrets NuGet package using the NuGet tool window. This dependency allows you to create a configuration instance and load your user secrets file.
Initialize the project using the Tools | .NET User Secrets context menu element.
Open the secrets.json file and add your secret values. For example:
{ "Name": "World" }
In Program.cs, use the ConfigurationBuilder type to build an IConfiguration instance and access your user secrets:
using Microsoft.Extensions.Configuration; var configuration = new ConfigurationBuilder() .AddUserSecrets<Program>() .Build(); Console.WriteLine($"Hello, {configuration["Name"]}!");

An essential part of the AddUserSecrets call is its generic type argument. The UserSecretsId MSBuild property value is added to your assembly and accessed using the UserSecretsIdAttribute custom attribute. Without this attribute's value, .NET would be unable to find the location of your user secrets file.

User secrets in ASP.NET Core and Worker Services

Most ASP.NET Core and Worker Service project templates already include user secrets by default. Their secret values are ready for you to use immediately.

ASP.NET Core applications typically start with the following line of code:

var builder = WebApplication.CreateBuilder(args);

The call to WebApplication.CreateBuilder builds your IConfiguration instance. The default configuration providers include JSON, environment variables, command line arguments, and user secrets.

Unlike a console application, the host builder registers user secrets only if your application runs in development mode. Developers don't usually use user secrets outside local development scenarios. There are other mechanisms to provide secrets to your application that are easier to manage in a production environment.

Security considerations

The secrets.json file is not encrypted and is still accessible by any bad actor that has compromised your machine. However, user secrets help reduce the risk of accidentally adding secrets into source control.

It is still essential to follow good security habits like rotating keys and limiting access to sensitive information to those who require it.

15 April 2026