Configuração no ASP.NET CoreConfiguration in ASP.NET Core

Por Luke LathamBy Luke Latham

A configuração de aplicativos no ASP.NET Core se baseia em pares chave-valor estabelecidos por provedores de configuração.App configuration in ASP.NET Core is based on key-value pairs established by configuration providers. Os provedores de configuração leem os dados de configuração em pares chave-valor de várias fontes de configuração:Configuration providers read configuration data into key-value pairs from a variety of configuration sources:

  • Azure Key VaultAzure Key Vault
  • Configuração de Azure AppAzure App Configuration
  • Argumentos de linha de comandoCommand-line arguments
  • Provedores personalizados (instalados ou criados)Custom providers (installed or created)
  • Arquivos de diretórioDirectory files
  • Variáveis de ambienteEnvironment variables
  • Objetos do .NET na memóriaIn-memory .NET objects
  • Arquivos de configuraçõesSettings files

Os pacotes de configuração para cenários comuns do provedor de configuração (Microsoft.Extensions.Configuration) são incluídos implicitamente pela estrutura.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included implicitly by the framework.

Os pacotes de configuração para cenários comuns do provedor de configuração (Microsoft.Extensions.Configuration) são incluídos no metapacote Microsoft.AspNetCore.App.Configuration packages for common configuration provider scenarios (Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.

Os exemplos de código a seguir e no aplicativo de exemplo usam o namespace Microsoft.Extensions.Configuration:Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration namespace:

using Microsoft.Extensions.Configuration;

O padrão de opções é uma extensão dos conceitos de configuração descritos neste tópico.The options pattern is an extension of the configuration concepts described in this topic. As opções usam classes para representar grupos de configurações relacionadas.Options use classes to represent groups of related settings. Para obter mais informações, consulte Padrão de opções no ASP.NET Core.For more information, see Padrão de opções no ASP.NET Core.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Configuração do host versus do aplicativoHost versus app configuration

Antes do aplicativo ser configurado e iniciado, um host é configurado e iniciado.Before the app is configured and started, a host is configured and launched. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo.The host is responsible for app startup and lifetime management. O aplicativo e o host são configurados usando os provedores de configuração descritos neste tópico.Both the app and the host are configured using the configuration providers described in this topic. Os pares chave-valor de configuração do host também estão incluídos na configuração do aplicativo.Host configuration key-value pairs are also included in the app's configuration. Para saber mais sobre como os provedores de configuração são usados quando o host for compilado, e como as fontes de configuração afetam o host e a configuração, confira Conceitos básicos do ASP.NET Core.For more information on how the configuration providers are used when the host is built and how configuration sources affect host configuration, see Conceitos básicos do ASP.NET Core.

Configuração padrãoDefault configuration

Aplicativos Web baseados em modelos dotnet new do ASP.NET Core chamam CreateDefaultBuilder ao criar um host.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder fornece a configuração padrão para o aplicativo na seguinte ordem:CreateDefaultBuilder provides default configuration for the app in the following order:

O seguinte se aplica a aplicativos que usam o host genérico.The following applies to apps using the Generic Host. Para obter detalhes sobre a configuração padrão ao usar o host da Web, confira a versão do ASP.NET Core 2.2 deste tópico.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

Aplicativos Web baseados em modelos dotnet new do ASP.NET Core chamam CreateDefaultBuilder ao criar um host.Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a host. CreateDefaultBuilder fornece a configuração padrão para o aplicativo na seguinte ordem:CreateDefaultBuilder provides default configuration for the app in the following order:

O seguinte se aplica a aplicativos que usam o host da Web.The following applies to apps using the Web Host. Para obter detalhes sobre a configuração padrão ao usar o host genérico, confira versão mais recente deste tópico.For details on the default configuration when using the Generic Host, see the latest version of this topic.

SegurançaSecurity

Adote as seguintes práticas para proteger dados de configuração confidenciais:Adopt the following practices to secure sensitive configuration data:

  • Nunca armazene senhas ou outros dados confidenciais no código do provedor de configuração ou nos arquivos de configuração de texto sem formatação.Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
  • Não use segredos de produção em ambientes de teste ou de desenvolvimento.Don't use production secrets in development or test environments.
  • Especifique segredos fora do projeto para que eles não sejam acidentalmente comprometidos com um repositório de código-fonte.Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.

Para mais informações, consulte os seguintes tópicos:For more information, see the following topics:

O Azure Key Vault armazena os segredos do aplicativo com segurança para aplicativos ASP.NET Core.Azure Key Vault safely stores app secrets for ASP.NET Core apps. Para obter mais informações, consulte Azure Key Vault provedor de configuração no ASP.NET Core.For more information, see Azure Key Vault provedor de configuração no ASP.NET Core.

Dados de configuração hierárquicaHierarchical configuration data

A API de Configuração é capaz de manter dados de configuração hierárquica nivelando os dados hierárquicos com o uso de um delimitador nas chaves de configuração.The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

No seguinte arquivo JSON, há quatro chaves em uma hierarquia estruturada com duas seções:In the following JSON file, four keys exist in a structured hierarchy of two sections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

Quando o arquivo é lido na configuração, ocorre a criação de chaves exclusivas para manter a estrutura hierárquica de dados original da fonte de configuração.When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure of the configuration source. As seções e as chaves são niveladas usando dois-pontos (:) para manter a estrutura original:The sections and keys are flattened with the use of a colon (:) to maintain the original structure:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Os métodos GetSection e GetChildren estão disponíveis para isolar as seções e os filhos de uma seção nos dados de configuração.GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration data. Esses métodos serão descritos posteriormente em GetSection, GetChildren e Exists.These methods are described later in GetSection, GetChildren, and Exists.

ConvençõesConventions

Origens e provedoresSources and providers

Na inicialização do aplicativo, as fontes de configuração são lidas na ordem especificada pelos provedores de configuração.At app startup, configuration sources are read in the order that their configuration providers are specified.

Os provedores de configuração que implementam a detecção de alteração podem recarregar a configuração quando uma configuração subjacente for alterada.Configuration providers that implement change detection have the ability to reload configuration when an underlying setting is changed. Por exemplo, o Provedor de configuração do arquivo (descrito mais adiante neste tópico) e o Provedor de configuração do Azure Key Vault implementam a detecção de alteração.For example, the File Configuration Provider (described later in this topic) and the Azure Key Vault Configuration Provider implement change detection.

IConfiguration está disponível no contêiner DI (injeção de dependência) do aplicativo.IConfiguration is available in the app's dependency injection (DI) container. IConfiguration pode ser injetado em um PageModel do Razor Pages para obter a configuração para a classe:IConfiguration can be injected into a Razor Pages PageModel to obtain configuration for the class:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    // The _config local variable is used to obtain configuration 
    // throughout the class.
}

Os provedores de configuração não podem utilizar a DI, pois ela não é disponibilizada quando eles são configurados pelo host.Configuration providers can't utilize DI, as it's not available when they're set up by the host.

NovasKeys

