appsettings por ambiente

Resumo

A variável DOTNET_ENVIRONMENT (ou ASPNETCORE_ENVIRONMENT) define o ambiente (Development, Staging, Production). O .NET carrega automaticamente o appsettings.{Environment}.json correspondente por cima do base.

1. Objetivos de Aprendizagem#

• Configurar valores por ambiente.
• Entender como o ambiente é selecionado.
• Usar User Secrets para segredos em desenvolvimento.

2. Pré-requisitos#

• IConfiguration e fontes (tópico 13.1).

3. Conceito#

O nome do ambiente vem de uma variável de ambiente:

• ASPNETCORE_ENVIRONMENT (apps web) ou DOTNET_ENVIRONMENT (genéricos).
• Valores convencionais: Development, Staging, Production.

O host carrega appsettings.json e depois appsettings.{Environment}.json, que sobrescreve o base. O porquê: manter a mesma base de configuração e ajustar só o que muda por ambiente (nível de log, endpoints, flags).

Para segredos em desenvolvimento, o .NET oferece User Secrets — um arquivo fora do repositório, associado ao projeto.

4. Mão na Massa#

4.1. Setup#

dotnet new console -n Catalog.Ambientes
cd Catalog.Ambientes

4.2. Implementação Passo a Passo#

1. Base e override por ambiente:

// appsettings.json
{ "Logging": { "Nivel": "Information" } }

// appsettings.Development.json
{ "Logging": { "Nivel": "Debug" } }

2. Carregar considerando o ambiente:

using Microsoft.Extensions.Configuration;

var ambiente = Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT") ?? "Production";

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false)
    .AddJsonFile($"appsettings.{ambiente}.json", optional: true) // sobrescreve
    .AddEnvironmentVariables()
    .Build();

Console.WriteLine($"[{ambiente}] Nível de log: {config["Logging:Nivel"]}");

3. User Secrets (segredos de dev):

dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Catalog" "Server=...;Password=..."

Nota

no ASP.NET Core, User Secrets é adicionado automaticamente à configuração apenas no ambiente Development.

4.3. Executando#

DOTNET_ENVIRONMENT=Development dotnet run   # usa appsettings.Development.json

5. Exemplo Completo#

Rodar com DOTNET_ENVIRONMENT=Development faz o nível de log virar Debug (do arquivo de ambiente), enquanto em Production permanece Information (do base) — mesma base, ajustes por ambiente.

6. Boas Práticas e Armadilhas#

Atenção

User Secrets não é criptografado — é apenas mantido fora do repositório. Para produção, use variáveis de ambiente ou um cofre gerenciado (Azure Key Vault, etc.).

7. Segurança e Produção#

• Configurações e recursos de Development (páginas de erro detalhadas, Swagger aberto) não devem vazar para produção. Trate o ambiente como uma fronteira de segurança.

8. Exercícios#

• Fácil: crie um appsettings.Development.json que sobrescreve um valor.
• Médio: rode em dois ambientes e confirme a diferença.
• Desafio: configure User Secrets e leia o valor via IConfiguration.

9. Resumo#

O ambiente (via DOTNET_ENVIRONMENT/ASPNETCORE_ENVIRONMENT) seleciona o appsettings.{Environment}.json que sobrescreve o base. Use User Secrets para segredos de dev e um cofre em produção.

10. Próximos Passos#

A seguir, tipar a configuração com o Options pattern.

11. Referências#

• Microsoft Learn — Uso de vários ambientes
• Microsoft Learn — Armazenamento seguro de segredos (User Secrets)
• Microsoft Learn — Configuração por ambiente