IConfiguration e fontes de configuração

Resumo

O .NET lê configuração de várias fontes (JSON, variáveis de ambiente, argumentos de linha de comando) num modelo unificado (IConfiguration). Fontes posteriores sobrescrevem as anteriores.

1. Objetivos de Aprendizagem#

• Ler valores de configuração via IConfiguration.
• Entender a ordem de precedência das fontes.
• Acessar seções e valores tipados.

2. Pré-requisitos#

• Injeção de dependência (Módulo 12).

3. Conceito#

A configuração no .NET é um conjunto de pares chave-valor montado a partir de provedores empilhados, tipicamente nesta ordem:

1. appsettings.json
2. appsettings.{Environment}.json
3. Variáveis de ambiente
4. Argumentos de linha de comando

Fontes posteriores sobrescrevem as anteriores. O porquê: manter defaults no JSON versionado e sobrescrever segredos/ajustes por ambiente sem recompilar.

4. Mão na Massa#

4.1. Setup#

dotnet new console -n Catalog.Config
cd Catalog.Config
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables

4.2. Implementação Passo a Passo#

1. appsettings.json:

{
  "Catalogo": {
    "TamanhoPaginaPadrao": 10,
    "MoedaPadrao": "BRL"
  }
}

2. Montar e ler:

using Microsoft.Extensions.Configuration;

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false)
    .AddEnvironmentVariables()   // sobrescreve o JSON
    .Build();

int tamanho = config.GetValue<int>("Catalogo:TamanhoPaginaPadrao"); // 10
string moeda = config["Catalogo:MoedaPadrao"] ?? "BRL";
Console.WriteLine($"{tamanho} itens em {moeda}");

Nota

no ASP.NET Core, o host já monta o IConfiguration com essas fontes; você só injeta IConfiguration ou usa o Options pattern (tópico 13.3).

4.3. Executando#

dotnet run
# Sobrescreva por ambiente:
# Catalogo__TamanhoPaginaPadrao=25 dotnet run   (duplo underscore = ':')

5. Exemplo Completo#

Definir TamanhoPaginaPadrao no JSON e sobrescrevê-lo com a variável Catalogo__TamanhoPaginaPadrao demonstra a precedência: o valor do ambiente vence o do arquivo.

6. Boas Práticas e Armadilhas#

Atenção

em variáveis de ambiente, o separador de seção é o duplo underscore (__), não : — pois : não é válido em nomes de variáveis em todos os sistemas.

7. Segurança e Produção#

• Nunca coloque segredos (senhas, connection strings com credenciais, chaves) no appsettings.json versionado. Use variáveis de ambiente, User Secrets (dev) ou um cofre (produção).

8. Exercícios#

• Fácil: leia um valor simples do appsettings.json.
• Médio: sobrescreva esse valor por variável de ambiente e confirme a precedência.
• Desafio: leia uma seção inteira e itere seus pares chave-valor.

9. Resumo#

IConfiguration unifica fontes (JSON, env, args) com precedência: as posteriores sobrescrevem. Mantenha defaults no JSON e segredos fora dele.

10. Próximos Passos#

A seguir, configuração específica por ambiente.

11. Referências#

• Microsoft Learn — Configuração no .NET
• Microsoft Learn — Configuração no ASP.NET Core
• Microsoft Learn — Provedores de configuração