As chaves de configuração adotam as convenções a seguir:Configuration keys adopt the following conventions:

  • As chaves não diferenciam maiúsculas de minúsculas.Keys are case-insensitive. Por exemplo, ConnectionString e connectionstring são tratados como chaves equivalentes.For example, ConnectionString and connectionstring are treated as equivalent keys.
  • Se um valor para a mesma chave for definido pelos mesmos provedores de configuração, ou por outros, o último valor definido na chave será o valor usado.If a value for the same key is set by the same or different configuration providers, the last value set on the key is the value used.
  • Chaves hierárquicasHierarchical keys
    • Ao interagir com a API de configuração, um separador de dois-pontos (:) funciona em todas as plataformas.Within the Configuration API, a colon separator (:) works on all platforms.
    • Nas variáveis de ambiente, talvez um separador de dois-pontos não funcione em todas as plataformas.In environment variables, a colon separator may not work on all platforms. Um sublinhado duplo (__) é compatível com todas as plataformas e é convertido automaticamente em dois-pontos.A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • No Azure Key Vault, as chaves hierárquicas usam -- (dois traços) como separador.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. Você deve fornecer o código para substituir os traços por dois-pontos quando os segredos forem carregados na configuração do aplicativo.You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • O ConfigurationBinder dá suporte a matrizes de associação para objetos usando os índices em chaves de configuração.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. A associação de matriz está descrita na seção Associar uma matriz a uma classe.Array binding is described in the Bind an array to a class section.

ValoresValues

Os valores de configuração adotam as convenções a seguir:Configuration values adopt the following conventions:

  • Os valores são cadeias de caracteres.Values are strings.
  • Não é possível armazenar valores nulos na configuração ou associá-los a objetos.Null values can't be stored in configuration or bound to objects.

ProvedoresProviders

A tabela a seguir mostra os provedores de configuração disponíveis para aplicativos ASP.NET Core.The following table shows the configuration providers available to ASP.NET Core apps.

ProviderProvider Fornece a configuração de …Provides configuration from…
Provedor de Configuração do Azure Key Vault (tópicos de Segurança)Azure Key Vault Configuration Provider (Security topics) Azure Key VaultAzure Key Vault
Provedor da Configuração de Aplicativos do Azure (documentação do Azure)Azure App Configuration Provider (Azure documentation) Configuração de Azure AppAzure App Configuration
Provedor de Configuração de Linha de ComandoCommand-line Configuration Provider Parâmetros de linha de comandoCommand-line parameters
Provedor de Configuração personalizadoCustom configuration provider Fonte personalizadaCustom source
Provedor de Configuração de Variáveis de AmbienteEnvironment Variables Configuration Provider Variáveis de ambienteEnvironment variables
Provedor de Configuração de ArquivoFile Configuration Provider Arquivos (INI, JSON, XML)Files (INI, JSON, XML)
Provedor de Configuração de Chave por ArquivoKey-per-file Configuration Provider Arquivos de diretórioDirectory files
Provedor de Configuração de MemóriaMemory Configuration Provider Coleções na memóriaIn-memory collections
Segredos do usuário (Gerenciador de Segredo) (tópicos de Segurança)User secrets (Secret Manager) (Security topics) Arquivo no diretório de perfil do usuárioFile in the user profile directory

Na inicialização, as fontes de configuração são lidas na ordem especificada pelos provedores de configuração.Configuration sources are read in the order that their configuration providers are specified at startup. Os provedores de configuração descritos neste tópico estão descritos em ordem alfabética, não na ordem na qual seu código pode organizá-los.The configuration providers described in this topic are described in alphabetical order, not in the order that your code may arrange them. Organize os provedores de configuração em seu código para atender às suas prioridades para as fontes de configuração subjacentes.Order configuration providers in your code to suit your priorities for the underlying configuration sources.

Uma sequência comum de provedores de configuração é:A typical sequence of configuration providers is:

  1. Arquivos (appsettings.json, appsettings.{Environment}.json, em que {Environment} é o ambiente de hospedagem atual do aplicativo)Files (appsettings.json, appsettings.{Environment}.json, where {Environment} is the app's current hosting environment)
  2. Azure Key VaultAzure Key Vault
  3. Segredos do usuário (Gerenciador de Segredo) (apenas no ambiente de desenvolvimento)User secrets (Secret Manager) (Development environment only)
  4. Variáveis de ambienteEnvironment variables
  5. Argumentos de linha de comandoCommand-line arguments

Uma prática comum é posicionar o Provedor de Configuração de Linha de Comando por último em uma série de provedores, a fim de permitir que os argumentos de linha de comando substituam a configuração definida por outros provedores.A common practice is to position the Command-line Configuration Provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

A sequência anterior de provedores é usada quando você inicializa um novo construtor de host com o CreateDefaultBuilder.The preceding sequence of providers is used when you initialize a new host builder with CreateDefaultBuilder. Para obter mais informações, confira a seção Configuração padrão.For more information, see the Default configuration section.

Configurar o construtor de host com ConfigureHostConfigurationConfigure the host builder with ConfigureHostConfiguration

Para configurar o construtor de host, chame ConfigureHostConfiguration e forneça a configuração.To configure the host builder, call ConfigureHostConfiguration and supply the configuration. ConfigureHostConfiguration é usado para inicializar o IHostEnvironment para uso posterior no processo de build.ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process. ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos.ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHostConfiguration(config =>
        {
            var dict = new Dictionary<string, string>
            {
                {"MemoryCollectionKey1", "value1"},
                {"MemoryCollectionKey2", "value2"}
            };

            config.AddInMemoryCollection(dict);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Configurar o construtor de host com UseConfigurationConfigure the host builder with UseConfiguration

Para configurar o construtor de host, chame UseConfiguration no construtor de host com a configuração.To configure the host builder, call UseConfiguration on the host builder with the configuration.

public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
    var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

    var config = new ConfigurationBuilder()
        .AddInMemoryCollection(dict)
        .Build();

    return WebHost.CreateDefaultBuilder(args)
        .UseConfiguration(config)
        .UseStartup<Startup>();
}

ConfigureAppConfigurationConfigureAppConfiguration

Chame ConfigureAppConfiguration ao criar o host para especificar os provedores de configuração do aplicativo, além daqueles adicionados automaticamente por CreateDefaultBuilder:Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in addition to those added automatically by CreateDefaultBuilder:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Substituir a configuração anterior por argumentos de linha de comandoOverride previous configuration with command-line arguments

Para fornecer a configuração de aplicativos que pode ser substituída por argumentos de linha de comando, chame AddCommandLine por último:To provide app configuration that can be overridden with command-line arguments, call AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

Remover provedores adicionados por CreateDefaultBuilderRemove providers added by CreateDefaultBuilder

Para remover os provedores adicionados por CreateDefaultBuilder, chame Clear no IConfigurationBuilder. Sources primeiro:To remove the providers added by CreateDefaultBuilder, call Clear on the IConfigurationBuilder.Sources first:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.Sources.Clear();
    // Add providers here
})

Consumir a configuração durante a inicialização do aplicativoConsume configuration during app startup

a configuração fornecida para o aplicativo no ConfigureAppConfiguration está disponível durante a inicialização do aplicativo, incluindo Startup.ConfigureServices.Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup, including Startup.ConfigureServices. Para saber mais, confira a seção Access configuration during startup (Configuração de acesso durante a inicialização).For more information, see the Access configuration during startup section.

Provedor de Configuração de Linha de ComandoCommand-line Configuration Provider

O CommandLineConfigurationProvider carrega a configuração dos pares chave-valor do argumento de linha de comando em runtime.The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at runtime.

Para ativar a configuração de linha de comando, o método de extensão AddCommandLine é chamado em uma instância do ConfigurationBuilder.To activate command-line configuration, the AddCommandLine extension method is called on an instance of ConfigurationBuilder.

