Partilhar via

Configuração em .NET

A configuração no .NET é executada usando um ou mais provedores de configuração . Os fornecedores de configuração leem dados de configuração a partir de pares chave-valor usando várias fontes de configuração.

  • Arquivos de configurações, como appsettings.json
  • Variáveis de ambiente
  • Azure Key Vault
  • Configuração de Aplicativos do Azure
  • Argumentos de linha de comando
  • Fornecedores personalizados, instalados ou criados
  • Arquivos de diretório
  • Objetos .NET na memória
  • Fornecedores terceiros

Observação

Para obter informações sobre como configurar o próprio tempo de execução do .NET, consulte definições de configuração do .NET Runtime.

Conceitos e abstrações

Dada uma ou mais fontes de configuração, o tipo de IConfiguration fornece uma exibição unificada dos dados de configuração. A configuração é somente leitura e o padrão de configuração não foi projetado para ser gravável de forma programática. A interface IConfiguration é uma única representação de todas as fontes de configuração, conforme mostrado no diagrama a seguir:

A interface 'IConfiguration' é uma única representação de todas as fontes de configuração.

Configurar aplicativos de console

Os aplicativos de console .NET criados usando o modelo de comando dotnet new ou o Visual Studio por padrão não expõem recursos de configuração. Para adicionar configuração em uma aplicação de console .NET nova, adicione uma referência de pacote para o Microsoft.Extensions.Configuration. Este pacote é a base para a configuração em aplicativos .NET. Ele proporciona o ConfigurationBuilder e tipos associados.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

O código anterior:

  • Cria uma nova instância ConfigurationBuilder.
  • Adiciona uma coleção na memória de pares chave-valor ao construtor de configurações.
  • Chama o método Build() para criar uma instância IConfiguration.
  • Grava o valor da chave SomeKey no console.

Embora este exemplo use uma configuração na memória, há muitos provedores de configuração disponíveis, expondo a funcionalidade para variáveis de ambiente baseadas em arquivo, argumentos de linha de comando e outras fontes de configuração. Para obter mais informações, consulte provedores de configuração do .NET.

Abordagem de hospedagem alternativa

Geralmente, seus aplicativos farão mais do que apenas ler a configuração. Eles provavelmente usarão injeção de dependência, registo de logs e outros serviços. A abordagem .NET Host Genérico é recomendada para aplicações que usam esses serviços. Em vez disso, considere adicionar uma referência de pacote ao Microsoft.Extensions.Hosting. Modifique o arquivo Program.cs para corresponder ao seguinte código:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

O método Host.CreateApplicationBuilder(String[]) fornece a configuração padrão para o aplicativo na seguinte ordem, da prioridade mais alta para a mais baixa:

  1. Argumentos de linha de comando usando o provedor de configuração de linha de comando .
  2. Variáveis de ambiente usando o provedor de configuração de Variáveis de Ambiente .
  3. Os segredos do aplicativo quando o aplicativo é executado no ambiente Development.
  4. appsettings.json usando o provedor de configuração JSON .
  5. appsettings.Environment.json usando o provedor de configuração JSON . Por exemplo, appsettings.Produção.json e appsettings.Desenvolvimento.json.
  6. ChainedConfigurationProvider : Adiciona um IConfiguration existente como fonte.

Adicionar um provedor de configuração substitui os valores de configuração anteriores. Por exemplo, o provedor de configuração de linha de comando substitui todos os valores de outros provedores porque é adicionado por último. Se SomeKey estiver definido no appsettings.json e no ambiente, o valor do ambiente será usado porque foi adicionado após appsettings.json.

Ligação

Uma das principais vantagens de usar as abstrações de configuração do .NET é a capacidade de vincular valores de configuração a instâncias de objetos .NET. Por exemplo, pode utilizar o provedor de configuração JSON para mapear arquivos appsettings.json em objetos .NET e usá-lo com injeções de dependência . Isso ativa o padrão de opções , que utiliza classes para fornecer acesso com tipagem forte a grupos de configurações relacionadas. O vinculador padrão é baseado em reflexão, mas existe uma alternativa de gerador de código-fonte que é fácil de habilitar.

A configuração do .NET fornece várias abstrações. Considere as seguintes interfaces:

Essas abstrações são agnósticas ao seu provedor de configuração subjacente (IConfigurationProvider). Em outras palavras, você pode usar uma instância IConfiguration para acessar qualquer valor de configuração de vários provedores.

O aglutinador pode usar diferentes abordagens para processar valores de configuração.

  • Desserialização direta (usando conversores internos) para tipos primitivos.
  • O TypeConverter para um tipo complexo caso o tipo tenha um.
  • Reflexão para um tipo complexo que possui propriedades.

