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:
| |
ℹ️ 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é
| Orden | Provider | reloadOnChange | Cuándo se registra |
|---|---|---|---|
| 1 | ChainedConfigurationSource | — | Configuraciones heredadas del host (rara vez se manipulan) |
| 2 | appsettings.json | ✅ Sí | Siempre — valores predeterminados de la aplicación |
| 3 | appsettings.{Environment}.json | ✅ Sí | Siempre — sobrescribe valores por entorno |
| 4 | User Secrets (secrets.json) | ❌ No | Solo cuando ASPNETCORE_ENVIRONMENT=Development |
| 5 | Environment Variables | ❌ No | Siempre — variables del sistema/contenedor |
| 6 | Command-line arguments | ❌ No | Siempre — 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:
| |
| |
⚠️ Atención:
appsettings.Production.jsonnunca 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:
| |
| |
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
| |
Dónde Se Almacenan
| Sistema Operativo | Ruta |
|---|---|
| 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:
| |
💡 Consejo:
secrets.jsontiene el mismo formato queappsettings.json. Internamente, .NET registra unJsonConfigurationProviderapuntando a ese archivo — por eso cualquier clave deappsettings.jsonpuede 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:
| |
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:
| |
| |
| |
⚠️ Atención: En Linux, las variables de entorno distinguen mayúsculas y minúsculas.
ConnectionStrings__Defaultes diferente deCONNECTIONSTRINGS__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:
| |
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>:
| |
| |
| |
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:
| |
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:
AddKeyPerFileaplica la convención__→:automáticamente, igual que las variables de entorno. Así, un archivo llamadoApp__Email__SmtpHostserá accesible comoConfiguration["App:Email:SmtpHost"].
Convención de Nombres para Secrets
Para mantener compatibilidad con la jerarquía de .NET:
| Secret (nombre del archivo) | Clave en Configuration | Contenido del archivo |
|---|---|---|
ConnectionStrings__Default | ConnectionStrings:Default | Host=db;Database=prod;Password=S3nh@! |
App__Email__SmtpHost | App:Email:SmtpHost | smtp.sendgrid.net |
App__JwtSecretKey | App:JwtSecretKey | minha-chave-jwt-super-secreta-256bits |
Podman Secrets vs Docker Secrets
| Característica | Docker Secrets | Podman Secrets |
|---|---|---|
| Requisito | Docker Swarm mode | Funciona sin Swarm (rootless) |
| Almacenamiento | Raft log (cifrado) | Directorio local (cifrable) |
| Montaje | /run/secrets/ (tmpfs) | /run/secrets/ (tmpfs) |
| ¿Visible en inspect? | ❌ No | ❌ No |
| ¿Visible en /proc? | ❌ No | ❌ No |
| CLI | docker secret create | podman secret create |
| Compose | docker 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í:
| |
⚠️ Atención: La posición donde llamas a
AddKeyPerFiledefine su prioridad. Si quieres que las variables de entorno tengan prioridad sobre los Docker secrets, registraAddKeyPerFileantes deAddEnvironmentVariables. 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
| |
| |
IOptions<T> — Singleton, Sin Recarga
| |
| Característica | Comportamiento |
|---|---|
| Ciclo de vida | Singleton (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 usar | Configuraciones que nunca cambian durante la vida de la aplicación |
| Registro | services.Configure<T>(section) |
IOptionsSnapshot<T> — Scoped, Recarga por Request
| |
| Característica | Comportamiento |
|---|---|
| Ciclo de vida | Scoped (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 usar | APIs y web apps donde la configuración puede cambiar sin reinicio |
| Restricción | ⚠️ No puede inyectarse en servicios Singleton |
| Registro | services.Configure<T>(section) (mismo registro) |
IOptionsMonitor<T> — Singleton con Notificación
| |
| Característica | Comportamiento |
|---|---|
| Ciclo de vida | Singleton (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 usar | Servicios Singleton que necesitan reaccionar a cambios de configuración |
| Registro | services.Configure<T>(section) (mismo registro) |
Comparativa Rápida
| Interfaz | Ciclo de vida | Reload | Notificació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):
| |
| |
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:
| |
| |
ℹ️ 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:
| |
Cuando editas appsettings.json o appsettings.Production.json con la aplicación en ejecución, .NET:
- Detecta el cambio mediante
FileSystemWatcher - Recarga el provider de configuración afectado
- Emite un change token (
IChangeToken) IOptionsSnapshot<T>devolverá el nuevo valor en el próximo requestIOptionsMonitor<T>dispara el callbackOnChange()inmediatamenteIOptions<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:
| |
⚠️ Atención: En contenedores Docker/Podman,
reloadOnChangeconFileSystemWatcherpuede no funcionar según el tipo de volumen montado. Los volúmenesbind mountsuelen funcionar, pero los volúmenes nombrados (docker volume) otmpfspueden 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
| |
Reemplazando el Pipeline por Completo
En escenarios raros en los que necesitas controlar el 100% del orden:
| |
Consejos y Buenas Prácticas
Nunca hagas commit de secrets en
appsettings.json— usadotnet user-secretsen desarrollo y variables de entorno o Docker/Podman secrets en producción. Si un secret se filtra en Git, considéralo comprometido de inmediato.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.Prefiere
IOptionsMonitor<T>en servicios Singleton — si el servicio necesita reaccionar a cambios de configuración. UsaIOptionsSnapshot<T>solo en servicios Scoped (controllers, servicios por request).Nombra los secrets del contenedor con
__— usaConnectionStrings__Defaultcomo nombre del archivo de secret para mantener compatibilidad con la jerarquía de configuración de .NET.Cuidado con
reloadOnChangeen contenedores —FileSystemWatcherpuede no funcionar con todos los tipos de volumen. Prueba el comportamiento en tu entorno antes de depender de la recarga automática.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.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.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
- EF Core 8 Fluent API: Mapeo, ORM y Desacoplamiento — desacoplamiento en el acceso a datos con el mismo patrón de configuración externalizada.
- EF Core Migrations: Multiproyecto, Secrets y Scaffolding — cómo
dotnet user-secretsse integra con EF Core Migrations en proyectos multicapa. - Autenticación y Autorización: JWT, OAuth2 y OpenID Connect — configuraciones de seguridad que dependen directamente del pipeline de configuración.
- BFF Backend For Frontend: Seguridad en SPAs — cómo se gestionan los tokens y secrets en el patrón BFF.
- Diseño de API REST: Verbos HTTP y Parameter Binding — arquitectura de APIs que consume configuraciones vía DI.
Referencias
- Configuración en ASP.NET Core — Microsoft Learn — documentación oficial del sistema de configuración de .NET, incluidos todos los providers y el orden de carga.
- Patrón de opciones en ASP.NET Core — Microsoft Learn — referencia completa de
IOptions<T>,IOptionsSnapshot<T>,IOptionsMonitor<T>y Named Options. - Almacenamiento seguro de secretos de aplicación en desarrollo — Microsoft Learn — guía oficial de
dotnet user-secretspara proteger datos sensibles en desarrollo. - Uso de varios entornos en ASP.NET Core — Microsoft Learn — cómo
ASPNETCORE_ENVIRONMENTcontrola la carga de configuraciones por entorno. - Proveedor de configuración de clave por archivo — Microsoft Learn — documentación de
AddKeyPerFilepara la integración con Docker/Podman secrets. - Docker Secrets — Docker Docs — referencia oficial de secrets en Docker Swarm y Docker Compose.
- Podman Secrets — Podman Docs — referencia oficial de gestión de secrets en Podman (rootless).
- .NET Generic Host — Microsoft Learn — cómo el host genérico de .NET configura el pipeline de configuración, logging y DI.
- Código fuente de WebApplicationBuilder — GitHub — código fuente de
WebApplicationBuilderque muestra el orden exacto de los providers registrados.

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.