AddCommandLine é chamado automaticamente quando CreateDefaultBuilder(string []) é chamado.AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. Para obter mais informações, confira a seção Configuração padrão.For more information, see the Default configuration section.

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

CreateDefaultBuilder adiciona o Provedor de Configuração de Linha de Comando por último.CreateDefaultBuilder adds the Command-line Configuration Provider last. Os argumentos de linha de comando passados em runtime substituem a configuração definida por outros provedores.Command-line arguments passed at runtime override configuration set by the other providers.

CreateDefaultBuilder age quando o host é construído.CreateDefaultBuilder acts when the host is constructed. Portanto, a configuração de linha de comando ativada por CreateDefaultBuilder pode afetar como o host é configurado.Therefore, command-line configuration activated by CreateDefaultBuilder can affect how the host is configured.

Para aplicativos baseados nos modelos do ASP.NET Core, AddCommandLine já foi chamado pelo CreateDefaultBuilder.For apps based on the ASP.NET Core templates, AddCommandLine has already been called by CreateDefaultBuilder. Para adicionar outros provedores de configuração e manter a capacidade de substituir a configuração desses provedores por argumentos de linha de comando, chame os provedores adicionais do aplicativo em ConfigureAppConfiguration e chame AddCommandLine por último.To add additional configuration providers and maintain the ability to override configuration from those providers with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call other providers here
    config.AddCommandLine(args);
})

ExemploExample

O aplicativo de exemplo aproveita o método de conveniência estático CreateDefaultBuilder para criar o host, que inclui uma chamada para AddCommandLine.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddCommandLine.

  1. Abra um prompt de comando no diretório do projeto.Open a command prompt in the project's directory.
  2. Forneça um argumento de linha de comando para o comando dotnet run, dotnet run CommandLineKey=CommandLineValue.Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue.
  3. Quando o aplicativo estiver em execução, abra um navegador para o aplicativo em http://localhost:5000.After the app is running, open a browser to the app at http://localhost:5000.
  4. Observe que a saída contém o par chave-valor do argumento de linha de comando de configuração fornecido para dotnet run.Observe that the output contains the key-value pair for the configuration command-line argument provided to dotnet run.

ArgumentsArguments

O valor deve vir após um sinal de igual (=), ou a chave deve ter um prefixo (-- ou /) quando o valor vier após um espaço.The value must follow an equals sign (=), or the key must have a prefix (-- or /) when the value follows a space. O valor não é necessário se um sinal de igual é usado (por exemplo, CommandLineKey=).The value isn't required if an equals sign is used (for example, CommandLineKey=).

Prefixo da chaveKey prefix ExemploExample
Nenhum prefixoNo prefix CommandLineKey1=value1
Dois traços (--)Two dashes (--) --CommandLineKey2=value2, --CommandLineKey2 value2--CommandLineKey2=value2, --CommandLineKey2 value2
Barra (/)Forward slash (/) /CommandLineKey3=value3, /CommandLineKey3 value3/CommandLineKey3=value3, /CommandLineKey3 value3

No mesmo comando, não combine pares chave-valor do argumento de linha de comando que usam um sinal de igual com pares chave-valor que usam um espaço.Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-value pairs that use a space.

Exemplo de comandos:Example commands:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

Mapeamentos de comutadorSwitch mappings

Os mapeamentos de comutador permitem fornecer a lógica de substituição do nome da chave.Switch mappings allow key name replacement logic. Quando você cria manualmente a configuração com um ConfigurationBuilder, pode fornecer um dicionário de substituições de opções para o método AddCommandLine.When you manually build configuration with a ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.

Ao ser usado, o dicionário de mapeamentos de comutador é verificado para oferecer uma chave que corresponda à chave fornecida por um argumento de linha de comando.When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. Se a chave de linha de comando for encontrada no dicionário, o valor do dicionário (a substituição da chave) será passado de volta para definir o par chave-valor na configuração do aplicativo.If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the key-value pair into the app's configuration. Um mapeamento de comutador é necessário para qualquer chave de linha de comando prefixada com um traço único (-).A switch mapping is required for any command-line key prefixed with a single dash (-).

Regras de chave do dicionário de mapeamentos de comutador:Switch mappings dictionary key rules:

  • Os comutadores devem começar com um traço (-) ou traço duplo (--).Switches must start with a dash (-) or double-dash (--).
  • O dicionário de mapeamentos de comutador chave não deve conter chaves duplicadas.The switch mappings dictionary must not contain duplicate keys.

Crie um dicionário de mapeamentos de opção.Create a switch mappings dictionary. No exemplo a seguir, dois mapeamentos de opção são criados:In the following example, two switch mappings are created:

public static readonly Dictionary<string, string> _switchMappings = 
    new Dictionary<string, string>
    {
        { "-CLKey1", "CommandLineKey1" },
        { "-CLKey2", "CommandLineKey2" }
    };

Quando o host for criado, chame AddCommandLine com o dicionário de mapeamentos de opção:When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddCommandLine(args, _switchMappings);
})

Para aplicativos que usam mapeamentos de opção, a chamada CreateDefaultBuilder para não deve passar argumentos.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. A chamada AddCommandLine do método CreateDefaultBuilder não inclui opções mapeadas, e não é possível passar o dicionário de mapeamento de opções para CreateDefaultBuilder.The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. A solução não é passar os argumentos para CreateDefaultBuilder, mas, em vez disso, permitir que o método AddCommandLine do método ConfigurationBuilder processe os dois argumentos e o dicionário de mapeamento de opções.The solution isn't to pass the arguments to CreateDefaultBuilder but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping dictionary.

Depois que o dicionário de mapeamentos de comutador for criado, ele conterá os dados mostrados na tabela a seguir.After the switch mappings dictionary is created, it contains the data shown in the following table.

ChaveKey ValorValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

Se as chaves mapeadas para opção forem usadas ao iniciar o aplicativo, a configuração receberá o valor de configuração na chave fornecida pelo dicionário:If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the key supplied by the dictionary:

dotnet run -CLKey1=value1 -CLKey2=value2

Após a execução do comando anterior, a configuração conterá os valores mostrados na tabela a seguir.After running the preceding command, configuration contains the values shown in the following table.

ChaveKey ValorValue
CommandLineKey1 value1
CommandLineKey2 value2

Provedor de Configuração de Variáveis de AmbienteEnvironment Variables Configuration Provider

O EnvironmentVariablesConfigurationProvider carrega a configuração dos pares chave-valor da variável de ambiente em runtime.The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at runtime.

Para ativar a configuração das variáveis de ambiente, chame o método de extensão AddEnvironmentVariables em uma instância do ConfigurationBuilder.To activate environment variables configuration, call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder.

Ao trabalhar com chaves hierárquicas em variáveis ​​de ambiente, um separador de dois-pontos (:) pode não funcionar em todas as plataformas (por exemplo, Bash).When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). Um sublinhado duplo (__) é compatível com todas as plataformas e é substituído automaticamente por dois-pontos.A double underscore (__) is supported by all platforms and is automatically replaced by a colon.

O Serviço de Aplicativo do Azure permite que você defina variáveis de ambiente no portal do Azure que podem substituir a configuração do aplicativo usando o Provedor de Configuração de Variáveis de Ambiente.Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Para saber mais, confira Aplicativos do Azure: substituir a configuração do aplicativo usando o portal do Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

