Introducción

Toda aplicación .NET necesita configuraciones — connection strings, API keys, feature flags, URLs de servicios externos. Lo que muchos desarrolladores no perciben es que .NET 8+ tiene un pipeline interno de configuración sofisticado, donde múltiples providers se cargan en un orden específico, y el último en registrar un valor gana. Entender este orden es la diferencia entre una aplicación que funciona “por suerte” y una que funciona por diseño.

En este artículo, voy a explorar cómo WebApplication.CreateBuilder() arma el pipeline de configuración, el orden exacto de los Add... en el ConfigurationBuilder, cómo los secrets de Docker y Podman se integran con .NET sin código adicional, y cómo IOptions<T>, IOptionsSnapshot<T> e IOptionsMonitor<T> reaccionan a cambios de configuración en tiempo de ejecución. Si alguna vez tuviste un bug causado por una variable de entorno que sobrescribió tu appsettings.json — o al revés — este artículo va a aclarar definitivamente lo que ocurre por debajo.

💡 Consejo: Este artículo usa .NET 8+ como referencia, pero el pipeline de configuración es fundamentalmente el mismo desde .NET 6. Las novedades de .NET 8 son refinamientos, no cambios estructurales.


Qué Ocurre en WebApplication.CreateBuilder()

Cuando llamas a WebApplication.CreateBuilder(args), .NET ejecuta internamente una secuencia precisa de registros en el ConfigurationBuilder. Este es el orden predeterminado de los providers de configuración:

1
2
3
4
5
6
7
8
9
var builder = WebApplication.CreateBuilder(args);

// Internamente, .NET 8 registra los providers en este orden:
// 1. ChainedConfigurationSource  (configuración del host)
// 2. appsettings.json             (reloadOnChange: true)
// 3. appsettings.{Environment}.json (reloadOnChange: true)
// 4. User Secrets                 (solo en Development)
// 5. Environment Variables
// 6. Command-line arguments

ℹ️ Información: La regla es simple — el último provider en registrar un valor sobrescribe a los anteriores. Por eso las variables de entorno ganan sobre appsettings.json, y los argumentos de línea de comandos ganan sobre todo.

El Orden Completo y Por Qué

OrdenProviderreloadOnChangeCuándo se registra
1ChainedConfigurationSource—Configuraciones heredadas del host (rara vez se manipulan)
2appsettings.json✅ SíSiempre — valores predeterminados de la aplicación
3appsettings.{Environment}.json✅ SíSiempre — sobrescribe valores por entorno
4User Secrets (secrets.json)❌ NoSolo cuando ASPNETCORE_ENVIRONMENT=Development
5Environment Variables❌ NoSiempre — variables del sistema/contenedor
6Command-line arguments❌ NoSiempre — argumentos pasados por CLI

Esta jerarquía es intencional: los valores más seguros y específicos tienen prioridad. appsettings.json contiene los valores predeterminados; el entorno (Development, Staging, Production) los refina; los secrets protegen datos sensibles en dev; y las variables de entorno son el estándar en contenedores.


appsettings.json y Entornos

appsettings.json es el punto de partida — contiene los valores predeterminados de la aplicación. El archivo de entorno (appsettings.{Environment}.json) no necesita contener todas las claves — solo las que quieres sobrescribir:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// appsettings.json — valores predeterminados
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "Default": "Host=localhost;Database=meudb;Username=dev;Password=dev123"
  },
  "App": {
    "NomeExibicao": "Minha Aplicação",
    "MaxItensPorPagina": 50,
    "HabilitarCache": true
  }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// appsettings.Production.json — sobrescribe solo lo necesario
{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "App": {
    "MaxItensPorPagina": 100,
    "HabilitarCache": true
  }
}

⚠️ Atención: appsettings.Production.json nunca debe contener connection strings de producción ni secrets. Esos valores deben venir de variables de entorno (contenedores) o key vaults (cloud). El archivo de producción solo sirve para ajustar comportamientos como nivel de log, paginación y flags.

Cómo .NET Determina el Entorno

