Configuration Management

Configuration is a critical part of any distributed application. .NET Aspire provides multiple ways to configure your resources, from simple key-value pairs to complex hierarchical settings.

Configuration Sources

The AppHost builder supports all standard .NET configuration sources:

var builder = DistributedApplication.CreateBuilder(args);

// Configuration is automatically loaded from:
// 1. appsettings.json
// 2. appsettings.{Environment}.json
// 3. User secrets (in Development)
// 4. Environment variables
// 5. Command-line arguments

Accessing Configuration

Access configuration in your AppHost:

var builder = DistributedApplication.CreateBuilder(args);

// Get a single value
var apiKey = builder.Configuration["ExternalApi:ApiKey"];

// Get a section
var apiConfig = builder.Configuration.GetSection("ExternalApi");
var apiKey = apiConfig["ApiKey"];
var baseUrl = apiConfig["BaseUrl"];

Adding Configuration Sources

Add additional configuration sources:

builder.Configuration.AddJsonFile(
    "appsettings.local.json", 
    optional: true, 
    reloadOnChange: true);

Parameters

Parameters are a special type of configuration designed for deployment-time values. They can be:

Prompted for during azd deployment
Stored securely in user secrets or Azure Key Vault
Validated and typed

Creating Parameters

String Parameter
Parameter with Default
Generated Parameter

var apiKey = builder.AddParameter("api-key", secret: true);

The secret: true flag marks the parameter as sensitive, hiding it in logs and the dashboard.

var environment = builder.AddParameter("environment", defaultValue: "development");

var password = builder.AddParameter("db-password", secret: true, defaultValue: GeneratePassword());

static string GeneratePassword()
{
    // Generate a secure random password
    return Guid.NewGuid().ToString("N");
}

Using Parameters

Use parameters in resource configuration:

var apiKey = builder.AddParameter("api-key", secret: true);

var api = builder.AddProject<Projects.Api>("api")
                 .WithEnvironment("ExternalApi__ApiKey", apiKey);

Or in connection strings:

var password = builder.AddParameter("sql-password", secret: true);

var sql = builder.AddSqlServer("sql")
                 .WithEnvironment("SA_PASSWORD", password);

Parameter Resolution

Parameters are resolved from multiple sources in this order:

Command-line arguments

dotnet run --api-key "your-key-here"

Environment variables

export API_KEY="your-key-here"
dotnet run

User secrets

dotnet user-secrets set "Parameters:api-key" "your-key-here"

Configuration files

{
  "Parameters": {
    "api-key": "your-key-here"
  }
}

Default value

If no value is found and a default is provided, the default is used.

User Secrets

User secrets provide a secure way to store sensitive configuration during development.

Enabling User Secrets

Add a UserSecretsId to your AppHost project:

MyApp.AppHost.csproj

<PropertyGroup>
  <UserSecretsId>aspire-myapp-12345</UserSecretsId>
</PropertyGroup>

Or initialize it using the CLI:

dotnet user-secrets init --project MyApp.AppHost

Setting Secrets

Set secrets from the command line:

cd MyApp.AppHost
dotnet user-secrets set "Parameters:api-key" "your-secret-key"
dotnet user-secrets set "ConnectionStrings:external-db" "Server=..."

Automatic API Keys

Aspire automatically generates and stores some API keys in user secrets:

Dashboard browser token
OTLP API key for telemetry
Resource service API key

These are stored in user secrets so they remain consistent across runs without being committed to source control.

Configuring Resources

Pass configuration to resources in several ways:

Environment Variables

The most common way to configure resources:

var api = builder.AddProject<Projects.Api>("api")
                 .WithEnvironment("Logging__LogLevel__Default", "Debug")
                 .WithEnvironment("Feature__EnableBeta", "true");

See Environment Variables for more details.

Configuration Callbacks

Use callbacks for dynamic configuration:

var api = builder.AddProject<Projects.Api>("api")
                 .WithEnvironment(context =>
                 {
                     if (context.ExecutionContext.IsPublishMode)
                     {
                         context.EnvironmentVariables["ASPNETCORE_ENVIRONMENT"] = "Production";
                     }
                     else
                     {
                         context.EnvironmentVariables["ASPNETCORE_ENVIRONMENT"] = "Development";
                     }
                 });

Command-line Arguments

Pass arguments to projects and executables:

var worker = builder.AddProject<Projects.Worker>("worker")
                    .WithArgs("--queue", "high-priority");

Environment-Specific Configuration

Configure resources differently based on the environment:

var builder = DistributedApplication.CreateBuilder(args);

var isDevelopment = builder.Environment.IsDevelopment();
var isProduction = builder.Environment.IsProduction();