AddEnvironmentVariables é usado para carregar variáveis de ambiente com prefixo DOTNET_ para configuração de host quando um novo construtor de host é inicializado com o host genérico e CreateDefaultBuilder é chamado.AddEnvironmentVariables is used to load environment variables prefixed with DOTNET_ for host configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is called. Para obter mais informações, confira a seção Configuração padrão.For more information, see the Default configuration section.

AddEnvironmentVariables é usado para carregar variáveis de ambiente com prefixo ASPNETCORE_ para configuração de host quando um novo construtor de host é inicializado com o host da Web e CreateDefaultBuilder é chamado.AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is called. Para obter mais informações, confira a seção Configuração padrão.For more information, see the Default configuration section.

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

  • Configuração de aplicativo em variáveis de ambiente sem prefixos chamando AddEnvironmentVariables sem um prefixo.App configuration from unprefixed environment variables by calling AddEnvironmentVariables without a prefix.
  • Configuração opcional de arquivos appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json files.
  • Segredos do usuário (Gerenciador de Segredo) no ambiente de desenvolvimento.User secrets (Secret Manager) in the Development environment.
  • Argumentos de linha de comando.Command-line arguments.

O Provedor de Configuração de Variáveis de Ambiente é chamado depois que a configuração é estabelecida por meio dos segredos do usuário e dos arquivos appsettings.The Environment Variables Configuration Provider is called after configuration is established from user secrets and appsettings files. Chamar o provedor nessa posição permite que as variáveis de ambiente sejam lidas em runtime para substituir a configuração definida por segredos do usuário e arquivos appsettings.Calling the provider in this position allows the environment variables read at runtime to override configuration set by user secrets and appsettings files.

Se precisar fornecer configuração do aplicativo com base em variáveis de ambiente adicionais, chame os provedores adicionais do aplicativo no ConfigureAppConfiguratione chame AddEnvironmentVariables com o prefixo.If you need to provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

.ConfigureAppConfiguration((hostingContext, config) =>
{
    // Call additional providers here as needed.
    // Call AddEnvironmentVariables last if you need to allow
    // environment variables to override values from other 
    // providers.
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}

ExemploExample

O aplicativo de exemplo aproveita o método de conveniência estático CreateDefaultBuilder para criar o host, que inclui uma chamada para AddEnvironmentVariables.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes a call to AddEnvironmentVariables.

  1. Execute o aplicativo de exemplo.Run the sample app. Abra um navegador para o aplicativo em http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Observe que a saída contém o par chave-valor da variável de ambiente ENVIRONMENT.Observe that the output contains the key-value pair for the environment variable ENVIRONMENT. O valor reflete o ambiente no qual o aplicativo está em execução, normalmente Development ao executar localmente.The value reflects the environment in which the app is running, typically Development when running locally.

Para encurtar a lista de variáveis de ambiente renderizadas pelo aplicativo, o aplicativo filtra as variáveis de ambiente.To keep the list of environment variables rendered by the app short, the app filters environment variables. Confira o arquivo Pages/Index.cshtml.cs do aplicativo de exemplo.See the sample app's Pages/Index.cshtml.cs file.

Se você quiser expor todas as variáveis de ambiente disponíveis para o aplicativo, altere o FilteredConfiguration em Pages/Index.cshtml.cs para o seguinte:If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PrefixosPrefixes

Variáveis de ambiente carregadas na configuração do aplicativo são filtradas quando você fornece um prefixo para o método AddEnvironmentVariables.Environment variables loaded into the app's configuration are filtered when you supply a prefix to the AddEnvironmentVariables method. Por exemplo, para filtrar as variáveis de ambiente no prefixo CUSTOM_, forneça o prefixo para o provedor de configuração:For example, to filter environment variables on the prefix CUSTOM_, supply the prefix to the configuration provider:

var config = new ConfigurationBuilder()
    .AddEnvironmentVariables("CUSTOM_")
    .Build();

O prefixo é removido na criação dos pares chave-valor de configuração.The prefix is stripped off when the configuration key-value pairs are created.

Quando o construtor de host é criado, a configuração do host é fornecida por variáveis de ambiente.When the host builder is created, host configuration is provided by environment variables. Para obter mais informações sobre o prefixo usado para essas variáveis de ambiente, confira a seção Configuração padrão.For more information on the prefix used for these environment variables, see the Default configuration section.

Prefixos de cadeia de conexãoConnection string prefixes

A API de configuração tem regras de processamento especiais para quatro variáveis de ambiente de cadeia de conexão envolvidas na configuração de cadeias de conexão do Azure para o ambiente de aplicativo.The Configuration API has special processing rules for four connection string environment variables involved in configuring Azure connection strings for the app environment. As variáveis de ambiente com os prefixos mostrados na tabela são carregadas no aplicativo se nenhum prefixo for fornecido para AddEnvironmentVariables.Environment variables with the prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables.

Prefixo da cadeia de conexãoConnection string prefix ProviderProvider
CUSTOMCONNSTR_ Provedor personalizadoCustom provider
MYSQLCONNSTR_ MySQLMySQL
SQLAZURECONNSTR_ Banco de Dados SQL do AzureAzure SQL Database
SQLCONNSTR_ SQL ServerSQL Server

Quando uma variável de ambiente for descoberta e carregada na configuração com qualquer um dos quatro prefixos mostrados na tabela:When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in the table:

  • 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).The configuration key is created by removing the environment variable prefix and adding a configuration key section (ConnectionStrings).
  • Um novo par chave-valor de configuração é criado para representar o provedor de conexão de banco de dados (exceto para CUSTOMCONNSTR_, que não tem um provedor indicado).A new configuration key-value pair is created that represents the database connection provider (except for CUSTOMCONNSTR_, which has no stated provider).
Chave de variável de ambienteEnvironment variable key Chave de configuração convertidaConverted configuration key Entrada de configuração do provedorProvider configuration entry
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Entrada de configuração não criada.Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valor: MySql.Data.MySqlClientValue: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Chave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valor: System.Data.SqlClientValue: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Chave: ConnectionStrings:<KEY>_ProviderName:Key: ConnectionStrings:<KEY>_ProviderName:
Valor: System.Data.SqlClientValue: System.Data.SqlClient

Provedor de Configuração de ArquivoFile Configuration Provider

FileConfigurationProvider é a classe base para carregamento da configuração do sistema de arquivos.FileConfigurationProvider is the base class for loading configuration from the file system. Os provedores de configuração a seguir são dedicados a tipos específicos de arquivos:The following configuration providers are dedicated to specific file types:

Provedor de Configuração INIINI Configuration Provider

O IniConfigurationProvider carrega a configuração de pares chave-valor do arquivo INI em runtime.The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.

Para ativar a configuração de arquivo INI, chame o método de extensão AddIniFile em uma instância do ConfigurationBuilder.To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.

Os dois-pontos podem ser usados como um delimitador de seção na configuração do arquivo INI.The colon can be used to as a section delimiter in INI file configuration.

As sobrecargas permitem especificar:Overloads permit specifying:

  • Se o arquivo é opcional.Whether the file is optional.
  • Se a configuração será recarregada caso o arquivo seja alterado.Whether the configuration is reloaded if the file changes.
  • O IFileProvider usado para acessar o arquivo.The IFileProvider used to access the file.

Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddIniFile(
        "config.ini", optional: true, reloadOnChange: true);
})

Um exemplo genérico de um arquivo de configuração INI:A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

