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
  • 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
  • Azure Key VaultAzure Key Vault
  • Argumentos de linha de comandoCommand-line arguments
  • Provedores personalizados (instalados ou criados)Custom providers (installed or created)
  • Variáveis de ambienteEnvironment variables
  • Objetos do .NET na memóriaIn-memory .NET objects
  • Arquivos de configuraçõesSettings files
  • Argumentos de linha de comandoCommand-line arguments
  • Provedores personalizados (instalados ou criados)Custom providers (installed or created)
  • Variáveis de ambienteEnvironment variables
  • Objetos do .NET na memóriaIn-memory .NET objects
  • Arquivos de configuraçõesSettings files

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 uses classes to represent groups of related settings. Para saber mais sobre como usar o padrão de opções, confira Padrão de opções no ASP.NET Core.For more information on using the options pattern, 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)

Os exemplos apresentados neste tópico dependem do seguinte:The examples provided in this topic rely upon:

Esses três pacotes estão incluídos no metapacote Microsoft.AspNetCore.App.These three packages are included in the Microsoft.AspNetCore.App metapackage.

Esses três pacotes estão incluídos no metapacote Microsoft.AspNetCore.All.These three packages are included in the Microsoft.AspNetCore.All metapackage.

Configuração do host versus aplicativoHost vs. 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 se tornam parte da configuração global do aplicativo.Host configuration key-value pairs become part of the app's global 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 Host da Web e Host Genérico no 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 Host da Web e Host Genérico no ASP.NET Core.

SegurançaSecurity

Adote as melhores práticas a seguir:Adopt the following best practices:

  • 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.

Saiba mais sobre como usar vários ambientes e gerenciar o armazenamento seguro de segredos de aplicativo em desenvolvimento com o Gerenciador de Segredo (inclui recomendações sobre como usar variáveis de ambiente para armazenar dados confidenciais).Learn more about how to use multiple environments and managing the safe storage of app secrets in development with the Secret Manager (includes advice on using environment variables to store sensitive data). O Gerenciador de Segredo usa o Provedor de Configuração de Arquivo para armazenar segredos do usuário em um arquivo JSON no sistema local.The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. O Provedor de Configuração de Arquivo será descrito mais adiante neste tópico.The File Configuration Provider is described later in this topic.

O Azure Key Vault é uma opção para o armazenamento seguro de segredos do aplicativo.Azure Key Vault is one option for the safe storage of app secrets. Para obter mais informações, consulte Provedor de configuração de Cofre de chaves do Azure no ASP.NET Core.For more information, see Provedor de configuração de Cofre de chaves do Azure 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

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 de Arquivo têm a capacidade de recarregar a configuração quando um arquivo de configurações subjacente é alterado após a inicialização do aplicativo.File Configuration Providers have the ability to reload configuration when an underlying settings file is changed after app startup. O Provedor de Configuração de Arquivo será descrito mais adiante neste tópico.The File Configuration Provider is described later in this topic.

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. 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.

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 em dois-pontos.A double underscore (__) is supported by all platforms and is converted to 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.

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 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
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 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 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
ProviderProvider Fornece a configuração de …Provides configuration from…
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 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) (in the Development environment only)
  4. Variáveis de ambienteEnvironment variables
  5. Argumentos de linha de comandoCommand-line arguments

É 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.It's a common practice 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.

Essa sequência de provedores é aplicada quando você inicializa um novo WebHostBuilder com CreateDefaultBuilder.This sequence of providers is put into place when you initialize a new WebHostBuilder with CreateDefaultBuilder. Para saber mais, veja o tópico Host da Web: configurar um host.For more information, see Web Host: Set up a host.

Essa sequência de provedores pode ser criada para o aplicativo (não o host) com um ConfigurationBuilder e uma chamada para seu método Build em Startup:This sequence of providers can be created for the app (not the host) with a ConfigurationBuilder and a call to its Build method in Startup:

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
            reloadOnChange: true);

    var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));

    if (appAssembly != null)
    {
        builder.AddUserSecrets(appAssembly, optional: true);
    }

    builder.AddEnvironmentVariables();

    Configuration = builder.Build();
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IConfiguration>(Configuration);
}

