Partilhar via

Configuração em .NET

  • Artigo

A configuração no .NET é executada usando um ou mais provedores de configuração. Os provedores de configuração leem dados de configuração 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 do Aplicativo do Azure
  • Argumentos de linha de comando
  • Fornecedores personalizados, instalados ou criados
  • Arquivos de diretório
  • Objetos .NET na memória
  • Fornecedores terceiros

Nota

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 IConfiguration tipo 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 programaticamente. A IConfiguration interface é uma única representação de todas as fontes de configuração, como mostrado no diagrama a seguir:

The `IConfiguration` interface is a single representation of all the configuration sources.

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 os recursos de configuração. Para adicionar configuração em um novo aplicativo de console .NET, adicione uma referência de pacote a Microsoft.Extensions.Configuration. Este pacote é a base para a configuração em aplicativos .NET. Ele fornece os ConfigurationBuilder tipos e relacionados.

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 ConfigurationBuilder instância.
  • Adiciona uma coleção na memória de pares chave-valor ao construtor de configurações.
  • Chama o Build() método para criar uma IConfiguration instância.
  • Grava o SomeKey valor da chave 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 no .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, registro em log e outros serviços. A abordagem de Host Genérico .NET é recomendada para aplicativos que usam esses serviços. Em vez disso, considere adicionar uma referência de pacote a 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 Host.CreateApplicationBuilder(String[]) método 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. Segredos do Development aplicativo quando o aplicativo é executado no ambiente.
  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 existente IConfiguration 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 for definido no appsettings.json e no ambiente, o valor do ambiente será usado porque foi adicionado após appsettings.json.

Enlace

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, o provedor de configuração JSON pode ser usado para mapear arquivos appsettings.json para objetos .NET e é usado com injeção de dependência. Isso habilita o padrão options, que usa classes para fornecer acesso fortemente tipado a grupos de configurações relacionadas. 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 IConfiguration instância para acessar qualquer valor de configuração de vários provedores.

O fichário 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 quando o tipo tem um.
  • Reflexão para um tipo complexo que tem propriedades.

Nota

O aglutinante tem algumas limitações:

  • As propriedades são ignoradas se tiverem setters privados ou se 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 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:

Key valor
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Exemplo básico

Para acessar valores de configuração em sua forma básica, sem a ajuda da abordagem de host genérica, use o ConfigurationBuilder tipo diretamente.

Gorjeta

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

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="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </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 ConfigurationBuilderarquivo .
  • Adiciona o "appsettings.json" arquivo a ser reconhecido pelo provedor de configuração JSON.
  • Adiciona variáveis de ambiente como sendo reconhecidas pelo provedor de configuração de variável de ambiente.
  • Obtém a seção necessária "Settings" e a instância correspondente Settings usando a config instância.

O Settings objeto 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 IConfiguration valor, você pode confiar novamente no Microsoft.Extensions.Hosting pacote NuGet. 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="8.0.2" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </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 Microsoft.Extensions.Hosting referência do pacote NuGet é 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 este aplicativo, o Host.CreateApplicationBuilder define o comportamento para descobrir a configuração JSON e expô-la através da IConfiguration instância. A partir da host instância, você pode solicitar a IConfiguration instância ao provedor de serviços e, em seguida, solicitar valores.

Gorjeta

Usar a instância bruta IConfiguration dessa maneira, embora conveniente, não escala 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.

Provider Fornece configuração a partir de
Provedor de configuração do Aplicativo do Azure Configuração da Aplicação Azure
Provedor de configuração do Azure Key Vault Azure Key Vault
Provedor de configuração de linha de comando Parâmetros da linha de comandos
Provedor de configuração personalizada Fonte personalizada
Provedor de configuração de variáveis de ambiente Variáveis de ambiente
Provedor de configuração de arquivos 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 de segredos) Arquivo no diretório de perfil de usuário

Gorjeta

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 Provedores de configuração no .NET.

Consulte também