O arquivo de configuração anterior carrega as seguintes chaves com value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:subsection:keysection1:subsection:key
  • section2:subsection0:keysection2:subsection0:key
  • section2:subsection1:keysection2:subsection1:key

Provedor de Configuração JSONJSON Configuration Provider

O JsonConfigurationProvider carrega a configuração de pares chave-valor do arquivo JSON em runtime.The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.

Para ativar a configuração de arquivo JSON, chame o método de extensão AddJsonFile em uma instância do ConfigurationBuilder.To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.

As sobrecargas permitem especificar:Overloads permit specifying:

  • Se o arquivo é opcional.Whether the file is optional.
  • Se a configuração será recarregada caso o arquivo seja alterado.Whether the configuration is reloaded if the file changes.
  • O IFileProvider usado para acessar o arquivo.The IFileProvider used to access the file.

AddJsonFile é chamado automaticamente duas vezes quando você inicializa um novo construtor de host com CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new host builder with CreateDefaultBuilder. O método é chamado para carregar a configuração de:The method is called to load configuration from:

  • appsettings.json – Esse arquivo é lido primeiro.appsettings.json – This file is read first. A versão do ambiente do arquivo pode substituir os valores fornecidos pelo arquivo appsettings.json.The environment version of the file can override the values provided by the appsettings.json file.
  • appsettings.{Environment}.json – A versão de ambiente do arquivo é carregada com base em IHostingEnvironment.EnvironmentName.appsettings.{Environment}.json – The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

Para obter mais informações, confira a seção Configuração padrão.For more information, see the Default configuration section.

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

O Provedor de Configuração JSON é estabelecido primeiro.The JSON Configuration Provider is established first. Portanto, os segredos do usuário, as variáveis de ambiente e os argumentos de linha de comando substituem a configuração definida pelos arquivos appsettings.Therefore, user secrets, environment variables, and command-line arguments override configuration set by the appsettings files.

Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo para arquivos que não sejam appsettings.json e appsettings.{Environment}.json:Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other than appsettings.json and appsettings.{Environment}.json:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddJsonFile(
        "config.json", optional: true, reloadOnChange: true);
})

ExemploExample

O aplicativo de exemplo aproveita o método de conveniência estático CreateDefaultBuilder para criar o host, que inclui duas chamadas para AddJsonFile.The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile. A configuração é carregada de appsettings.json e de appsettings.{Environment}.json.Configuration is loaded from appsettings.json and appsettings.{Environment}.json.

  1. Execute o aplicativo de exemplo.Run the sample app. Abra um navegador para o aplicativo em http://localhost:5000.Open a browser to the app at http://localhost:5000.
  2. Observe que a saída contém pares chave-valor para a configuração mostrada na tabela de acordo com o ambiente.Observe that the output contains key-value pairs for the configuration shown in the table depending on the environment. Chaves de configuração de registro usam os dois-pontos (:) como um separador hierárquico.Logging configuration keys use the colon (:) as a hierarchical separator.
ChaveKey Valor de DesenvolvimentoDevelopment Value Valor de ProduçãoProduction Value
Logging:LogLevel:SystemLogging:LogLevel:System InformaçõesInformation InformaçõesInformation
Logging:LogLevel:MicrosoftLogging:LogLevel:Microsoft InformaçõesInformation InformaçõesInformation
Logging:LogLevel:DefaultLogging:LogLevel:Default DepurarDebug ErroError
AllowedHostsAllowedHosts * *

Provedor de Configuração XMLXML Configuration Provider

O XmlConfigurationProvider carrega a configuração de pares chave-valor do arquivo XML em runtime.The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.

Para ativar a configuração de arquivo XML, chame o método de extensão AddXmlFile em uma instância do ConfigurationBuilder.To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.

As sobrecargas permitem especificar:Overloads permit specifying:

  • Se o arquivo é opcional.Whether the file is optional.
  • Se a configuração será recarregada caso o arquivo seja alterado.Whether the configuration is reloaded if the file changes.
  • O IFileProvider usado para acessar o arquivo.The IFileProvider used to access the file.

O nó raiz do arquivo de configuração é ignorado quando os pares chave-valor da configuração são criados.The root node of the configuration file is ignored when the configuration key-value pairs are created. Não especifique um DTD (definição de tipo de documento) ou um namespace no arquivo.Don't specify a Document Type Definition (DTD) or namespace in the file.

Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddXmlFile(
        "config.xml", optional: true, reloadOnChange: true);
})

Os arquivos de configuração XML podem usar nomes de elemento distintos para seções repetidas:XML configuration files can use distinct element names for repeating sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <section0>
    <key0>value</key0>
    <key1>value</key1>
  </section0>
  <section1>
    <key0>value</key0>
    <key1>value</key1>
  </section1>
</configuration>

O arquivo de configuração anterior carrega as seguintes chaves com value:The previous configuration file loads the following keys with value:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1

Elementos repetidos que usam o mesmo nome de elemento funcionarão se o atributo name for usado para diferenciar os elementos:Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

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

O arquivo de configuração anterior carrega as seguintes chaves com value:The previous configuration file loads the following keys with value:

  • section:section0:key:key0section:section0:key:key0
  • section:section0:key:key1section:section0:key:key1
  • section:section1:key:key0section:section1:key:key0
  • section:section1:key:key1section:section1:key:key1

É possível usar atributos para fornecer valores:Attributes can be used to supply values:

<?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:The previous configuration file loads the following keys with value:

  • key:attributekey:attribute
  • section:key:attributesection:key:attribute

Provedor de Configuração de Chave por ArquivoKey-per-file Configuration Provider

O KeyPerFileConfigurationProvider usa arquivos do diretório como pares chave-valor de configuração.The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. A chave é o nome do arquivo.The key is the file name. O valor contém o conteúdo do arquivo.The value contains the file's contents. O Provedor de Configuração de Chave por arquivo é usado em cenários de hospedagem do Docker.The Key-per-file Configuration Provider is used in Docker hosting scenarios.

Para ativar a configuração de chave por arquivo, chame o método de extensão AddKeyPerFile em uma instância do ConfigurationBuilder.To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of ConfigurationBuilder. O directoryPath para os arquivos deve ser um caminho absoluto.The directoryPath to the files must be an absolute path.

As sobrecargas permitem especificar:Overloads permit specifying:

  • Um delegado Action<KeyPerFileConfigurationSource> que configura a origem.An Action<KeyPerFileConfigurationSource> delegate that configures the source.
  • Se o diretório é opcional, e o caminho para o diretório.Whether the directory is optional and the path to the directory.

O sublinhado duplo (__) é usado como um delimitador de chave de configuração em nomes de arquivo.The double-underscore (__) is used as a configuration key delimiter in file names. Por exemplo, o nome do arquivo Logging__LogLevel__System produz a chave de configuração Logging:LogLevel:System.For example, the file name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System.

Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo:Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    var path = Path.Combine(
        Directory.GetCurrentDirectory(), "path/to/files");
    config.AddKeyPerFile(directoryPath: path, optional: true);
})

Provedor de Configuração de MemóriaMemory Configuration Provider

O MemoryConfigurationProvider usa uma coleção na memória como pares chave-valor de configuração.The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.

Para ativar a configuração de coleção na memória, chame o método de extensão AddInMemoryCollection em uma instância do ConfigurationBuilder.To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance of ConfigurationBuilder.

O provedor de configuração pode ser inicializado com um IEnumerable<KeyValuePair<String,String>>.The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>>.