No exemplo anterior, o nome do ambiente (env.EnvironmentName) e o nome do assembly de aplicativo (env.ApplicationName) são fornecidos pelo IHostingEnvironment.In the preceding example, the environment name (env.EnvironmentName) and app assembly name (env.ApplicationName) are provided by the IHostingEnvironment. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

ConfigureAppConfigurationConfigureAppConfiguration

Chame ConfigureAppConfiguration ao criar o Host da Web para especificar os provedores de configuração do aplicativo, além daqueles adicionados automaticamente por CreateDefaultBuilder:Call ConfigureAppConfiguration when building the Web 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)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}

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 tempo de execução.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 você inicializa um novo WebHostBuilder com CreateDefaultBuilder.AddCommandLine is automatically called when you initialize a new WebHostBuilder with CreateDefaultBuilder. Para saber mais, veja o tópico Host da Web: configurar um host.For more information, see Web Host: Set up a host.

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 tempo de execução 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.

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.

AddCommandLine já foi chamado por CreateDefaultBuilder.AddCommandLine has already been called by CreateDefaultBuilder. Se precisar oferecer configuração de aplicativo e ainda poder substituir essa configuração por argumentos de linha de comando, chame os provedores adicionais do aplicativo em ConfigureAppConfiguration e chame AddCommandLine por fim.If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers in ConfigureAppConfiguration and call AddCommandLine last.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                // Call other providers here and call AddCommandLine last.
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration.Apply the configuration to WebHostBuilder with the UseConfiguration method.

AddCommandLine já foi chamado por CreateDefaultBuilder quando UseConfiguration é chamado.AddCommandLine has already been called by CreateDefaultBuilder when UseConfiguration is called. Se precisar oferecer configuração de aplicativo e ainda poder substituir essa configuração por argumentos de linha de comando, chame os provedores adicionais do aplicativo em um ConfigurationBuilder e chame AddCommandLine por fim.If you need to provide app configuration and still be able to override that configuration with command-line arguments, call the app's additional providers on a ConfigurationBuilder and call AddCommandLine last.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            // Call other providers here and call AddCommandLine last.
            .AddCommandLine(args)
            .Build();

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

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

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

Chamar o provedor por último permite que os argumentos de linha de comando passados em tempo de execução substituam a configuração definida por outros provedores de configuração.Call the provider last to allow the command-line arguments passed at runtime to override configuration set by other configuration providers.

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

var config = new ConfigurationBuilder()
    // Call additional providers here as needed.
    // Call AddCommandLine last to allow arguments to override other configuration.
    .AddCommandLine(args)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

ExemploExample

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

O aplicativo de exemplo 1.x chama AddCommandLine em um ConfigurationBuilder.The 1.x sample app calls AddCommandLine on a ConfigurationBuilder.

  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 pode ser nulo se um sinal de igual for usado (por exemplo, CommandLineKey=).The value can be null 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.

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:

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

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

    // Do not pass the args to CreateDefaultBuilder
    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, _switchMappings);
            })
            .UseStartup<Startup>();
}

Conforme mostrado no exemplo anterior, a chamada para CreateDefaultBuilder não deve passar argumentos ao usar mapeamentos de opção.As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. 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.CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Se os argumentos incluírem uma opção mapeada e forem passados para CreateDefaultBuilder, o provedor AddCommandLine não inicializará com um FormatException.If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. 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.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>
            {
                { "-CLKey1", "CommandLineKey1" },
                { "-CLKey2", "CommandLineKey2" }
            };

        var config = new ConfigurationBuilder()
            .AddCommandLine(args, switchMappings)
            .Build();

        // Do not pass the args to CreateDefaultBuilder
        return WebHost.CreateDefaultBuilder()
            .UseConfiguration(config)
            .UseStartup<Startup>();
    }
}

Conforme mostrado no exemplo anterior, a chamada para CreateDefaultBuilder não deve passar argumentos ao usar mapeamentos de opção.As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch mappings are used. 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.CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder. Se os argumentos incluírem uma opção mapeada e forem passados para CreateDefaultBuilder, o provedor AddCommandLine não inicializará com um FormatException.If the arguments include a mapped switch and are passed to CreateDefaultBuilder, its AddCommandLine provider fails to initialize with a FormatException. 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.