if (isDevelopment)
{
    // Use local Redis
    var cache = builder.AddRedis("cache");
}
else
{
    // Use Azure Cache for Redis in production
    var cache = builder.AddAzureRedis("cache");
}

Setting the Environment

Control the environment via:

Environment Variable
Command-line
launchSettings.json

export DOTNET_ENVIRONMENT=Production
dotnet run

dotnet run --environment Production

{
  "profiles": {
    "MyApp.AppHost": {
      "commandName": "Project",
      "environmentVariables": {
        "DOTNET_ENVIRONMENT": "Production"
      }
    }
  }
}

Connection String Configuration

Override resource connection strings via configuration:

var db = builder.AddPostgres("postgres")
                .AddDatabase("catalogdb");

Override the connection string:

appsettings.json

{
  "ConnectionStrings": {
    "catalogdb": "Host=production-server;Database=catalog;Username=app;Password=..."
  }
}

If a connection string is found in configuration, it takes precedence over the generated one.

Configuration in Publish Mode

When generating deployment manifests, configuration is handled differently:

var builder = DistributedApplication.CreateBuilder(args);

if (builder.ExecutionContext.IsPublishMode)
{
    // Configuration for deployment
    var externalDb = builder.Configuration.GetConnectionString("ProductionDb");
}
else
{
    // Configuration for local development
    var db = builder.AddPostgres("postgres").AddDatabase("catalogdb");
}

Common Configuration Patterns

Feature Flags

Use configuration to control features:

var enableBeta = builder.Configuration.GetValue<bool>("Features:EnableBeta");

if (enableBeta)
{
    var betaService = builder.AddProject<Projects.BetaService>("beta-service");
}

External Service URLs

Configure external services via parameters:

var paymentUrl = builder.AddParameter("payment-api-url");
var paymentApi = builder.AddExternalService("payment-api", paymentUrl);

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(paymentApi);

Database Credentials

Use parameters for credentials:

var dbPassword = builder.AddParameter("db-password", secret: true);

var db = builder.AddPostgres("postgres")
                .WithEnvironment("POSTGRES_PASSWORD", dbPassword)
                .AddDatabase("appdb");

Replica Count

Configure scaling via configuration:

var replicaCount = builder.Configuration.GetValue<int>("Api:Replicas", defaultValue: 1);

var api = builder.AddProject<Projects.Api>("api")
                 .WithReplicas(replicaCount);

Configuration Best Practices

Use Parameters for Secrets

Always use parameters with secret: true for sensitive values like API keys and passwords.

Environment-Specific Config

Use environment-specific configuration files (appsettings.Development.json, appsettings.Production.json).

User Secrets in Development

Store development secrets in user secrets, never commit them to source control.

Validate Configuration

Validate required configuration at startup to fail fast if misconfigured.

Next Steps

Environment Variables

Learn how to set environment variables

Deployment

Deploy your configured application

Get Started

Core Concepts

Building Apps

Deployment

Configuration Management

Configuration Sources

Accessing Configuration

Adding Configuration Sources

Parameters

Creating Parameters

Using Parameters

Parameter Resolution

User Secrets

Enabling User Secrets

Setting Secrets

Automatic API Keys

Configuring Resources

Environment Variables

Configuration Callbacks

Command-line Arguments

Environment-Specific Configuration

Setting the Environment

Connection String Configuration

Configuration in Publish Mode

Common Configuration Patterns

Configuration Best Practices

Use Parameters for Secrets

Environment-Specific Config

User Secrets in Development

Validate Configuration

Next Steps

Environment Variables

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Apps

Deployment

Documentation Index

​Configuration Sources

​Accessing Configuration

​Adding Configuration Sources

​Parameters

​Creating Parameters

​Using Parameters

​Parameter Resolution

​User Secrets

​Enabling User Secrets

​Setting Secrets

​Automatic API Keys

​Configuring Resources

​Environment Variables

​Configuration Callbacks

​Command-line Arguments

​Environment-Specific Configuration

​Setting the Environment

​Connection String Configuration

​Configuration in Publish Mode

​Common Configuration Patterns

​Configuration Best Practices

Use Parameters for Secrets

Environment-Specific Config

User Secrets in Development

Validate Configuration

​Next Steps

Environment Variables

Deployment

Build docs developers (and LLMs) love

Configuration Sources

Accessing Configuration

Adding Configuration Sources

Parameters

Creating Parameters

Using Parameters

Parameter Resolution

User Secrets

Enabling User Secrets

Setting Secrets

Automatic API Keys

Configuring Resources

Environment Variables

Configuration Callbacks

Command-line Arguments

Environment-Specific Configuration

Setting the Environment

Connection String Configuration

Configuration in Publish Mode

Common Configuration Patterns

Configuration Best Practices

Next Steps