Chame ConfigureAppConfiguration ao criar o host para especificar a configuração do aplicativo.Call ConfigureAppConfiguration when building the host to specify the app's configuration.

No exemplo a seguir, um dicionário de configuração é criado:In the following example, a configuration dictionary is created:

public static readonly Dictionary<string, string> _dict = 
    new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

O dicionário é usado com uma chamada para AddInMemoryCollection a fim de fornecer a configuração:The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddInMemoryCollection(_dict);
})

GetValueGetValue

ConfigurationBinder. GetValue <T > extrai um único valor da configuração com uma chave especificada e a converte para o tipo de não coleção especificado.ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified noncollection type. Uma sobrecarga aceita um valor padrão.An overload accepts a default value.

O exemplo a seguir:The following example:

  • extrai o valor de cadeia de caracteres da configuração com a chave NumberKey.Extracts the string value from configuration with the key NumberKey. Se NumberKey não for encontrado nas chaves de configuração, será usado o valor padrão 99.If NumberKey isn't found in the configuration keys, the default value of 99 is used.
  • Digita o valor como um int.Types the value as an int.
  • Armazena o valor na propriedade NumberConfig para uso pela página.Stores the value in the NumberConfig property for use by the page.
public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public int NumberConfig { get; private set; }

    public void OnGet()
    {
        NumberConfig = _config.GetValue<int>("NumberKey", 99);
    }
}

GetSection, GetChildren e ExistsGetSection, GetChildren, and Exists

Para os exemplos a seguir, considere o seguinte arquivo JSON.For the examples that follow, consider the following JSON file. Há quatro chaves em duas seções, cada uma delas inclui um par de subseções:Four keys are found across two sections, one of which includes a pair of subsections:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  },
  "section2": {
    "subsection0" : {
      "key0": "value",
      "key1": "value"
    },
    "subsection1" : {
      "key0": "value",
      "key1": "value"
    }
  }
}

Quando o arquivo é lido na configuração, as seguintes chaves hierárquicas exclusivas são criadas para conter os valores de configuração:When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration values:

  • section0:key0section0:key0
  • section0:key1section0:key1
  • section1:key0section1:key0
  • section1:key1section1:key1
  • section2:subsection0:key0section2:subsection0:key0
  • section2:subsection0:key1section2:subsection0:key1
  • section2:subsection1:key0section2:subsection1:key0
  • section2:subsection1:key1section2:subsection1:key1

GetSectionGetSection

IConfiguration.GetSection extrai uma subseção de configuração com a chave de subseção especificada.IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.

Para retornar um IConfigurationSection que contenha apenas os pares chave-valor em section1, chame GetSection e forneça o nome da seção:To return an IConfigurationSection containing only the key-value pairs in section1, call GetSection and supply the section name:

var configSection = _config.GetSection("section1");

configSection não tem um valor, apenas uma chave e um caminho.The configSection doesn't have a value, only a key and a path.

Da mesma forma, para obter os valores de chaves em section2:subsection0, chame GetSection e forneça o caminho de seção:Similarly, to obtain the values for keys in section2:subsection0, call GetSection and supply the section path:

var configSection = _config.GetSection("section2:subsection0");

GetSection nunca retorna null.GetSection never returns null. Se uma seção correspondente não for encontrada, um IConfigurationSection vazio será retornado.If a matching section isn't found, an empty IConfigurationSection is returned.

Quando GetSection retorna uma seção correspondente, Value não é preenchido.When GetSection returns a matching section, Value isn't populated. Key e Path são retornados quando a seção existe.A Key and Path are returned when the section exists.

GetChildrenGetChildren

Uma chamada para IConfiguration.GetChildren em section2 obtém um IEnumerable<IConfigurationSection> que inclui:A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:

  • subsection0
  • subsection1
var configSection = _config.GetSection("section2");

var children = configSection.GetChildren();

ExistsExists

Use ConfigurationExtensions.Exists para determinar se há uma seção de configuração:Use ConfigurationExtensions.Exists to determine if a configuration section exists:

var sectionExists = _config.GetSection("section2:subsection2").Exists();

Considerando os dados de exemplo, sectionExists é false, pois não existe uma seção section2:subsection2 nos dados de configuração.Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the configuration data.

Associar a uma classeBind to a class

A configuração pode ser associada a classes que representam grupos de configurações relacionadas usando o padrão de opções.Configuration can be bound to classes that represent groups of related settings using the options pattern. Para obter mais informações, consulte Padrão de opções no ASP.NET Core.For more information, see Padrão de opções no ASP.NET Core.

Os valores de configuração retornam como cadeias de caracteres, mas chamar Bind permite a construção de objetos POCO.Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.

O aplicativo de exemplo contém um modelo Starship (Models/Starship.cs):The sample app contains a Starship model (Models/Starship.cs):

public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}
public class Starship
{
    public string Name { get; set; }
    public string Registry { get; set; }
    public string Class { get; set; }
    public decimal Length { get; set; }
    public bool Commissioned { get; set; }
}

A seção starship do arquivo starship.json cria a configuração quando o aplicativo de exemplo usa o Provedor de Configuração JSON para carregar a configuração:The starship section of the starship.json file creates the configuration when the sample app uses the JSON Configuration Provider to load the configuration:

{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
  "starship": {
    "name": "USS Enterprise",
    "registry": "NCC-1701",
    "class": "Constitution",
    "length": 304.8,
    "commissioned": false
  },
  "trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

Os seguintes pares chave-valor de configuração são criados:The following configuration key-value pairs are created:

ChaveKey ValorValue
starship:namestarship:name USS EnterpriseUSS Enterprise
starship:registrystarship:registry NCC-1701NCC-1701
starship:classstarship:class ConstituiçãoConstitution
starship:lengthstarship:length 304,8304.8
starship:commissionedstarship:commissioned FalseFalse
marcatrademark Paramount Pictures Corp. https://www.paramount.comParamount Pictures Corp. https://www.paramount.com

O aplicativo de exemplo chama GetSection com a chave starship.The sample app calls GetSection with the starship key. Os pares chave-valor starship são isolados.The starship key-value pairs are isolated. O método Bind é chamado na subseção passando uma instância da classe Starship.The Bind method is called on the subsection passing in an instance of the Starship class. Depois de associar os valores de instância, a instância é atribuída a uma propriedade para renderização:After binding the instance values, the instance is assigned to a property for rendering:

var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;
var starship = new Starship();
_config.GetSection("starship").Bind(starship);
Starship = starship;

Associar a um gráfico de objetoBind to an object graph

Bind é capaz de associar um grafo de objeto POCO inteiro.Bind is capable of binding an entire POCO object graph.

O exemplo contém um modelo TvShow cujo grafo do objeto inclui as classes Metadata e Actors (Models/TvShow.cs):The sample contains a TvShow model whose object graph includes Metadata and Actors classes (Models/TvShow.cs):

public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}
public class TvShow
{
    public Metadata Metadata { get; set; }
    public Actors Actors { get; set; }
    public string Legal { get; set; }
}

public class Metadata
{
    public string Series { get; set; }
    public string Title { get; set; }
    public DateTime AirDate { get; set; }
    public int Episodes { get; set; }
}

public class Actors
{
    public string Names { get; set; }
}

