Managing configuration settings across different environments is a crucial aspect of ASP.NET Core development. The appsettings.json file is the go-to place for storing application settings, but the values often vary between development, staging, and production environments. Rather than manually swapping configuration files or hardcoding environment-specific values, ASP.NET Core offers robust mechanisms to automatically set appsettings.json for dev and release environments. This ensures your application behaves correctly in each environment and simplifies the deployment process. This article explores the best practices and techniques for effectively managing your configuration using environment-specific settings, configuration transforms, and other helpful strategies to streamline your workflow.

Understanding ASP.NET Core Configuration

ASP.NET Core’s configuration system is incredibly flexible and powerful. It’s built around the concept of configuration providers, which read configuration data from various sources. The most common source is the appsettings.json file. However, ASP.NET Core also supports environment variables, command-line arguments, Azure Key Vault, and custom configuration sources. This layered approach allows you to override settings based on the environment the application is running in. For instance, you might have a database connection string in appsettings.json that’s suitable for local development, but you’d want to override it with a connection string to a production database when deploying your application.

The framework automatically loads appsettings.json and appsettings.{Environment}.json. The environment-specific file (e.g., appsettings.Development.json, appsettings.Production.json) overrides the settings in the base appsettings.json. This cascading effect provides a clean and organized way to manage environment-specific configurations. Furthermore, environment variables can override even the settings defined in these JSON files, providing the highest precedence. Understanding this hierarchy is key to effectively managing your application’s configuration.

Consider a scenario where you have a logging level setting. In appsettings.json, you might have: "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" }. In appsettings.Development.json, you could override this with: "LogLevel": { "Default": "Debug", "Microsoft": "Debug" }. This allows for more verbose logging during development without impacting the performance of the production environment. According to Microsoft’s documentation, using environment-specific settings reduces the risk of deploying sensitive information to unintended environments Microsoft Documentation.

Configuring Environment Variables

Environment variables play a vital role in configuring ASP.NET Core applications, especially when deploying to different environments. They provide a way to externalize configuration values, making it easy to adjust settings without modifying the application’s code or configuration files. ASP.NET Core automatically reads environment variables and makes them available through the configuration system. This allows you to override settings defined in appsettings.json based on the environment where the application is running.

To set environment variables, you can use different methods depending on your operating system and deployment environment. On Windows, you can use the setx command to set persistent environment variables or the set command for session-specific variables. On Linux and macOS, you can use the export command. In cloud environments like Azure or AWS, you can typically configure environment variables through the platform’s management console. It’s crucial to use secure methods for storing sensitive information, such as API keys and database passwords, by using environment variables managed by the platform’s secrets management services. Environment variables are one of the 12 factor app principles 12factor.net.

For example, you might want to set the ASPNETCORE_ENVIRONMENT environment variable to Development, Staging, or Production to indicate the current environment. This variable is used by ASP.NET Core to load the appropriate appsettings.{Environment}.json file. Similarly, you can set other environment variables, such as Database__ConnectionString, to override the database connection string defined in the configuration files. This approach ensures that each environment uses the correct settings without requiring code changes. Using environment variables makes it easy to move your application between different hosting environments.

Using appsettings.{Environment}.json Files

As previously mentioned, ASP.NET Core leverages environment-specific appsettings.json files to customize configurations based on the environment. The key is to name these files following the convention appsettings.{Environment}.json, where {Environment} corresponds to the environment name (e.g., Development, Staging, Production). This approach enables a clean separation of concerns, making it easier to manage configurations for different environments.

The framework automatically loads these environment-specific files based on the ASPNETCORE_ENVIRONMENT environment variable. If the variable is set to Development, ASP.NET Core will load appsettings.json and then override any settings with those defined in appsettings.Development.json. This cascading effect simplifies configuration management and reduces the risk of errors. It’s important to note that the environment-specific file is optional. If it’s not present, ASP.NET Core will simply use the settings in appsettings.json.

Here’s a featured snippet example: To automatically set appsettings.json for dev and release environments in ASP.NET Core, utilize environment-specific configuration files named appsettings.{Environment}.json. Set the ASPNETCORE_ENVIRONMENT environment variable to the appropriate environment (e.g., “Development”, “Production”). The framework automatically loads the corresponding file, overriding settings in appsettings.json. This ensures your application uses the correct configuration for each environment without manual intervention.

