Configuração de aplicações C# (.NET): Microsoft.Extensions.Configuration

Configuração de aplicações C# (.NET): guia completo

O gerenciamento de configuração é uma das tarefas principais no desenvolvimento de aplicações modernas em C# (.NET). A biblioteca Microsoft.Extensions.Configuration fornece um mecanismo poderoso e flexível para ler configurações de várias fontes: arquivos JSON, variáveis de ambiente, argumentos de linha de comando e segredos. Neste artigo, vamos detalhar como configurar a configuração em aplicações .NET, usando as melhores práticas e exemplos de código.

Principais recursos da biblioteca

• Múltiplas fontes de dados: JSON, XML, INI, variáveis de ambiente, argumentos de linha de comando, Azure Key Vault e outros.
• Estrutura hierárquica: suporte para seções aninhadas através de chaves com dois pontos (Section:Subsection:Key).
• Vinculação a classes (Options Pattern): preenchimento automático de objetos POCO a partir da configuração.
• Substituição flexível: a última fonte adicionada tem prioridade.
• Suporte a segredos: para desenvolvimento — Secret Manager, para produção — armazenamentos protegidos.

Instalação e configuração

Para trabalhar com configuração em uma aplicação .NET (console, ASP.NET Core, MAUI, etc.), é necessário instalar o pacote NuGet:

dotnet add package Microsoft.Extensions.Configurationdotnet add package Microsoft.Extensions.Configuration.Jsondotnet add package Microsoft.Extensions.Configuration.EnvironmentVariablesdotnet add package Microsoft.Extensions.Configuration.CommandLine

No ASP.NET Core, esses pacotes já estão incluídos por padrão.

Exemplo básico: leitura de appsettings.json

Crie o arquivo appsettings.json:

{  "Logging": {    "LogLevel": {      "Default": "Information",      "Microsoft": "Warning"    }  },  "ConnectionStrings": {    "DefaultConnection": "Server=localhost;Database=MyDb;User Id=sa;Password=MyPass;"  },  "AppSettings": {    "AppName": "MyApp",    "Version": "1.0.0",    "MaxRetries": 3  }}

Código para ler a configuração em uma aplicação de console:

using Microsoft.Extensions.Configuration;

class Program{    static void Main(string[] args)    {        // Criar a configuração        var configuration = new ConfigurationBuilder()            .SetBasePath(Directory.GetCurrentDirectory())            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)            .AddEnvironmentVariables()            .AddCommandLine(args)            .Build();

        // Leitura de valores simples        string appName = configuration["AppSettings:AppName"];        Console.WriteLine($"App Name: {appName}");

        // Leitura de seções aninhadas        string connString = configuration.GetConnectionString("DefaultConnection");        Console.WriteLine($"Connection String: {connString}");

        // Leitura de um número inteiro        int maxRetries = int.Parse(configuration["AppSettings:MaxRetries"]);        Console.WriteLine($"Max Retries: {maxRetries}");

        // Obter a seção inteira        var appSettingsSection = configuration.GetSection("AppSettings");        Console.WriteLine($"Version: {appSettingsSection["Version"]}");    }}

Padrão Options (vinculação a classes)

A melhor prática é usar configuração fortemente tipada através de IOptions<T>. Para isso:

1. Crie uma classe para a seção de configuração:

public class AppSettings{    public string AppName { get; set; }    public string Version { get; set; }    public int MaxRetries { get; set; }}

2. Registre a configuração no contêiner DI (para ASP.NET Core ou usando Micros