O aplicativo de exemplo tem um arquivo tvshow.xml que contém os dados de configuração:The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <tvshow>
    <metadata>
      <series>Dr. Who</series>
      <title>The Sun Makers</title>
      <airdate>11/26/1977</airdate>
      <episodes>4</episodes>
    </metadata>
    <actors>
      <names>Tom Baker, Louise Jameson, John Leeson</names>
    </actors>
    <legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
  </tvshow>
</configuration>

A configuração está associada ao método do grafo de objeto TvShow inteiro com o método Bind.Configuration is bound to the entire TvShow object graph with the Bind method. A instância associada é atribuída a uma propriedade para renderização:The bound instance is assigned to a property for rendering:

var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

ConfigurationBinder.Get<T> associa e retorna o tipo especificado.ConfigurationBinder.Get<T> binds and returns the specified type. O Get<T> é mais conveniente do que usar Bind.Get<T> is more convenient than using Bind. O código a seguir mostra como usar Get<T> com o exemplo anterior, que permite que a instância associada seja diretamente atribuída à propriedade usada para renderização:The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be directly assigned to the property used for rendering:

TvShow = _config.GetSection("tvshow").Get<TvShow>();
TvShow = _config.GetSection("tvshow").Get<TvShow>();

Associar uma matriz a uma classeBind an array to a class

O aplicativo de exemplo demonstra os conceitos explicados nesta seção.The sample app demonstrates the concepts explained in this section.

O Bind dá suporte a matrizes de associação para objetos usando os índices em chaves de configuração.The Bind supports binding arrays to objects using array indices in configuration keys. Qualquer formato de matriz que exponha um segmento de chave numérica (:0:, :1:, … :{n}:) é capaz de associar matrizes a uma matriz de classe POCO.Any array format that exposes a numeric key segment (:0:, :1:, … :{n}:) is capable of array binding to a POCO class array.

Observação

A associação é fornecida por convenção.Binding is provided by convention. Provedores de configuração personalizados não são necessários para implementar a associação de matriz.Custom configuration providers aren't required to implement array binding.

Processamento de matriz na memóriaIn-memory array processing

Considere as chaves de configuração e os valores mostrados na tabela a seguir.Consider the configuration keys and values shown in the following table.

ChaveKey ValorValue
array:entries:0array:entries:0 value0value0
array:entries:1array:entries:1 value1value1
array:entries:2array:entries:2 value2value2
array:entries:4array:entries:4 value4value4
array:entries:5array:entries:5 value5value5

Essas chaves e valores são carregados no aplicativo de exemplo usando o Provedor de Configuração de Memória:These keys and values are loaded in the sample app using the Memory Configuration Provider:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}
public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

A matriz ignora um valor para o índice #3.The array skips a value for index #3. O associador de configuração não é capaz de associar valores nulos ou criar entradas nulas em objetos associados, o que fica claro em um momento quando o resultado da associação dessa matriz a um objeto é demonstrado.The configuration binder isn't capable of binding null values or creating null entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is demonstrated.

No aplicativo de exemplo, uma classe POCO está disponível para armazenar os dados de configuração associados:In the sample app, a POCO class is available to hold the bound configuration data:

public class ArrayExample
{
    public string[] Entries { get; set; }
}
public class ArrayExample
{
    public string[] Entries { get; set; }
}

Os dados de configuração estão associados ao objeto:The configuration data is bound to the object:

var arrayExample = new ArrayExample();
_config.GetSection("array").Bind(arrayExample);

A sintaxe ConfigurationBinder.Get<T> também pode ser usada, o que resulta em um código mais compacto:ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:

ArrayExample = _config.GetSection("array").Get<ArrayExample>();
ArrayExample = _config.GetSection("array").Get<ArrayExample>();

O objeto associado, uma instância de ArrayExample, recebe os dados da matriz de configuração.The bound object, an instance of ArrayExample, receives the array data from configuration.

Índice ArrayExample.EntriesArrayExample.Entries Index Valor ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value4value4
44 value5value5

O índice #3 no objeto associado contém os dados de configuração para a chave de configuração array:4 e seu valor de value4.Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of value4. Quando os dados de configuração que contêm uma matriz são associados, os índices da matriz nas chaves de configuração são simplesmente usados para iterar os dados de configuração ao criar o objeto.When configuration data containing an array is bound, the array indices in the configuration keys are merely used to iterate the configuration data when creating the object. Um valor nulo não pode ser mantido nos dados de configuração, e uma entrada de valor nulo não será criada em um objeto de associação quando uma matriz nas chaves de configuração ignorar um ou mais índices.A null value can't be retained in configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip one or more indices.

O item de configuração ausente para o índice #3 pode ser fornecido antes da associação à instância ArrayExample por qualquer provedor de configuração que produza o par chave-valor correto na configuração.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that produces the correct key-value pair in configuration. Se o exemplo incluir um Provedor de Configuração JSON adicional com o par chave-valor ausente, o ArrayExample.Entries coincidirá com a matriz de configuração completa:If the sample included an additional JSON Configuration Provider with the missing key-value pair, the ArrayExample.Entries matches the complete configuration array:

missing_value.json:missing_value.json:

{
  "array:entries:3": "value3"
}

No ConfigureAppConfiguration:In ConfigureAppConfiguration:

config.AddJsonFile(
    "missing_value.json", optional: false, reloadOnChange: false);

O par chave-valor mostrado na tabela é carregado na configuração.The key-value pair shown in the table is loaded into configuration.

ChaveKey ValorValue
array:entries:3array:entries:3 value3value3

Se a instância da classe ArrayExample for associada após o Provedor de Configuração JSON incluir a entrada para o índice #3, a matriz ArrayExample.Entries incluirá o valor.If the ArrayExample class instance is bound after the JSON Configuration Provider includes the entry for index #3, the ArrayExample.Entries array includes the value.

Índice ArrayExample.EntriesArrayExample.Entries Index Valor ArrayExample.EntriesArrayExample.Entries Value
00 value0value0
11 value1value1
22 value2value2
33 value3value3
44 value4value4
55 value5value5

Processamento de matriz JSONJSON array processing

Se um arquivo JSON contiver uma matriz, as chaves de configuração serão criadas para os elementos da matriz com um índice de seção de base zero.If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section index. No arquivo de configuração a seguir, subsection é uma matriz:In the following configuration file, subsection is an array:

{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}
{
  "json_array": {
    "key": "valueA",
    "subsection": [
      "valueB",
      "valueC",
      "valueD"
    ]
  }
}

O Provedor de Configuração JSON lê os dados de configuração para os seguintes pares chave-valor:The JSON Configuration Provider reads the configuration data into the following key-value pairs:

ChaveKey ValorValue
json_array:keyjson_array:key valueAvalueA
json_array:subsection:0json_array:subsection:0 valueBvalueB
json_array:subsection:1json_array:subsection:1 valueCvalueC
json_array:subsection:2json_array:subsection:2 valueDvalueD

No aplicativo de exemplo, a seguinte classe POCO está disponível para associar os pares chave-valor de configuração:In the sample app, the following POCO class is available to bind the configuration key-value pairs:

public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}
public class JsonArrayExample
{
    public string Key { get; set; }
    public string[] Subsection { get; set; }
}

Após a associação, JsonArrayExample.Key contém o valor valueA.After binding, JsonArrayExample.Key holds the value valueA. Os valores de subseção são armazenados na propriedade matriz POCO, Subsection.The subsection values are stored in the POCO array property, Subsection.

