Provedores de configuração no .NET

A configuração no .NET é possível com provedores de configuração. Vários tipos de provedores dependem de várias fontes de configuração. Este artigo detalha todos os diferentes provedores de configuração e suas fontes correspondentes.

• Provedor de configuração de arquivos
• Provedor de configuração de variável de ambiente
• Provedor de configuração de linha de comando
• Provedor de configuração de chave por arquivo
• Provedor de configuração de memória

Provedor de configuração de arquivos

FileConfigurationProvider é a classe base para carregar a configuração do sistema de arquivos. Os seguintes provedores de configuração derivam de FileConfigurationProvider:

• Provedor de configuração JSON
• Provedor de configuração XML
• Provedor de configuração INI

As chaves não sensível às maiúsculas e minúsculas. Todos os provedores de configuração de arquivos lançam quando chaves FormatException duplicadas são encontradas em um único provedor.

Provedor de configuração JSON

A JsonConfigurationProvider classe carrega a configuração de um arquivo JSON. Instale o Microsoft.Extensions.Configuration.Json pacote NuGet.

As sobrecargas podem especificar:

• Se o arquivo é opcional.
• Se a configuração será recarregada se o arquivo for alterado.

Considere o seguinte código:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ConsoleJson.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true);

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

O código anterior:

• Limpa todos os provedores de configuração existentes que foram adicionados por padrão no CreateApplicationBuilder(String[]) método.
• Configura o provedor de configuração JSON para carregar o appsettings.json e appsettings.Environment.JSON com as seguintes opções:
  • optional: true: O arquivo é opcional.
  • reloadOnChange: true: O arquivo é recarregado quando as alterações são salvas.

Importante

Ao adicionar provedores de configuração com IConfigurationBuilder.Add, o provedor de configuração adicionado é adicionado ao final do final da IConfigurationSource lista. Quando as chaves são encontradas por vários provedores, o último provedor a ler a chave substitui os provedores anteriores.

Segue-se um exemplo appsettings.json ficheiro com várias definições de configuração:

{
    "SecretKey": "Secret key value",
    "TransientFaultHandlingOptions": {
        "Enabled": true,
        "AutoRetryDelay": "00:00:07"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    }
}

A partir da instância, depois que os IConfigurationBuilder provedores de configuração tiverem sido adicionados, você poderá chamar IConfigurationBuilder.Build() para obter o IConfigurationRoot objeto. A raiz de configuração representa a raiz de uma hierarquia de configuração. As seções da configuração podem ser vinculadas a instâncias de objetos .NET e posteriormente fornecidas como IOptions<TOptions> por meio de injeção de dependência.

Nota

As propriedades Build Action e Copy to Output Directory do arquivo JSON devem ser definidas como Content e Copy se forem mais recentes (ou Copy always), respectivamente.

Considere a TransientFaultHandlingOptions classe definida da seguinte forma:

namespace ConsoleJson.Example;

public sealed class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

O código a seguir cria a raiz de configuração, vincula uma seção ao TransientFaultHandlingOptions tipo de classe e imprime os valores acoplados na janela do console:

TransientFaultHandlingOptions options = new();
builder.Configuration.GetSection(nameof(TransientFaultHandlingOptions))
    .Bind(options);

Console.WriteLine($"TransientFaultHandlingOptions.Enabled={options.Enabled}");
Console.WriteLine($"TransientFaultHandlingOptions.AutoRetryDelay={options.AutoRetryDelay}");

O aplicativo grava a seguinte saída de exemplo:

// Sample output:
//    TransientFaultHandlingOptions.Enabled=True
//    TransientFaultHandlingOptions.AutoRetryDelay=00:00:07

Provedor de configuração XML

A XmlConfigurationProvider classe carrega a configuração de um arquivo XML em tempo de execução. Instale o Microsoft.Extensions.Configuration.Xml pacote NuGet.

O código a seguir demonstra a configuração de arquivos XML usando o provedor de configuração XML.

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.Sources.Clear();

builder.Configuration
    .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
    .AddXmlFile("repeating-example.xml", optional: true, reloadOnChange: true);

builder.Configuration.AddEnvironmentVariables();

if (args is { Length: > 0 })
{
    builder.Configuration.AddCommandLine(args);
}

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

O código anterior:

