In today’s cloud-native, multi-environment world, managing application settings can be a difficult task. How do you securely handle database connection strings? Switch configurations between development and production? Or avoid hardcoding secrets? .NET Core’s configuration system is here to save the day! With its unified, extensible architecture, it simplifies managing settings across JSON files, environment variables, command-line arguments and more.
In this guide, you’ll learn how to:
- Use appsettings.json and environment-specific configurations.
- Secure sensitive data with Azure Key Vault and User Secrets.
- Bind settings to strongly-typed classes for cleaner code.
- Avoid common pitfalls and optimize for scalability.
Let’s dive in!
The Configuration API: Your Gateway to Flexibility
.NET Core’s configuration revolves around the IConfiguration interface and the ConfigurationBuilder. Unlike the old web.config approach, this system aggregates data from multiple sources (JSON, environment variables, etc.) into a single unified structure.
Example: Basic Setup in Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("appsettings.json")
.AddEnvironmentVariables()
.AddCommandLine(args);
This code loads settings from appsettings.json, environment variables, and command-line arguments, with later sources overriding earlier ones.
Configuration Providers: Choose Your Sources
JSON Files
The default appsettings.json is your go-to for most settings. For environment-specific overrides, use appsettings.{Environment}.json (e.g., appsettings.Production.json).
Pro Tip: Use nested JSON objects for logical grouping:
{
"Database": {
"ConnectionString": "Server=dev;Database=MyApp;",
"Timeout": 30
}
}
Environment Variables
Ideal for production secrets (e.g., passwords, API keys). Use double underscores (__) to denote nested sections:
export Database__ConnectionString="Server=prod;Database=MyApp;"
User Secrets (Developer-Friendly Security)
Never commit sensitive data! For local development, use:
dotnet user-secrets init dotnet user-secrets set "Database:ConnectionString" "Server=localhost;..."
Azure Key Vault (Production-Grade Security)
Integrate Azure Key Vault for centralized secret management:
builder.Configuration.AddAzureKeyVault(
new Uri("https://myvault.vault.azure.net/"),
new DefaultAzureCredential()
);
Accessing Settings: From Basics to Strongly-Typed Magic
Direct Access via IConfiguration
var timeout = Configuration.GetValue<int>("Database:Timeout");
Strongly-Typed Classes (Best Practice)
Define a class:
public class DatabaseSettings {
public string ConnectionString { get; set; }
public int Timeout { get; set; }
}
Bind it in Program.cs:
builder.Services.Configure<DatabaseSettings>(
builder.Configuration.GetSection("Database")
);
Inject IOptions<DatabaseSettings> into your services:
public class MyService {
private readonly DatabaseSettings _settings;
public MyService(IOptions<DatabaseSettings> options) {
_settings = options.Value;
}
}
Why Strongly-Typed?
- Compile-time safety.
- Cleaner code with dependency injection.
Environment-Specific Mastery
Set the ASPNETCORE_ENVIRONMENT variable to control which settings load:
- Development: appsettings.Development.json + User Secrets.
- Production: appsettings.Production.json + Azure Key Vault.
Example:
ASPNETCORE_ENVIRONMENT=Production dotnet run
Best Practices for Bulletproof Configuration
- Security First
- Never store secrets in appsettings.json (even if gitignored).
- Use Azure Key Vault or AWS Secrets Manager for production.
- Validate settings with DataAnnotations:
public class DatabaseSettings {
[Required]
public string ConnectionString { get; set; }
}
- Organize for Clarity
- Group related settings under nested sections.
- Prefix environment variables (e.g., MyApp_Database__Timeout).
- Reload Dynamically
Enable live updates for JSON files:
.AddJsonFile("appsettings.json", reloadOnChange: true)
Use IOptionsSnapshot<T> to access refreshed values.
Advanced Tricks
Custom Configuration Providers
Build a provider to load settings from a database or API:
public class DatabaseConfigurationProvider : ConfigurationProvider {
// Override Load() to fetch data from your source
}
Azure App Configuration
For microservices, centralize settings with Azure’s managed service:
builder.Configuration.AddAzureAppConfiguration( "Endpoint=https://myconfig.azconfig.io;..." );
Watch Out! Common Pitfalls
- Case Sensitivity: JSON keys are case-insensitive, but environment variables vary by OS.
- Provider Order: Later providers override earlier ones. Place User Secrets and environment variables after JSON files.
- Debugging: Use Configuration.GetDebugView() to dump resolved settings.
In conclusion, .NET Core’s configuration system is a game-changer for modern apps. By leveraging environment-specific files, strongly-typed classes, and secure secret management, you can build scalable, maintainable applications ready for any deployment.
Ready to Level Up? Explore these resources:
If you liked this post then please share it with your team or follow us on TheDotNetWay for more deep dives into .NET Core, C# tips, and cloud-native development!
Structured Data FAQs:
Q: How to read environment variables in .NET Core?
A: Use Configuration.GetValue<string>(“KEY”) after adding AddEnvironmentVariables() to your ConfigurationBuilder.
Q: How to manage secrets in .NET Core?
A: Use dotnet user-secrets for development and Azure Key Vault for production.
Q: How to reload settings without restarting the app?
A: Enable reloadOnChange: true for JSON providers and inject IOptionsSnapshot<T>.