La variable ASPNETCORE_ENVIRONMENT (o DOTNET_ENVIRONMENT para aplicaciones no web) define qué appsettings.{Environment}.json se cargará. Los valores convencionales son:

1
2
3
4
5
6
7
8
# En desarrollo (predeterminado en Visual Studio y dotnet run)
ASPNETCORE_ENVIRONMENT=Development

# En staging
ASPNETCORE_ENVIRONMENT=Staging

# En producción
ASPNETCORE_ENVIRONMENT=Production
1
2
3
4
5
6
7
// .NET usa IHostEnvironment para exponer el entorno actual
app.MapGet("/info", (IHostEnvironment env) => new
{
    Ambiente = env.EnvironmentName,       // "Development", "Production", etc.
    IsDev = env.IsDevelopment(),
    IsProd = env.IsProduction()
});

dotnet user-secrets — Protegiendo Datos en Desarrollo

El mecanismo de User Secrets resuelve un problema real: desarrolladores que hacen commit de appsettings.json con connection strings de base de datos, API keys o credenciales. Los secrets se almacenan fuera del repositorio, en el perfil del usuario del sistema operativo.

Cómo Funciona

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Inicializar secrets en el proyecto (crea UserSecretsId en el .csproj)
dotnet user-secrets init --project src/MeuProjeto.API

# Agregar un secret
dotnet user-secrets set "ConnectionStrings:Default" "Host=prod-server;Database=producao;Password=S3nh@F0rt3!" --project src/MeuProjeto.API

# Listar todos los secrets
dotnet user-secrets list --project src/MeuProjeto.API

# Eliminar un secret
dotnet user-secrets remove "ConnectionStrings:Default" --project src/MeuProjeto.API

Dónde Se Almacenan

Sistema OperativoRuta
Windows%APPDATA%\Microsoft\UserSecrets\<UserSecretsId>\secrets.json
Linux/macOS~/.microsoft/usersecrets/<UserSecretsId>/secrets.json

El UserSecretsId es un GUID generado automáticamente en el .csproj:

1
2
3
<PropertyGroup>
  <UserSecretsId>a1b2c3d4-e5f6-7890-abcd-ef1234567890</UserSecretsId>
</PropertyGroup>

💡 Consejo: secrets.json tiene el mismo formato que appsettings.json. Internamente, .NET registra un JsonConfigurationProvider apuntando a ese archivo — por eso cualquier clave de appsettings.json puede sobrescribirse con un secret. Para entender cómo User Secrets se integran con EF Core Migrations en proyectos multicapa, consulta EF Core Migrations: Multiproyecto, Secrets y Scaffolding.

User Secrets NO Funcionan en Producción

El provider de User Secrets se registra solo cuando el entorno es Development:

1
2
3
4
5
// Código interno de WebApplicationBuilder (simplificado):
if (hostEnvironment.IsDevelopment())
{
    configBuilder.AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true);
}

En producción, los valores deben venir de variables de entorno (contenedores), key vaults (Azure Key Vault, AWS Secrets Manager) o Docker/Podman secrets.


Variables de Entorno — El Estándar en Contenedores

Las variables de entorno son el provider más importante en entornos contenerizados. Sobrescriben tanto appsettings.json como appsettings.{Environment}.json.

Convención de Nombres

.NET convierte el separador jerárquico : en __ (doble guion bajo) en las variables de entorno:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// appsettings.json
{
  "ConnectionStrings": {
    "Default": "..."
  },
  "App": {
    "Email": {
      "SmtpHost": "smtp.mailtrap.io"
    }
  }
}
1
2
3
# Variable de entorno equivalente (Linux/Docker/Podman)
ConnectionStrings__Default="Host=prod-server;Database=producao;Password=S3nh@F0rt3!"
App__Email__SmtpHost="smtp.sendgrid.net"
1
2
3
4
5
6
7
8
9
# docker-compose.yml / podman-compose.yml
services:
  api:
    image: minha-api:latest
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ConnectionStrings__Default=Host=db;Database=producao;Password=${DB_PASSWORD}
      - App__Email__SmtpHost=smtp.sendgrid.net
      - App__MaxItensPorPagina=200