public static void Main(string[] args)
{
    var switchMappings = new Dictionary<string, string>
        {
            { "-CLKey1", "CommandLineKey1" },
            { "-CLKey2", "CommandLineKey2" }
        };

    var config = new ConfigurationBuilder()
        .AddCommandLine(args, switchMappings)
        .Build();

    var host = new WebHostBuilder()
        .UseConfiguration(config)
        .UseKestrel()
        .UseStartup<Startup>()
        .Start();

    using (host)
    {
        Console.ReadLine();
    }
}

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 tempo de execução.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 nas variáveis de ambiente, talvez um separador de dois-pontos (:) não funcione em todas as plataformas.When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms. Um sublinhado duplo (__) é compatível com todas as plataformas e é substituído por dois-pontos.A double underscore (__) is supported by all platforms and is 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 é chamado automaticamente para as variáveis de ambiente prefixadas com ASPNETCORE_ quando você inicializa um novo WebHostBuilder.AddEnvironmentVariables is automatically called for environment variables prefixed with ASPNETCORE_ when you initialize a new WebHostBuilder. Para saber mais, veja o tópico Host da Web: configurar um host.For more information, see Web Host: Set up a host.

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 appsettings.json e appsettings.{Environment}.json.Optional configuration from appsettings.json and appsettings.{Environment}.json.
  • 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 tempo de execução 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.

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.

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.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .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_");
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Chame o método de extensão AddEnvironmentVariables em uma instância de ConfigurationBuilder.Call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder. Aplique a configuração ao WebHostBuilder com o método UseConfiguration.Apply the configuration to WebHostBuilder with the UseConfiguration method.

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.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            // Call additional providers here as needed.
            // Call AddEnvironmentVariables last if you need to allow environment
            // variables to override values from other providers.
            .AddEnvironmentVariables(prefix: "PREFIX_")
            .Build();

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

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

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

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

ExemploExample

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

O aplicativo de exemplo 1.x chama AddEnvironmentVariables em um ConfigurationBuilder.The 1.x sample app calls AddEnvironmentVariables on a ConfigurationBuilder.

  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 para mostrar as que começam com o seguinte:To keep the list of environment variables rendered by the app short, the app filters environment variables to those that start with the following:

  • ASPNETCORE_ASPNETCORE_
  • urlsurls
  • Registrando em logLogging
  • AMBIENTEENVIRONMENT
  • contentRootcontentRoot
  • AllowedHostsAllowedHosts
  • applicationNameapplicationName
  • CommandLineCommandLine

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:

Se você quiser expor todas as variáveis de ambiente disponíveis para o aplicativo, altere o FilteredConfiguration em Controllers/HomeController.cs para o seguinte:If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in Controllers/HomeController.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.