• Limpa todos os provedores de configuração existentes que foram adicionados por padrão no CreateApplicationBuilder(String[]) método.
• Configura o provedor de configuração XML para carregar os arquivos appsettings.xml e repeating-example.xml com as seguintes opções:
  • optional: true: O arquivo é opcional.
  • reloadOnChange: true: O arquivo é recarregado quando as alterações são salvas.
• Configura o provedor de configuração de variáveis de ambiente.
• Configura o provedor de configuração de linha de comando se os dados contiverem args argumentos.

As configurações XML são substituídas por configurações no provedor de configuração de variáveis de ambiente e no provedor de configuração de linha de comando.

Segue-se um exemplo appsettings.xml ficheiro com várias definições de configuração:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <SecretKey>Secret key value</SecretKey>
  <TransientFaultHandlingOptions>
    <Enabled>true</Enabled>
    <AutoRetryDelay>00:00:07</AutoRetryDelay>
  </TransientFaultHandlingOptions>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

Gorjeta

Para usar o IConfiguration tipo em aplicativos WinForms, adicione uma referência ao pacote NuGet Microsoft.Extensions.Configuration.Xml . Instancie as chamadas e encadeie ConfigurationBuilder para AddXmlFile e Build(). Para obter mais informações, consulte .NET Docs Issue #29679.

No .NET 5 e versões anteriores, adicione o name atributo para distinguir elementos repetitivos que usam o mesmo nome de elemento. No .NET 6 e versões posteriores, o provedor de configuração XML indexa automaticamente elementos repetidos. Isso significa que você não precisa especificar o name atributo, exceto se quiser o índice "0" na chave e houver apenas um elemento. (Se você estiver atualizando para o .NET 6 ou posterior, poderá encontrar uma interrupção resultante dessa alteração no comportamento. Para obter mais informações, consulte Elementos XML repetidos incluem índice.)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section name="section0">
    <key name="key0">value 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

O código a seguir lê o arquivo de configuração anterior e exibe as chaves e valores:

IConfigurationRoot configurationRoot = builder.Configuration;

string key00 = "section:section0:key:key0";
string key01 = "section:section0:key:key1";
string key10 = "section:section1:key:key0";
string key11 = "section:section1:key:key1";

string? val00 = configurationRoot[key00];
string? val01 = configurationRoot[key01];
string? val10 = configurationRoot[key10];
string? val11 = configurationRoot[key11];

Console.WriteLine($"{key00} = {val00}");
Console.WriteLine($"{key01} = {val01}");
Console.WriteLine($"{key10} = {val10}");
Console.WriteLine($"{key10} = {val11}");

O aplicativo gravaria a seguinte saída de exemplo:

// Sample output:
//    section:section0:key:key0 = value 00
//    section:section0:key:key1 = value 01
//    section:section1:key:key0 = value 10
//    section:section1:key:key0 = value 11

Os atributos podem ser usados para fornecer valores:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <key attribute="value" />
  <section>
    <key attribute="value" />
  </section>
</configuration>

O arquivo de configuração anterior carrega as seguintes chaves com value:

• key:attribute
• section:key:attribute

Provedor de configuração INI

A IniConfigurationProvider classe carrega a configuração de um arquivo INI em tempo de execução. Instale o Microsoft.Extensions.Configuration.Ini pacote NuGet.

O código a seguir limpa todos os provedores de configuração e adiciona o IniConfigurationProvider com dois arquivos INI como origem:

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Configuration.Sources.Clear();

IHostEnvironment env = builder.Environment;

builder.Configuration
    .AddIniFile("appsettings.ini", optional: true, reloadOnChange: true)
    .AddIniFile($"appsettings.{env.EnvironmentName}.ini", true, true);

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Segue-se um exemplo appsettings.ini ficheiro com várias definições de configuração:

SecretKey="Secret key value"

[TransientFaultHandlingOptions]
Enabled=True
AutoRetryDelay="00:00:07"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

O código a seguir exibe as definições de configuração anteriores gravando-as na janela do console:

foreach ((string key, string? value) in
    builder.Configuration.AsEnumerable().Where(t => t.Value is not null))
{
    Console.WriteLine($"{key}={value}");
}

O aplicativo gravaria a seguinte saída de exemplo:

// Sample output:
//    TransientFaultHandlingOptions:Enabled=True
//    TransientFaultHandlingOptions:AutoRetryDelay=00:00:07
//    SecretKey=Secret key value
//    Logging:LogLevel:Microsoft=Warning
//    Logging:LogLevel:Default=Information