⚠️ Atención: En Linux, las variables de entorno distinguen mayúsculas y minúsculas. ConnectionStrings__Default es diferente de CONNECTIONSTRINGS__DEFAULT. .NET trata ambas correctamente gracias al provider de Environment Variables, pero mantén la convención PascalCase con __ por consistencia.

Prefijo para Filtrado

En entornos compartidos, usa un prefijo para evitar colisiones:

1
2
3
4
5
// Cargar solo variables con el prefijo MEUAPP_
builder.Configuration.AddEnvironmentVariables(prefix: "MEUAPP_");

// MEUAPP_ConnectionStrings__Default se mapeará a ConnectionStrings:Default
// (el prefijo se elimina automáticamente)

Docker y Podman Secrets — El Enfoque Seguro para Contenedores

Las variables de entorno resuelven muchos escenarios, pero tienen una limitación de seguridad: son visibles con docker inspect, podman inspect, /proc/*/environ y logs de depuración. Para datos realmente sensibles (contraseñas de base de datos, API keys, certificados), Docker y Podman ofrecen secrets — archivos montados en memoria (tmpfs) dentro del contenedor.

Cómo Funcionan los Secrets en Docker y Podman

Los secrets se almacenan en el host y se montan como archivos de solo lectura en el contenedor, en /run/secrets/<nombre>:

1
2
3
4
5
# Docker — crear un secret
echo "S3nh@F0rt3!Pr0duc40" | docker secret create db_password -

# Docker Compose — definir secrets
echo "S3nh@F0rt3!Pr0duc40" > ./secrets/db_password.txt
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# docker-compose.yml
services:
  api:
    image: minha-api:latest
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
    secrets:
      - db_password
      - api_key
    volumes:
      # alternativa: montar manualmente
      # - ./secrets:/run/secrets:ro

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    file: ./secrets/api_key.txt
1
2
3
4
5
6
7
# Podman — crear un secret
echo "S3nh@F0rt3!Pr0duc40" | podman secret create db_password -

# Podman — usar el secret en el contenedor
podman run --secret db_password -e ASPNETCORE_ENVIRONMENT=Production minha-api:latest

# El secret queda disponible en /run/secrets/db_password dentro del contenedor

Integrando Docker/Podman Secrets con .NET

.NET no tiene un provider nativo para /run/secrets/. La integración se hace mediante el key-per-file provider — un provider de configuración que lee cada archivo de un directorio como un par clave-valor, donde el nombre del archivo es la clave y el contenido es el valor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var builder = WebApplication.CreateBuilder(args);

// Registrar el provider key-per-file para Docker/Podman secrets
var secretsPath = "/run/secrets";
if (Directory.Exists(secretsPath))
{
    builder.Configuration.AddKeyPerFile(
        directoryPath: secretsPath,
        optional: true,
        filePrefix: "" // sin prefijo — usa el nombre del archivo como clave
    );
}

Con esta configuración, un archivo /run/secrets/ConnectionStrings__Default con el contenido Host=db;Database=prod;Password=S3nh@! se mapeará a Configuration["ConnectionStrings:Default"].

ℹ️ Información: AddKeyPerFile aplica la convención __ → : automáticamente, igual que las variables de entorno. Así, un archivo llamado App__Email__SmtpHost será accesible como Configuration["App:Email:SmtpHost"].

Convención de Nombres para Secrets

Para mantener compatibilidad con la jerarquía de .NET:

Secret (nombre del archivo)Clave en ConfigurationContenido del archivo
ConnectionStrings__DefaultConnectionStrings:DefaultHost=db;Database=prod;Password=S3nh@!
App__Email__SmtpHostApp:Email:SmtpHostsmtp.sendgrid.net
App__JwtSecretKeyApp:JwtSecretKeyminha-chave-jwt-super-secreta-256bits

Podman Secrets vs Docker Secrets

CaracterísticaDocker SecretsPodman Secrets
RequisitoDocker Swarm modeFunciona sin Swarm (rootless)
AlmacenamientoRaft log (cifrado)Directorio local (cifrable)
Montaje/run/secrets/ (tmpfs)/run/secrets/ (tmpfs)
¿Visible en inspect?❌ No❌ No
¿Visible en /proc?❌ No❌ No
CLIdocker secret createpodman secret create
Composedocker compose con secrets:podman-compose con secrets:

💡 Consejo: Si tu aplicación corre en Podman rootless (como se describe en el deploy de este blog), prefiere Podman secrets con AddKeyPerFile. No quedan expuestos en logs, inspect ni variables de entorno — una capa extra de seguridad sin complejidad adicional.


El Orden Final Completo (con Docker Secrets)

Al agregar todos los providers, incluidos los Docker/Podman secrets, el orden completo del pipeline queda así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
var builder = WebApplication.CreateBuilder(args);

// Providers registrados automáticamente por .NET 8:
// 1. ChainedConfigurationSource
// 2. appsettings.json                  (reloadOnChange: true)
// 3. appsettings.{Environment}.json    (reloadOnChange: true)
// 4. User Secrets                      (solo Development)
// 5. Environment Variables
// 6. Command-line arguments

// Provider adicional — Docker/Podman secrets (REGISTRAR DESPUÉS de los defaults):
if (Directory.Exists("/run/secrets"))
    builder.Configuration.AddKeyPerFile("/run/secrets", optional: true);

// Orden final de prioridad (el último gana):
// 1.  appsettings.json               ← menor prioridad
// 2.  appsettings.Production.json
// 3.  User Secrets (solo Dev)
// 4.  Environment Variables
// 5.  Command-line args
// 6.  Docker/Podman Secrets           ← mayor prioridad (si se registra al final)

Diagrama del pipeline de configuración de .NET 8+ con el orden de carga de providers y la prioridad de sobrescritura entre appsettings, secrets, variables de entorno y Docker secrets

⚠️ Atención: La posición donde llamas a AddKeyPerFile define su prioridad. Si quieres que las variables de entorno tengan prioridad sobre los Docker secrets, registra AddKeyPerFile antes de AddEnvironmentVariables. La regla siempre es: el último registrado gana.


IOptions<T> y Sus Variantes

Con el pipeline armado, el siguiente paso es consumir las configuraciones de forma tipada. .NET ofrece tres interfaces en el namespace Microsoft.Extensions.Options, y cada una tiene un comportamiento distinto en cuanto a ciclo de vida y recarga:

Registro de Configuración Tipada

1
2
3
4
5
6
// Program.cs
builder.Services.Configure<AppConfig>(
    builder.Configuration.GetSection("App"));

builder.Services.Configure<EmailConfig>(
    builder.Configuration.GetSection("App:Email"));
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// AppConfig.cs — clase POCO sin dependencia del framework
public sealed class AppConfig
{
    public string NomeExibicao { get; set; } = string.Empty;
    public int MaxItensPorPagina { get; set; } = 50;
    public bool HabilitarCache { get; set; }
}

public sealed class EmailConfig
{
    public string SmtpHost { get; set; } = string.Empty;
    public int SmtpPort { get; set; } = 587;
    public string SmtpUsername { get; set; } = string.Empty;
}

IOptions<T> — Singleton, Sin Recarga

1
2
3
4
5
6
public class MeuServico(IOptions<AppConfig> options)
{
    private readonly AppConfig _config = options.Value;

    public int ObterMaxItens() => _config.MaxItensPorPagina;
}
CaracterísticaComportamiento
Ciclo de vidaSingleton (Value se calcula una vez y queda en caché para siempre)
Recarga❌ No recarga — si appsettings.json cambia, Value mantiene el valor original
Cuándo usarConfiguraciones que nunca cambian durante la vida de la aplicación
Registroservices.Configure<T>(section)

IOptionsSnapshot<T> — Scoped, Recarga por Request

1
2
3
4
5
6
public class MeuServico(IOptionsSnapshot<AppConfig> options)
{
    private readonly AppConfig _config = options.Value;

    public int ObterMaxItens() => _config.MaxItensPorPagina;
}
CaracterísticaComportamiento
Ciclo de vidaScoped (nuevo valor en cada request HTTP / scope de DI)
Recarga✅ Recarga — si appsettings.json cambia, el próximo request ya ve el nuevo valor
Cuándo usarAPIs y web apps donde la configuración puede cambiar sin reinicio
Restricción⚠️ No puede inyectarse en servicios Singleton
Registroservices.Configure<T>(section) (mismo registro)

IOptionsMonitor<T> — Singleton con Notificación

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
public class MeuServico : IDisposable
{
    private readonly IDisposable? _changeListener;
    private AppConfig _config;

    public MeuServico(IOptionsMonitor<AppConfig> monitor)
    {
        _config = monitor.CurrentValue;

        // Recibir notificación cuando cambie la configuración
        _changeListener = monitor.OnChange(novaConfig =>
        {
            _config = novaConfig;
            Console.WriteLine($"¡Config modificada! MaxItens ahora es {novaConfig.MaxItensPorPagina}");
        });
    }

    public int ObterMaxItens() => _config.MaxItensPorPagina;

    public void Dispose() => _changeListener?.Dispose();
}
CaracterísticaComportamiento
Ciclo de vidaSingleton (puede inyectarse en cualquier servicio)
Recarga✅ Recarga — CurrentValue siempre devuelve el valor más reciente
Notificación✅ OnChange() permite reaccionar a cambios en tiempo real
Cuándo usarServicios Singleton que necesitan reaccionar a cambios de configuración
Registroservices.Configure<T>(section) (mismo registro)

Comparativa Rápida

InterfazCiclo de vidaReloadNotificación¿Usar en Singleton?
IOptions<T>Singleton❌❌✅
IOptionsSnapshot<T>Scoped✅ (por request)❌❌
IOptionsMonitor<T>Singleton✅ (en tiempo real)✅ OnChange()✅

Named Options — Múltiples Instancias de la Misma Configuración

Cuando tienes múltiples configuraciones del mismo tipo (ej.: varios proveedores de email, múltiples bases de datos):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "EmailProviders": {
    "Transacional": {
      "SmtpHost": "smtp.sendgrid.net",
      "SmtpPort": 587
    },
    "Marketing": {
      "SmtpHost": "smtp.mailchimp.com",
      "SmtpPort": 587
    }
  }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// Registrar como Named Options
builder.Services.Configure<EmailConfig>("Transacional",
    builder.Configuration.GetSection("EmailProviders:Transacional"));
builder.Services.Configure<EmailConfig>("Marketing",
    builder.Configuration.GetSection("EmailProviders:Marketing"));

// Consumir vía IOptionsSnapshot (o IOptionsMonitor)
public class EmailService(IOptionsSnapshot<EmailConfig> options)
{
    public void EnviarTransacional(string para, string assunto)
    {
        var config = options.Get("Transacional");
        // usa config.SmtpHost, config.SmtpPort...
    }

    public void EnviarMarketing(string para, string assunto)
    {
        var config = options.Get("Marketing");
        // usa config.SmtpHost, config.SmtpPort...
    }
}

Validación de Configuración en el Arranque

Un error común es que la aplicación arranque con configuración inválida (connection string vacía, puerto cero) y solo falle cuando llega el primer request. .NET 8 permite validar en el arranque:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
builder.Services.AddOptions<AppConfig>()
    .Bind(builder.Configuration.GetSection("App"))
    .ValidateDataAnnotations()       // valida [Required], [Range], etc.
    .ValidateOnStart();              // falla INMEDIATAMENTE si es inválido

builder.Services.AddOptions<EmailConfig>()
    .Bind(builder.Configuration.GetSection("App:Email"))
    .Validate(config =>
    {
        // Validación personalizada
        return !string.IsNullOrWhiteSpace(config.SmtpHost)
            && config.SmtpPort > 0;
    }, "SmtpHost debe estar completo y SmtpPort debe ser mayor que cero")
    .ValidateOnStart();
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// AppConfig.cs con Data Annotations para validación (¡no para ORM!)
using System.ComponentModel.DataAnnotations;

public sealed class AppConfig
{
    [Required(ErrorMessage = "NomeExibicao es obligatorio")]
    public string NomeExibicao { get; set; } = string.Empty;

    [Range(1, 500, ErrorMessage = "MaxItensPorPagina debe estar entre 1 y 500")]
    public int MaxItensPorPagina { get; set; } = 50;

    public bool HabilitarCache { get; set; }
}

ℹ️ Información: ValidateOnStart() hace que la aplicación falle rápido (fail fast) si la configuración es inválida — en lugar de fallar misteriosamente en el primer request. Esto es especialmente importante en contenedores, donde un arranque rápido con un error claro es mejor que un contenedor “running” que falla en cada request.


Cuándo .NET Recarga Configuraciones Automáticamente

No todos los providers soportan recarga automática. Saber cuáles recargan (y cuáles no) evita bugs sutiles:

Providers con reloadOnChange: true

Los providers basados en archivos son los únicos que soportan recarga automática:

1
2
3
4
5
// WebApplicationBuilder registra con reloadOnChange: true por defecto:
configBuilder.AddJsonFile("appsettings.json",
    optional: true, reloadOnChange: true);
configBuilder.AddJsonFile($"appsettings.{env.EnvironmentName}.json",
    optional: true, reloadOnChange: true);

Cuando editas appsettings.json o appsettings.Production.json con la aplicación en ejecución, .NET:

  1. Detecta el cambio mediante FileSystemWatcher
  2. Recarga el provider de configuración afectado
  3. Emite un change token (IChangeToken)
  4. IOptionsSnapshot<T> devolverá el nuevo valor en el próximo request
  5. IOptionsMonitor<T> dispara el callback OnChange() inmediatamente
  6. IOptions<T> no se ve afectado — mantiene el valor original

Providers que NO Recargan

Provider¿Recarga?Motivo
appsettings.json✅reloadOnChange: true (predeterminado)
appsettings.{Env}.json✅reloadOnChange: true (predeterminado)
User Secrets (secrets.json)❌Registrado sin reloadOnChange
Environment Variables❌Las variables se leen en el arranque y quedan en caché
Command-line args❌Se pasan una sola vez en el arranque
AddKeyPerFile (Docker secrets)❌Se leen en el arranque (archivo en tmpfs)

Forzando Reload con reloadOnChange

Si necesitas que otros archivos JSON también recarguen:

1
2
3
4
5
6
// Agregar un archivo JSON personalizado CON reloadOnChange
builder.Configuration.AddJsonFile(
    path: "config/feature-flags.json",
    optional: true,
    reloadOnChange: true   // ← habilita el FileSystemWatcher
);

⚠️ Atención: En contenedores Docker/Podman, reloadOnChange con FileSystemWatcher puede no funcionar según el tipo de volumen montado. Los volúmenes bind mount suelen funcionar, pero los volúmenes nombrados (docker volume) o tmpfs pueden no emitir los eventos de sistema de archivos necesarios. Prueba siempre en tu escenario específico.


Personalizando el Pipeline de Configuración

Cuando los providers predeterminados no son suficientes, puedes personalizar el pipeline por completo:

Agregando Providers Personalizados

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
var builder = WebApplication.CreateBuilder(args);

// Los providers predeterminados ya fueron registrados por CreateBuilder.
// Todo lo que agregues abajo tendrá MAYOR prioridad:

// Provider para Azure Key Vault
builder.Configuration.AddAzureKeyVault(
    new Uri("https://meu-vault.vault.azure.net/"),
    new DefaultAzureCredential());

// Provider para AWS Secrets Manager
builder.Configuration.AddSecretsManager(region: RegionEndpoint.SAEast1);

// Provider para HashiCorp Vault
builder.Configuration.AddVaultConfiguration(
    () => new VaultOptions { Address = "https://vault.meudominio.com" },
    "meuapp");

// Provider para Docker/Podman secrets
if (Directory.Exists("/run/secrets"))
    builder.Configuration.AddKeyPerFile("/run/secrets", optional: true);

Reemplazando el Pipeline por Completo

En escenarios raros en los que necesitas controlar el 100% del orden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // NO cargar appsettings.json automáticamente
    // (Cuidado: se pierden TODOS los providers predeterminados)
});

// Limpiar y reconstruir manualmente
builder.Configuration.Sources.Clear();

builder.Configuration
    .AddJsonFile("config/base.json", optional: false, reloadOnChange: true)
    .AddJsonFile($"config/base.{builder.Environment.EnvironmentName}.json", optional: true, reloadOnChange: true)
    .AddEnvironmentVariables(prefix: "MEUAPP_")
    .AddCommandLine(args);

if (builder.Environment.IsDevelopment())
    builder.Configuration.AddUserSecrets<Program>();

if (Directory.Exists("/run/secrets"))
    builder.Configuration.AddKeyPerFile("/run/secrets", optional: true);

Consejos y Buenas Prácticas

  1. Nunca hagas commit de secrets en appsettings.json — usa dotnet user-secrets en desarrollo y variables de entorno o Docker/Podman secrets en producción. Si un secret se filtra en Git, considéralo comprometido de inmediato.

  2. Usa ValidateOnStart() para todas las configuraciones críticas — connection strings, API keys, URLs de servicios. Fallar en el arranque siempre es mejor que fallar en el primer request a las 3 de la madrugada.

  3. Prefiere IOptionsMonitor<T> en servicios Singleton — si el servicio necesita reaccionar a cambios de configuración. Usa IOptionsSnapshot<T> solo en servicios Scoped (controllers, servicios por request).

  4. Nombra los secrets del contenedor con __ — usa ConnectionStrings__Default como nombre del archivo de secret para mantener compatibilidad con la jerarquía de configuración de .NET.

  5. Cuidado con reloadOnChange en contenedores — FileSystemWatcher puede no funcionar con todos los tipos de volumen. Prueba el comportamiento en tu entorno antes de depender de la recarga automática.

  6. Usa un prefijo para variables de entorno compartidas — builder.Configuration.AddEnvironmentVariables(prefix: "MEUAPP_") evita colisiones con variables del sistema y con otros servicios en el mismo host.

  7. No mezcles configuración y código — la clase POCO de configuración debe ser simple (getters/setters). La lógica de negocio basada en configuración debe estar en el servicio que consume IOptions<T>, nunca en la clase de configuración.

  8. Documenta el orden de tu pipeline — en proyectos con muchos providers (Key Vault, Feature Flags, Docker secrets), documenta explícitamente el orden de prioridad para el equipo.


Conclusión

El pipeline de configuración de .NET 8+ es un sistema potente y extensible que sigue una regla simple: el último provider registrado gana. Entender este orden — desde appsettings.json (menor prioridad) hasta los Docker/Podman secrets o los argumentos de línea de comandos (mayor prioridad) — es fundamental para evitar bugs de configuración sutiles que solo aparecen en producción.

El trío IOptions<T>, IOptionsSnapshot<T> e IOptionsMonitor<T> cubre todos los escenarios de consumo: configuración estática (Singleton), configuración por request (Scoped) y configuración reactiva con notificación (Singleton con reload). Combinado con ValidateOnStart(), garantiza que tu aplicación falle rápido con un mensaje claro, en lugar de fallar misteriosamente en tiempo de ejecución.

Para contenedores Docker y Podman, AddKeyPerFile("/run/secrets") es el puente entre los secrets del motor de contenedores y el sistema de configuración de .NET — seguro, simple y sin dependencia de paquetes externos. Esto encaja perfectamente con una arquitectura de deploy con Podman rootless y secrets gestionados mediante pipeline.

El siguiente paso natural es garantizar que tus entidades de dominio y el acceso a datos estén igualmente desacoplados — y para eso, EF Core 8 con Fluent API es el complemento ideal de este artículo.


Lee También


Referencias