Observação

O fichário tem algumas limitações:

  • As propriedades são ignoradas se tiverem métodos de escrita privados ou se o seu tipo não puder ser convertido.
  • As propriedades sem chaves de configuração correspondentes são ignoradas.

Hierarquias de vinculação

Os valores de configuração podem conter dados hierárquicos. Os objetos hierárquicos são representados com o uso do delimitador de : nas chaves de configuração. Para acessar um valor de configuração, use o caractere : para delimitar uma hierarquia. Por exemplo, considere os seguintes valores de configuração:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

A tabela a seguir representa chaves de exemplo e seus valores correspondentes para o exemplo anterior JSON:

Chave Valor
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Exemplo básico

Para aceder aos valores de configuração na sua forma básica, sem a ajuda da abordagem do host genérico , use o tipo ConfigurationBuilder diretamente.

Dica

O tipo System.Configuration.ConfigurationBuilder é diferente do tipo Microsoft.Extensions.Configuration.ConfigurationBuilder. Todo este conteúdo é específico para os pacotes e namespaces do NuGet Microsoft.Extensions.*.

Considere o seguinte projeto C#:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.6" />
  </ItemGroup>

</Project>

O arquivo de projeto anterior faz referência a vários pacotes NuGet de configuração:

Considere um exemplo appsettings.json arquivo:

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Agora, dado esse arquivo JSON, aqui está um exemplo de padrão de consumo usando o construtor de configurações diretamente:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

O código C# anterior:

  • Instancia um ConfigurationBuilder.
  • Adiciona o arquivo "appsettings.json" a ser reconhecido pelo provedor de configuração JSON.
  • Adiciona variáveis de ambiente reconhecidas pelo fornecedor de configuração de ambiente.
  • Obtém a seção "Settings" necessária e a instância Settings correspondente usando a instância config.

O objeto Settings tem a seguinte forma:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Exemplo básico com hospedagem

Para acessar o valor IConfiguration, você pode confiar novamente no pacote NuGet Microsoft.Extensions.Hosting. Crie um novo aplicativo de console e cole o seguinte conteúdo do arquivo de projeto nele:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.6" />
  </ItemGroup>

</Project>

O arquivo de projeto anterior define que:

  • O aplicativo é um executável.
  • Um arquivo appsettings.json deve ser copiado para o diretório de saída quando o projeto é compilado.
  • A referência de pacote NuGet Microsoft.Extensions.Hosting é adicionada.

Adicione o arquivo appsettings.json na raiz do projeto com o seguinte conteúdo:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Substitua o conteúdo do arquivo Program.cs pelo seguinte código C#:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

Quando você executa esse aplicativo, o Host.CreateApplicationBuilder define o comportamento para descobrir a configuração JSON e expô-la através da instância IConfiguration. A partir da instância host, pode-se pedir ao provedor de serviços a instância IConfiguration e depois solicitar os valores.

Dica

Utilizar a instância IConfiguration em bruto desta forma, embora seja conveniente, não permite expandir muito bem. Quando os aplicativos aumentam em complexidade e suas configurações correspondentes se tornam mais complexas, recomendamos que você use o padrão de opções como alternativa.

Exemplo básico com hospedagem e uso da API do indexador

Considere o mesmo appsettings.json conteúdo do arquivo do exemplo anterior:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Substitua o conteúdo do arquivo Program.cs pelo seguinte código C#:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Os valores são acessados usando a API do indexador, onde cada chave é uma cadeia de caracteres e o valor é uma cadeia de caracteres. A configuração suporta propriedades, objetos, matrizes e dicionários.

Provedores de configuração

A tabela a seguir mostra os provedores de configuração disponíveis para aplicativos .NET Core.

Fornecedor Fornece configuração a partir de
provedor de configuração do aplicativo Azure Configuração do Aplicativo do Azure
provedor de configuração do Azure Key Vault Azure Key Vault
Provedor de configuração de linha de comando Parâmetros de linha de comando
Provedor de configuração personalizado Fonte personalizada
provedor de configuração de variáveis de ambiente Variáveis de ambiente
Provedor de configuração de arquivo Arquivos JSON, XML e INI
Provedor de configuração de chave por arquivo Arquivos de diretório
Provedor de configuração de memória Coleções na memória
Segredos da aplicação (Gestor Secreto) Arquivo no diretório de perfil de usuário

Dica

A ordem na qual os provedores de configuração são adicionados é importante. Quando vários provedores de configuração são usados e mais de um provedor especifica a mesma chave, o último adicionado é usado.

Para obter mais informações sobre vários provedores de configuração, consulte a secção Provedores de configuração no .NET.

Ver também