Provedor de configuração de variável de ambiente

Usando a configuração padrão, a configuração carrega a EnvironmentVariablesConfigurationProvider partir de pares chave-valor da variável de ambiente depois de ler appsettings.json, appsettings.Environment. json, e gerente secreto. Portanto, os valores-chave lidos do ambiente substituem os valores lidos de appsettings.json, appsettings.Environment. json, e gerente secreto.

O : delimitador não funciona com chaves hierárquicas variáveis de ambiente em todas as plataformas. Por exemplo, o delimitador não é suportado : pelo Bash. O sublinhado duplo (__), que é suportado em todas as plataformas, substitui automaticamente quaisquer : delimitadores em variáveis de ambiente.

Considere a TransientFaultHandlingOptions classe:

public class TransientFaultHandlingOptions
{
    public bool Enabled { get; set; }
    public TimeSpan AutoRetryDelay { get; set; }
}

Os comandos a seguir set definem as chaves de ambiente e os valores de SecretKey e TransientFaultHandlingOptions.

set SecretKey="Secret key from environment"
set TransientFaultHandlingOptions__Enabled="true"
set TransientFaultHandlingOptions__AutoRetryDelay="00:00:13"

Essas configurações de ambiente são definidas apenas em processos iniciados a partir da janela de comando em que foram definidas. Eles não são lidos por aplicativos Web iniciados com o Visual Studio.

Com o Visual Studio 2019 e posterior, você pode especificar variáveis de ambiente usando a caixa de diálogo Perfis de inicialização .

Os seguintes comandos setx podem ser usados para definir as chaves e valores de ambiente no Windows. Ao contrário setdo , setx as configurações são persistentes. /M Define a variável no ambiente do sistema. Se o /M switch não for usado, uma variável de ambiente do usuário será definida.

setx SecretKey "Secret key from setx environment" /M
setx TransientFaultHandlingOptions__Enabled "true" /M
setx TransientFaultHandlingOptions__AutoRetryDelay "00:00:05" /M

Para testar se os comandos anteriores substituem qualquer appsettings.json e appsettings.Environment. Configurações JSON :

• Com o Visual Studio: saia e reinicie o Visual Studio.
• Com a CLI: Inicie uma nova janela de comando e digite dotnet run.

Prefixos

Para especificar um prefixo para variáveis de ambiente, chame AddEnvironmentVariables com uma cadeia de caracteres:

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddEnvironmentVariables(prefix: "CustomPrefix_");

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

No código anterior:

• config.AddEnvironmentVariables(prefix: "CustomPrefix_") é adicionado após os provedores de configuração padrão. Para obter um exemplo de como ordenar os provedores de configuração, consulte Provedor de configuração XML.
• As variáveis de ambiente definidas com o prefixo substituem CustomPrefix_ os provedores de configuração padrão. Isso inclui variáveis de ambiente sem o prefixo.

O prefixo é removido quando os pares chave-valor de configuração são lidos.

A configuração padrão carrega variáveis de ambiente e argumentos de linha de comando prefixados com DOTNET_. O DOTNET_ prefixo é usado pelo .NET para configuração de host e aplicativo, mas não para configuração de usuário.

Para obter mais informações sobre a configuração do host e do aplicativo, consulte .NET Generic Host.

Prefixos de cadeia de conexão

A API de configuração tem regras de processamento especiais para quatro variáveis de ambiente de cadeia de conexão. Essas cadeias de conexão estão envolvidas na configuração de cadeias de conexão do Azure para o ambiente do aplicativo. As variáveis de ambiente com os prefixos mostrados na tabela são carregadas no aplicativo com a configuração padrão ou quando nenhum prefixo é fornecido ao AddEnvironmentVariables.

Prefixo da cadeia de conexão	Provider
CUSTOMCONNSTR_	Provedor personalizado
MYSQLCONNSTR_	MySQL
SQLAZURECONNSTR_	Base de Dados SQL do Azure
SQLCONNSTR_	SQL Server

Quando uma variável de ambiente é descoberta e carregada na configuração com qualquer um dos quatro prefixos mostrados na tabela:

• A chave de configuração é criada removendo o prefixo da variável de ambiente e adicionando uma seção de chave de configuração (ConnectionStrings).
• É criado um novo par chave-valor de configuração que representa o provedor de conexão de banco de dados (exceto para CUSTOMCONNSTR_, que não tem nenhum provedor declarado).