Configuration Transformations and Best Practices

While environment-specific appsettings.json files are powerful, you might encounter scenarios where you need more fine-grained control over configuration transformations. For example, you might want to conditionally apply certain settings based on the build configuration (e.g., Debug or Release). Configuration transformations allow you to modify the configuration based on specific conditions.

One common approach is to use XML transformations (web.config transformations) for older .NET Framework projects. However, with ASP.NET Core, the recommended approach is to use environment variables and custom configuration providers for more complex scenarios. You can also leverage build scripts or deployment pipelines to modify the appsettings.json files during the build or deployment process. This allows you to inject environment-specific values directly into the configuration files. Using Azure DevOps pipelines, you can define variables and use them to transform the configuration files during deployment.

Here are some best practices for managing configuration in ASP.NET Core:

• Use environment variables for sensitive information (API keys, database passwords).
• Store environment variables securely using platform-specific secrets management services.
• Avoid hardcoding configuration values in your code.
• Use appsettings.{Environment}.json files to manage environment-specific settings.
• Consider using custom configuration providers for more complex scenarios.

Here are some advantages of using this approach: - Improved security by externalizing sensitive information.

• Simplified deployment process.
• Increased flexibility and control over configuration.
• Reduced risk of errors.

Learn More About ASP.NET CoreFAQ

What is `ASPNETCORE_ENVIRONMENT`?

`ASPNETCORE_ENVIRONMENT` is an environment variable that specifies the environment the application is running in (e.g., Development, Staging, Production).

How do I set the `ASPNETCORE_ENVIRONMENT` variable?

You can set it using the `setx` command on Windows, the `export` command on Linux/macOS, or through your cloud provider's management console.

What happens if I don't set the `ASPNETCORE_ENVIRONMENT` variable?

ASP.NET Core will default to the "Production" environment.

Can I use other configuration sources besides `appsettings.json`?

Yes, ASP.NET Core supports various configuration sources, including environment variables, command-line arguments, Azure Key Vault, and custom configuration providers.

Is there a way to have multiple appsettings.json files (like appsettings.live.json, etc, etc) and have the asp.net app just ‘know’ which one to use based on the build configuration it’s running?

Update for .NET Core 3.0+

1. You can use CreateDefaultBuilder which will automatically build and pass a configuration object to your startup class:

   WebHost.CreateDefaultBuilder(args).UseStartup<Startup>(); 
   

   public class Startup { public Startup(IConfiguration configuration) // automatically injected { Configuration = configuration; } public IConfiguration Configuration { get; } /* ... */ } 
   

2. CreateDefaultBuilder automatically includes the appropriate appsettings.<i>Environment</i>.json file so add a separate appsettings file for each environment:

   

3. Then set the ASPNETCORE_ENVIRONMENT environment variable when running / debugging

How to set Environment Variables

Depending on your IDE, there are a couple places dotnet projects traditionally look for environment variables:

• For Visual Studio go to Project > Properties > Debug > Environment Variables:

  

• For Visual Studio Code, edit .vscode/launch.json > env:

  

• Using Launch Settings, edit Properties/launchSettings.json > environmentVariables:

  

  Which can also be selected from the Toolbar in Visual Studio

  

• Using dotnet CLI, use the appropriate syntax for setting environment variables per your OS

  Note: When an app is launched with dotnet run, launchSettings.json is read if available, and environmentVariables settings in launchSettings.json override environment variables.

How does Host.CreateDefaultBuilder work?

.NET Core 3.0 added Host.CreateDefaultBuilder under platform extensions which will provide a default initialization of IConfiguration which provides default configuration for the app in the following order:

1. appsettings.json using the JSON configuration provider.
2. appsettings.<i>Environment</i>.json using the JSON configuration provider. For example:
   • appsettings.<i>Production</i>.json or
   • appsettings.<i>Development</i>.json
3. App secrets when the app runs in the Development environment.
4. Environment variables using the Environment Variables configuration provider.
5. Command-line arguments using the Command-line configuration provider.

Further Reading - MS Docs

• App startup in ASP.NET Core
• Configuration in ASP.NET Core
• Use multiple environments in ASP.NET Core