O método de conveniência estático CreateDefaultBuilder cria um WebHostBuilder para estabelecer o host do aplicativo.The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host. Quando WebHostBuilder é criado, ele encontra a configuração de seu host nas variáveis de ambiente prefixadas com ASPNETCORE_.When WebHostBuilder is created, it finds its host configuration in environment variables prefixed with ASPNETCORE_.

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 tempo de execução.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:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddIniFile("config.ini", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Ao chamar CreateDefaultBuilder, chame UseConfiguration com a configuração:When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddIniFile("config.ini", optional: true, reloadOnChange: true)
            .Build();

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

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddIniFile("config.ini", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

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 tempo de execução.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 WebHostBuilder com CreateDefaultBuilder.AddJsonFile is automatically called twice when you initialize a new WebHostBuilder 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 saber mais, veja o tópico Host da Web: configurar um host.For more information, see Web Host: Set up a host.

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:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddJsonFile("config.json", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Você pode chamar diretamente o método de extensão AddJsonFile em uma instância do ConfigurationBuilder.You can also directly call the AddJsonFile extension method on an instance of ConfigurationBuilder.

Ao chamar CreateDefaultBuilder, chame UseConfiguration com a configuração:When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("config.json", optional: true, reloadOnChange: true)
            .Build();

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

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("config.json", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

ExemploExample

O aplicativo de exemplo 2.x aproveita a vantagem do método de conveniência estático CreateDefaultBuilder para criar o host, que inclui duas chamadas para AddJsonFile.The 2.x 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.

O aplicativo de exemplo 1.x chama AddJsonFile duas vezes em um ConfigurationBuilder.The 1.x sample app calls AddJsonFile twice on a ConfigurationBuilder. 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 tempo de execução.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:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                config.AddXmlFile("config.xml", optional: true, reloadOnChange: true);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Ao chamar CreateDefaultBuilder, chame UseConfiguration com a configuração:When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddXmlFile("config.xml", optional: true, reloadOnChange: true)
            .Build();

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

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddXmlFile("config.xml", optional: true, reloadOnChange: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

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.

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:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
                config.AddKeyPerFile(directoryPath: path, optional: true);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
var config = new ConfigurationBuilder()
    .AddKeyPerFile(directoryPath: path, optional: true)
    .Build();

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

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:

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

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(_dict);
            })
            .UseStartup<Startup>();
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Ao chamar CreateDefaultBuilder, chame UseConfiguration com a configuração:When calling CreateDefaultBuilder, call UseConfiguration with the configuration:

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

    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>();
    }
}

Ao criar um WebHostBuilder diretamente, chame UseConfiguration com a configuração:When creating a WebHostBuilder directly, call UseConfiguration with the configuration:

Aplique a configuração ao WebHostBuilder com o método UseConfiguration:Apply the configuration to WebHostBuilder with the UseConfiguration method:

var dict = new Dictionary<string, string>
    {
        {"MemoryCollectionKey1", "value1"},
        {"MemoryCollectionKey2", "value2"}
    };

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

var host = new WebHostBuilder()
    .UseConfiguration(config)
    .UseKestrel()
    .UseStartup<Startup>();

GetValueGetValue

ConfigurationBinder.GetValue<T> extrai um valor de configuração com uma chave especificada e o converte para o tipo especificado.ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the specified type. Uma sobrecarga permite que você forneça um valor padrão se a chave não for encontrada.An overload permits you to provide a default value if the key isn't found.

O exemplo a seguir extrai o valor de cadeia de caracteres da configuração com a chave NumberKey, digita o valor como um int e armazena o valor na variável intValue.The following example extracts the string value from configuration with the key NumberKey, types the value as an int, and stores the value in the variable intValue. Se NumberKey não for encontrado em chaves de configuração, intValue recebe o valor padrão de 99:If NumberKey isn't found in the configuration keys, intValue receives the default value of 99:

var intValue = 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");

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.

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. http://www.paramount.comParamount Pictures Corp. http://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);
viewModel.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;
var tvShow = new TvShow();
_config.GetSection("tvshow").Bind(tvShow);
viewModel.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>();
viewModel.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)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}
public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        var 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"}
        };

        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddInMemoryCollection(arrayDict)
            .AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
                reloadOnChange: true)
            .AddEnvironmentVariables()
            .AddJsonFile("starship.json", optional: false, reloadOnChange: false)
            .AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
            .AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
            .AddCommandLine(Program.Args);

        Configuration = builder.Build();
    }

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>();
viewModel.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);

No construtor Startup:In the Startup constructor:

.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; }
}
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; }
}
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);
    }
}
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>
            {
                { "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;
    }
}
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>
            {
                { "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));
    }
}
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.SetBasePath(Directory.GetCurrentDirectory());
                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>();
}
public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        var 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"}
        };

        var builder = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddInMemoryCollection(arrayDict)
            .AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, 
                reloadOnChange: true)
            .AddEnvironmentVariables()
            .AddJsonFile("starship.json", optional: false, reloadOnChange: false)
            .AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
            .AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
            .AddCommandLine(Program.Args);

        Configuration = builder.Build();
    }

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 Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup.For more information, see Aprimorar um aplicativo por meio de um assembly externo no ASP.NET Core com IHostingStartup.

Recursos adicionaisAdditional resources