Chave variável de ambiente	Chave de configuração convertida	Entrada de configuração do provedor
CUSTOMCONNSTR_{KEY}	ConnectionStrings:{KEY}	Entrada de configuração não criada.
MYSQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Chave: ConnectionStrings:{KEY}_ProviderName: Valor: MySql.Data.MySqlClient
SQLAZURECONNSTR_{KEY}	ConnectionStrings:{KEY}	Chave: ConnectionStrings:{KEY}_ProviderName: Valor: System.Data.SqlClient
SQLCONNSTR_{KEY}	ConnectionStrings:{KEY}	Chave: ConnectionStrings:{KEY}_ProviderName: Valor: System.Data.SqlClient

Variáveis de ambiente definidas em launchSettings.json

As variáveis de ambiente definidas no launchSettings.json substituem as definidas no ambiente do sistema.

Configurações do Serviço de Aplicativo do Azure

No Serviço de Aplicativo do Azure, selecione Nova configuração de aplicativo na página Configuração de Definições>. As configurações do aplicativo do Serviço de Aplicativo do Azure são:

• Encriptado em repouso e transmitido através de um canal encriptado.
• Exposto como variáveis de ambiente.

Provedor de configuração de linha de comando

Usando a configuração padrão, o carrega a CommandLineConfigurationProvider configuração a partir de pares chave-valor de argumento de linha de comando após as seguintes fontes de configuração:

• appsettings.json e appsettings.Environment.arquivos json.
• Segredos da aplicação (Gestor Secreto) no Development ambiente.
• Variáveis de ambiente.

Por padrão, os valores de configuração definidos na linha de comando substituem os valores de configuração definidos com todos os outros provedores de configuração.

Com o Visual Studio 2019 e posterior, você pode especificar argumentos de linha de comando usando a caixa de diálogo Iniciar Perfis .

Argumentos de linha de comando

O comando a seguir define chaves e valores usando =:

dotnet run SecretKey="Secret key from command line"

O comando a seguir define chaves e valores usando /:

dotnet run /SecretKey "Secret key set from forward slash"

O comando a seguir define chaves e valores usando --:

dotnet run --SecretKey "Secret key set from double hyphen"

O valor-chave:

• Deve seguir =, ou a chave deve ter um prefixo de -- ou / quando o valor segue um espaço.
• Não é necessário se = for usado. Por exemplo, SomeKey=.

Dentro do mesmo comando, não misture pares chave-valor de argumento de linha de comando que usam = com pares chave-valor que usam um espaço.

Provedor de configuração de chave por arquivo

O KeyPerFileConfigurationProvider usa os arquivos de um diretório como pares chave-valor de configuração. A chave é o nome do arquivo. O valor é o conteúdo do arquivo. O provedor de configuração de chave por arquivo é usado em cenários de hospedagem do Docker.

Para ativar a configuração de chave por arquivo, chame o AddKeyPerFile método de extensão em uma instância do ConfigurationBuilder. O directoryPath para os arquivos deve ser um caminho absoluto.

As sobrecargas permitem especificar:

• Um Action<KeyPerFileConfigurationSource> delegado que configura a origem.
• Se o diretório é opcional e o caminho para o diretório.

O sublinhado duplo (__) é usado como um delimitador de chave de configuração em nomes de arquivo. Por exemplo, o nome Logging__LogLevel__System do arquivo produz a chave Logging:LogLevel:Systemde configuração .

Ligue ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo:

.ConfigureAppConfiguration((_, configuration) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");

    configuration.AddKeyPerFile(directoryPath: path, optional: true);
})

Provedor de configuração de memória

O MemoryConfigurationProvider usa uma coleção na memória como pares chave-valor de configuração.

O código a seguir adiciona uma coleção de memória ao sistema de configuração:

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["SecretKey"] = "Dictionary MyKey Value",
        ["TransientFaultHandlingOptions:Enabled"] = bool.TrueString,
        ["TransientFaultHandlingOptions:AutoRetryDelay"] = "00:00:07",
        ["Logging:LogLevel:Default"] = "Warning"
    });

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

No código anterior, MemoryConfigurationBuilderExtensions.AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<String,String>>) adiciona o provedor de memória após os provedores de configuração padrão. Para obter um exemplo de como ordenar os provedores de configuração, consulte Provedor de configuração XML.

Consulte também

• Configuração em .NET
• Host Genérico .NET
• Implementar um provedor de configuração personalizado