Índice JsonArrayExample.SubsectionJsonArrayExample.Subsection Index Valor JsonArrayExample.SubsectionJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Provedor de Configuração personalizadoCustom configuration provider

O aplicativo de exemplo demonstra como criar um provedor de configuração básico que lê os pares chave-valor da configuração de um banco de dados usando Entity Framework (EF).The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs from a database using Entity Framework (EF).

O provedor tem as seguintes características:The provider has the following characteristics:

  • O banco de dados EF na memória é usado para fins de demonstração.The EF in-memory database is used for demonstration purposes. Para usar um banco de dados que exija uma cadeia de conexão, implemente um ConfigurationBuilder secundário para fornecer a cadeia de conexão de outro provedor de configuração.To use a database that requires a connection string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration provider.
  • O provedor lê uma tabela de banco de dados na configuração na inicialização.The provider reads a database table into configuration at startup. O provedor não consulta o banco de dados em uma base por chave.The provider doesn't query the database on a per-key basis.
  • O recarregamento na alteração não está implementado, portanto, a atualização do banco de dados após a inicialização do aplicativo não tem efeito sobre a configuração do aplicativo.Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration.

Defina uma entidade EFConfigurationValue para armazenar valores de configuração no banco de dados.Define an EFConfigurationValue entity for storing configuration values in the database.

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Adicione um EFConfigurationContext para armazenar e acessar os valores configurados.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Crie uma classe que implementa IConfigurationSource.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
    {
        _optionsAction = optionsAction;
    }

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Crie o provedor de configuração personalizado através da herança de ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. O provedor de configuração inicializa o banco de dados quando ele está vazio.The configuration provider initializes the database when it's empty. Como as chaves de configuraçãonão diferenciam maiúsculas de minúsculas, o dicionário usado para inicializar o banco de dados é criado com o comparador que não diferencia maiúsculas de minúsculas (StringComparer. OrdinalIgnoreCase).Since configuration keys are case-insensitive, the dictionary used to initialize the database is created with the case-insensitive comparer (StringComparer.OrdinalIgnoreCase).

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        var configValues = 
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue 
                {
                    Id = kvp.Key,
                    Value = kvp.Value
                })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Um método de extensão AddEFConfiguration permite adicionar a fonte de configuração a um ConfigurationBuilder.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

O código a seguir mostra como usar o EFConfigurationProvider personalizado em Program.cs:The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Models/EFConfigurationValue.cs:Models/EFConfigurationValue.cs:

public class EFConfigurationValue
{
    public string Id { get; set; }
    public string Value { get; set; }
}

Adicione um EFConfigurationContext para armazenar e acessar os valores configurados.Add an EFConfigurationContext to store and access the configured values.

EFConfigurationProvider/EFConfigurationContext.cs:EFConfigurationProvider/EFConfigurationContext.cs:

public class EFConfigurationContext : DbContext
{
    public EFConfigurationContext(DbContextOptions options) : base(options)
    {
    }

    public DbSet<EFConfigurationValue> Values { get; set; }
}

Crie uma classe que implementa IConfigurationSource.Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:EFConfigurationProvider/EFConfigurationSource.cs:

public class EFConfigurationSource : IConfigurationSource
{
    private readonly Action<DbContextOptionsBuilder> _optionsAction;

    public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)
    {
        _optionsAction = optionsAction;
    }

    public IConfigurationProvider Build(IConfigurationBuilder builder)
    {
        return new EFConfigurationProvider(_optionsAction);
    }
}

Crie o provedor de configuração personalizado através da herança de ConfigurationProvider.Create the custom configuration provider by inheriting from ConfigurationProvider. O provedor de configuração inicializa o banco de dados quando ele está vazio.The configuration provider initializes the database when it's empty.

EFConfigurationProvider/EFConfigurationProvider.cs:EFConfigurationProvider/EFConfigurationProvider.cs:

public class EFConfigurationProvider : ConfigurationProvider
{
    public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
    {
        OptionsAction = optionsAction;
    }

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    // Load config data from EF DB.
    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

        using (var dbContext = new EFConfigurationContext(builder.Options))
        {
            dbContext.Database.EnsureCreated();

            Data = !dbContext.Values.Any()
                ? CreateAndSaveDefaultValues(dbContext)
                : dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
        }
    }

    private static IDictionary<string, string> CreateAndSaveDefaultValues(
        EFConfigurationContext dbContext)
    {
        // Quotes (c)2005 Universal Pictures: Serenity
        // https://www.uphe.com/movies/serenity
        var configValues = 
            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                { "quote1", "I aim to misbehave." },
                { "quote2", "I swallowed a bug." },
                { "quote3", "You can't stop the signal, Mal." }
            };

        dbContext.Values.AddRange(configValues
            .Select(kvp => new EFConfigurationValue 
                {
                    Id = kvp.Key,
                    Value = kvp.Value
                })
            .ToArray());

        dbContext.SaveChanges();

        return configValues;
    }
}

Um método de extensão AddEFConfiguration permite adicionar a fonte de configuração a um ConfigurationBuilder.An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder.

Extensions/EntityFrameworkExtensions.cs:Extensions/EntityFrameworkExtensions.cs:

public static class EntityFrameworkExtensions
{
    public static IConfigurationBuilder AddEFConfiguration(
        this IConfigurationBuilder builder, 
        Action<DbContextOptionsBuilder> optionsAction)
    {
        return builder.Add(new EFConfigurationSource(optionsAction));
    }
}

O código a seguir mostra como usar o EFConfigurationProvider personalizado em Program.cs:The following code shows how to use the custom EFConfigurationProvider in Program.cs:

public class Program
{
    public static Dictionary<string, string> arrayDict = 
        new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Acessar a configuração durante a inicializaçãoAccess configuration during startup

Injete IConfiguration no construtor Startup para acessar os valores de configuração em Startup.ConfigureServices.Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices. Para acessar a configuração em Startup.Configure, injete IConfiguration diretamente no método ou use a instância do construtor:To access configuration in Startup.Configure, either inject IConfiguration directly into the method or use the instance from the constructor:

public class Startup
{
    private readonly IConfiguration _config;

    public Startup(IConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var value = _config["key"];
    }

    public void Configure(IApplicationBuilder app, IConfiguration config)
    {
        var value = config["key"];
    }
}

Para obter um exemplo de como acessar a configuração usando os métodos de conveniência de inicialização, consulte Inicialização do aplicativo: métodos de conveniência.For an example of accessing configuration using startup convenience methods, see App startup: Convenience methods.

Acessar a configuração em uma página do Razor Pages ou exibição do MVCAccess configuration in a Razor Pages page or MVC view

Para acessar definições de configuração em uma página do Razor Pages ou uma exibição do MVC, adicione usando diretiva (referência de C#: usando diretiva) para o namespace Microsoft.Extensions.Configuration e injete IConfiguration na página ou na exibição.To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.

Em uma página do Razor:In a Razor Pages page:

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index Page</title>
</head>
<body>
    <h1>Access configuration in a Razor Pages page</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

Em uma exibição do MVC:In an MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Index View</title>
</head>
<body>
    <h1>Access configuration in an MVC view</h1>
    <p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>

Adicionar configuração de um assembly externoAdd configuration from an external assembly

Uma implementação IHostingStartup permite adicionar melhorias a um aplicativo durante a inicialização de um assembly externo fora da classe Startup do aplicativo.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.For more information, see Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Recursos adicionaisAdditional resources