Aspnet Configuration
title: ASP.NET Core Configuration — Complete Guide to App Configuration description: 'Learn ASP.NET Core configuration: appsettings.json, environment variables, user secrets, Options pattern, connection strings, and multi-environment configuration.' date: 2026-06-28 lastmod: 2026-06-28 weight: 21 tags: [backend, aspnet]
ASP.NET Core configuration system reads settings from JSON files, environment variables, user secrets, and command-line arguments, merging them into a single key-value store.
## What You'll Learn
By the end of this tutorial, you'll configure apps with appsettings.json, use environment-specific overrides, access connection strings, implement the Options pattern, and secure secrets.
## Real-World Use
A deployment pipeline sets database connection strings via environment variables. Development uses user secrets. Staging overrides appsettings.Staging.json. Production uses environment variables.
## Configuration Learning Path
```mermaid
flowchart LR
A[DI] --> B[Config]
B --> C[EF Core]
C --> D[Migrations]
D --> E[Auth]
B --> F{You Are Here}
style F fill:#f90,color:#fff
appsettings.json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"ConnectionStrings": {
"DefaultConnection": "Server=localhost;Database=MyApp;Trusted_Connection=True;TrustServerCertificate=True"
},
"EmailSettings": {
"SmtpServer": "smtp.example.com",
"Port": 587,
"Username": "noreply@example.com",
"EnableSsl": true
},
"FeatureFlags": {
"NewCheckout": true,
"BetaDashboard": false
}
}
Accessing Configuration
var builder = WebApplication.CreateBuilder(args);
// builder.Configuration is ready after this line
// Direct access
var dbConn = builder.Configuration.GetConnectionString("DefaultConnection");
var smtpServer = builder.Configuration["EmailSettings:SmtpServer"];
var newCheckout = builder.Configuration.GetValue<bool>("FeatureFlags:NewCheckout");
// Options pattern
builder.Services.Configure<EmailSettings>(
builder.Configuration.GetSection("EmailSettings"));
// Named options
builder.Services.Configure<EmailSettings>("Primary",
builder.Configuration.GetSection("EmailSettings"));
Environment-Specific Config
{
"Logging": {
"LogLevel": {
"Default": "Debug", // Verbose in development
"Microsoft": "Information"
}
}
}
// Order of precedence (last wins):
// 1. appsettings.json
// 2. appsettings.{Environment}.json
// 3. User Secrets (Development only)
// 4. Environment variables
// 5. Command-line arguments
// Set environment
export ASPNETCORE_ENVIRONMENT=Production
// Or in launchSettings.json
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
User Secrets
# Initialize (creates a secrets.json file)
dotnet user-secrets init
# Set secrets
dotnet user-secrets set "DbPassword" "my-secret-password"
dotnet user-secrets set "EmailSettings:Password" "smtp-pass"
# List secrets
dotnet user-secrets list
# Remove secret
dotnet user-secrets remove "DbPassword"
# Clear all
dotnet user-secrets clear
Strongly-Typed Options
// Model
public class EmailSettings
{
public string SmtpServer { get; set; } = "";
public int Port { get; set; } = 587;
public string Username { get; set; } = "";
public string Password { get; set; } = "";
public bool EnableSsl { get; set; } = true;
}
// Registration
builder.Services.Configure<EmailSettings>(
builder.Configuration.GetSection("EmailSettings"));
// Usage
public class EmailService
{
private readonly EmailSettings _settings;
public EmailService(IOptions<EmailSettings> options)
{
_settings = options.Value;
}
public async Task SendAsync(string to, string subject, string body)
{
using var client = new SmtpClient(_settings.SmtpServer, _settings.Port);
// ...
}
}
Common Mistakes
1. Hardcoding Configuration
Connection strings, API keys, and URLs in code prevent environment-specific deployment. Always use configuration.
2. Committing Secrets to Git
Add appsettings.*.local.json and secrets to .gitignore. Use User Secrets for development.
3. Accessing Configuration Mid-Request Directly
Don't inject IConfiguration into services. Use the Options pattern with strongly-typed classes.
4. Ignoring Configuration Reload
IOptionsSnapshot reloads on each request. IOptionsMonitor allows reactive reloading.
5. Flat Configuration Keys
Use hierarchical keys (EmailSettings:SmtpServer) instead of flat keys (SmtpServer) for organization.
Practice Questions
1. What is the configuration source order in ASP.NET Core?
appsettings.json -> appsettings.{env}.json -> User Secrets -> Environment variables -> Command-line args.
2. How do you read a connection string?
builder.Configuration.GetConnectionString("DefaultConnection") reads from ConnectionStrings section.
3. What is the Options pattern?
Bind configuration sections to strongly-typed classes using IOptions
4. How do you handle secrets in development?
Use dotnet user-secrets for sensitive data during development. These are stored outside the project directory.
5. Challenge: Configure a multi-environment app with different database connections per environment.
// appsettings.Production.json
{ "ConnectionStrings": { "DefaultConnection": "Server=prod-db;Database=app;..." } }
// appsettings.Staging.json
{ "ConnectionStrings": { "DefaultConnection": "Server=staging-db;Database=app;..." } }
FAQ
Mini Project: Multi-Environment Config
Create a configuration that reads database connection from environment in production and from appsettings in development.
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
.AddJsonFile("appsettings.json", optional: false)
.AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
.AddEnvironmentVariables();
var connStr = builder.Configuration.GetConnectionString("DefaultConnection")
?? throw new InvalidOperationException("No connection string configured");
What's Next
ASP.NET Core Entity Framework ASP.NET Core Migrations
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro