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

Por Rick Anderson e Kirk LarkinBy Rick Anderson and Kirk Larkin

A configuração no ASP.NET Core é executada usando um ou mais provedores de configuração.Configuration in ASP.NET Core is performed using one or more configuration providers. Os provedores de configuração lêem dados de configuração de pares chave-valor usando uma variedade de fontes de configuração:Configuration providers read configuration data from key-value pairs using a variety of configuration sources:

  • Arquivos de configurações, como appsettings.jsemSettings files, such as appsettings.json
  • Variáveis de ambienteEnvironment variables
  • Cofre de Chave do AzureAzure Key Vault
  • Configuração de Aplicativo do AzureAzure App Configuration
  • Argumentos de linha de comandoCommand-line arguments
  • Provedores personalizados, instalados ou criadosCustom providers, installed or created
  • Arquivos de diretórioDirectory files
  • Objetos do .NET na memóriaIn-memory .NET objects

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

Configuração padrãoDefault configuration

ASP.NET Core aplicativos Web criados com dotnet novo ou o Visual Studio geram o seguinte código:ASP.NET Core web apps created with dotnet new or Visual Studio generate the following code:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder fornece a configuração padrão para o aplicativo na seguinte ordem:CreateDefaultBuilder provides default configuration for the app in the following order:

  1. ChainedConfigurationProvider : Adiciona um existente IConfiguration como uma origem.ChainedConfigurationProvider : Adds an existing IConfiguration as a source. No caso de configuração padrão, o adiciona a configuração do host e a define como a primeira origem para a configuração do aplicativo .In the default configuration case, adds the host configuration and setting it as the first source for the app configuration.
  2. appsettings.js usando o provedor de configuração JSON.appsettings.json using the JSON configuration provider.
  3. appSettings. Environment . JSON usando o provedor de configuração JSON.appsettings.Environment.json using the JSON configuration provider. Por exemplo, appSettings. Produção. JSON e appSettings. Desenvolvimento. JSON.For example, appsettings.Production.json and appsettings.Development.json.
  4. Segredos do aplicativo quando o aplicativo é executado no Development ambiente.App secrets when the app runs in the Development environment.
  5. Variáveis de ambiente usando o provedor de configuração de variáveis de ambiente.Environment variables using the Environment Variables configuration provider.
  6. Argumentos de linha de comando usando o provedor de configuração de linha de comando.Command-line arguments using the Command-line configuration provider.

Os provedores de configuração adicionados posteriormente substituem as configurações de chave anteriores.Configuration providers that are added later override previous key settings. Por exemplo, se MyKey for definido tanto no appsettings.jsquanto no ambiente, o valor do ambiente será usado.For example, if MyKey is set in both appsettings.json and the environment, the environment value is used. Usando os provedores de configuração padrão, o provedor de configuração de linha de comando substitui todos os outros provedores.Using the default configuration providers, the Command-line configuration provider overrides all other providers.

Para obter mais informações sobre o CreateDefaultBuilder , consulte configurações padrão do Construtor.For more information on CreateDefaultBuilder, see Default builder settings.

O código a seguir exibe os provedores de configuração habilitados na ordem em que foram adicionados:The following code displays the enabled configuration providers in the order they were added:

public class Index2Model : PageModel
{
    private IConfigurationRoot ConfigRoot;

    public Index2Model(IConfiguration configRoot)
    {
        ConfigRoot = (IConfigurationRoot)configRoot;
    }

    public ContentResult OnGet()
    {           
        string str = "";
        foreach (var provider in ConfigRoot.Providers.ToList())
        {
            str += provider.ToString() + "\n";
        }

        return Content(str);
    }
}

appsettings.jsonappsettings.json

Considere o seguinte appsettings.jsno arquivo:Consider the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

O código a seguir do download de exemplo exibe várias das configurações anteriores:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

O padrão JsonConfigurationProvider carrega a configuração na seguinte ordem:The default JsonConfigurationProvider loads configuration in the following order:

  1. appsettings.jsonappsettings.json
  2. appSettings. Environment . JSON : por exemplo, appSettings. Produção. JSON e appSettings. Desenvolvimento. arquivos JSON .appsettings.Environment.json : For example, the appsettings.Production.json and appsettings.Development.json files. A versão de ambiente do arquivo é carregada com base no IHostingEnvironment. environmentname.The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName. 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.

appSettings. Environment . os valores JSON substituem as chaves no appsettings.jsem.appsettings.Environment.json values override keys in appsettings.json. Por exemplo, por padrão:For example, by default:

  • Em desenvolvimento, appSettings. Desenvolvimento. a configuração JSON substitui os valores encontrados no appsettings.jsem.In development, appsettings.Development.json configuration overwrites values found in appsettings.json.
  • Em produção, appSettings. Produção. a configuração JSON substitui os valores encontrados no appsettings.jsem.In production, appsettings.Production.json configuration overwrites values found in appsettings.json. Por exemplo, ao implantar o aplicativo no Azure.For example, when deploying the app to Azure.

Associar dados de configuração hierárquica usando o padrão de opçõesBind hierarchical configuration data using the options pattern

A maneira preferida de ler valores de configuração relacionados é usar o padrão de opções.The preferred way to read related configuration values is using the options pattern. Por exemplo, para ler os seguintes valores de configuração:For example, to read the following configuration values:

  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }

Crie a seguinte PositionOptions classe:Create the following PositionOptions class:

public class PositionOptions
{
    public const string Position = "Position";

    public string Title { get; set; }
    public string Name { get; set; }
}

Uma classe de opções:An options class:

  • Deve ser não-abstrato com um construtor público sem parâmetros.Must be non-abstract with a public parameterless constructor.
  • Todas as propriedades de leitura/gravação públicas do tipo estão associadas.All public read-write properties of the type are bound.
  • Os campos não estão associados.Fields are not bound. No código anterior, Position não está associado.In the preceding code, Position is not bound. A Position propriedade é usada para que a cadeia de caracteres "Position" não precise ser embutida em código no aplicativo ao associar a classe a um provedor de configuração.The Position property is used so the string "Position" doesn't need to be hard coded in the app when binding the class to a configuration provider.

O seguinte código:The following code:

  • Chama ConfigurationBinder. bind para associar a PositionOptions classe à Position seção.Calls ConfigurationBinder.Bind to bind the PositionOptions class to the Position section.
  • Exibe os Position dados de configuração.Displays the Position configuration data.
public class Test22Model : PageModel
{
    private readonly IConfiguration Configuration;

    public Test22Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var positionOptions = new PositionOptions();
        Configuration.GetSection(PositionOptions.Position).Bind(positionOptions);

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

No código anterior, por padrão, as alterações no arquivo de configuração JSON depois que o aplicativo é iniciado são lidas.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

ConfigurationBinder.Get<T>associa e retorna o tipo especificado.ConfigurationBinder.Get<T> binds and returns the specified type. ConfigurationBinder.Get<T>pode ser mais conveniente do que usar o ConfigurationBinder.Bind .ConfigurationBinder.Get<T> may be more convenient than using ConfigurationBinder.Bind. O código a seguir mostra como usar ConfigurationBinder.Get<T> com a PositionOptions classe:The following code shows how to use ConfigurationBinder.Get<T> with the PositionOptions class:

public class Test21Model : PageModel
{
    private readonly IConfiguration Configuration;
    public PositionOptions positionOptions { get; private set; }

    public Test21Model(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {            
        positionOptions = Configuration.GetSection(PositionOptions.Position)
                                                     .Get<PositionOptions>();

        return Content($"Title: {positionOptions.Title} \n" +
                       $"Name: {positionOptions.Name}");
    }
}

No código anterior, por padrão, as alterações no arquivo de configuração JSON depois que o aplicativo é iniciado são lidas.In the preceding code, by default, changes to the JSON configuration file after the app has started are read.

Uma abordagem alternativa ao usar o padrão de opções é associar a Position seção e adicioná-la ao contêiner de serviço de injeção de dependência.An alternative approach when using the options pattern is to bind the Position section and add it to the dependency injection service container. No código a seguir, PositionOptions é adicionado ao contêiner de serviço com Configure e associado à configuração:In the following code, PositionOptions is added to the service container with Configure and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<PositionOptions>(Configuration.GetSection(
                                        PositionOptions.Position));
    services.AddRazorPages();
}

Usando o código anterior, o código a seguir lê as opções de posição:Using the preceding code, the following code reads the position options:

public class Test2Model : PageModel
{
    private readonly PositionOptions _options;

    public Test2Model(IOptions<PositionOptions> options)
    {
        _options = options.Value;
    }

    public ContentResult OnGet()
    {
        return Content($"Title: {_options.Title} \n" +
                       $"Name: {_options.Name}");
    }
}

No código anterior, as alterações no arquivo de configuração JSON depois que o aplicativo foi iniciado não são lidas.In the preceding code, changes to the JSON configuration file after the app has started are not read. Para ler as alterações depois que o aplicativo for iniciado, use IOptionsSnapshot.To read changes after the app has started, use IOptionsSnapshot.

Usando a configuração padrão , o appsettings.jsem e appSettings. Environment os arquivos . JSON são habilitados com reloadOnChange: true.Using the default configuration, the appsettings.json and appsettings.Environment.json files are enabled with reloadOnChange: true. As alterações feitas no appsettings.jsem e appSettings. Environment o arquivo . JSON após o início do aplicativo é lido pelo provedor de configuração JSON.Changes made to the appsettings.json and appsettings.Environment.json file after the app starts are read by the JSON configuration provider.

Consulte provedor de configuração JSON neste documento para obter informações sobre como adicionar arquivos de configuração JSON adicionais.See JSON configuration provider in this document for information on adding additional JSON configuration files.

Gerenciador de segurança e segredoSecurity and secret manager

Diretrizes de dados de configuração:Configuration data guidelines:

  • 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. O Gerenciador de segredo pode ser usado para armazenar segredos no desenvolvimento.The Secret manager can be used to store secrets in development.
  • 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.

Por padrão, o Gerenciador de segredo lê as definições de configuração depois deappsettings.js e appSettings. Environment . JSON.By default, Secret manager reads configuration settings after appsettings.json and appsettings.Environment.json.

Para obter mais informações sobre como armazenar senhas ou outros dados confidenciais:For more information on storing passwords or other sensitive data:

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

Variáveis de ambienteEnvironment variables

Usando a configuração padrão , o EnvironmentVariablesConfigurationProvider carrega a configuração de pares chave-valor da variável de ambiente depois de ler appsettings.jsem, appSettings. Environment . JSONe o Gerenciador de segredo.Using the default configuration, the EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs after reading appsettings.json, appsettings.Environment.json, and Secret manager. Portanto, os valores de chave lidos dos valores de substituição de ambiente lidos de appsettings.jsem, appSettings. Environment . JSONe o Gerenciador de segredo.Therefore, key values read from the environment override values read from appsettings.json, appsettings.Environment.json, and Secret manager.

O : separador não funciona com chaves hierárquicas de variáveis de ambiente em todas as plataformas.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, o sublinhado duplo é:__, the double underscore, is:

  • Compatível com todas as plataformas.Supported by all platforms. Por exemplo, o : separador não tem suporte do bash, mas sim __ .For example, the : separator is not supported by Bash, but __ is.
  • Substituído automaticamente por um:Automatically replaced by a :

Os seguintes set comandos:The following set commands:

  • Defina as chaves de ambiente e os valores do exemplo anterior no Windows.Set the environment keys and values of the preceding example on Windows.
  • Teste as configurações ao usar o download de exemplo.Test the settings when using the sample download. O dotnet run comando deve ser executado no diretório do projeto.The dotnet run command must be run in the project directory.
set MyKey="My key from Environment"
set Position__Title=Environment_Editor
set Position__Name=Environment_Rick
dotnet run

As configurações de ambiente anteriores:The preceding environment settings:

  • São definidos apenas em processos iniciados na janela de comando em que foram definidos.Are only set in processes launched from the command window they were set in.
  • Não serão lidos por navegadores iniciados com o Visual Studio.Won't be read by browsers launched with Visual Studio.

Os comandos setx a seguir podem ser usados para definir as chaves de ambiente e os valores no Windows.The following setx commands can be used to set the environment keys and values on Windows. Ao contrário set de, setx as configurações são persistidas.Unlike set, setx settings are persisted. /Mdefine a variável no ambiente do sistema./M sets the variable in the system environment. Se a /M opção não for usada, uma variável de ambiente do usuário será definida.If the /M switch isn't used, a user environment variable is set.

setx MyKey "My key from setx Environment" /M
setx Position__Title Setx_Environment_Editor /M
setx Position__Name Environment_Rick /M

Para testar se os comandos anteriores substituem appsettings.js e appSettings. Environment . JSON:To test that the preceding commands override appsettings.json and appsettings.Environment.json:

  • Com o Visual Studio: saia e reinicie o Visual Studio.With Visual Studio: Exit and restart Visual Studio.
  • Com a CLI: iniciar uma nova janela de comando e Enter dotnet run .With the CLI: Start a new command window and enter dotnet run.

Chame AddEnvironmentVariables com uma cadeia de caracteres para especificar um prefixo para variáveis de ambiente:Call AddEnvironmentVariables with a string to specify a prefix for environment variables:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddEnvironmentVariables(prefix: "MyCustomPrefix_");
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

No código anterior:In the preceding code:

O prefixo é eliminado quando os pares chave-valor de configuração são lidos.The prefix is stripped off when the configuration key-value pairs are read.

Os comandos a seguir testam o prefixo personalizado:The following commands test the custom prefix:

set MyCustomPrefix_MyKey="My key with MyCustomPrefix_ Environment"
set MyCustomPrefix_Position__Title=Editor_with_customPrefix
set MyCustomPrefix_Position__Name=Environment_Rick_cp
dotnet run

A configuração padrão carrega variáveis de ambiente e argumentos de linha de comando prefixados com DOTNET_ and ASPNETCORE_ .The default configuration loads environment variables and command line arguments prefixed with DOTNET_ and ASPNETCORE_. Os DOTNET_ ASPNETCORE_ prefixos e são usados por ASP.NET Core para configuração de host e aplicativo, mas não para a configuração do usuário.The DOTNET_ and ASPNETCORE_ prefixes are used by ASP.NET Core for host and app configuration, but not for user configuration. Para obter mais informações sobre a configuração de host e aplicativo, consulte host genérico .net.For more information on host and app configuration, see .NET Generic Host.

Em Azure app serviço, selecione nova configuração de aplicativo na página configurações > configuração .On Azure App Service, select New application setting on the Settings > Configuration page. Azure App configurações do aplicativo de serviço são:Azure App Service application settings are:

  • Criptografado em repouso e transmitido por um canal criptografado.Encrypted at rest and transmitted over an encrypted channel.
  • Exposto como variáveis de ambiente.Exposed as environment variables.

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.

Consulte prefixos de cadeia de conexão para obter informações sobre cadeias de conexão do banco de dadosSee Connection string prefixes for information on Azure database connection strings.

Variáveis de ambiente definidas no launchSettings.jsemEnvironment variables set in launchSettings.json

As variáveis de ambiente definidas no launchSettings.js substituir aquelas definidas no ambiente do sistema.Environment variables set in launchSettings.json override those set in the system environment.

Linha de comandoCommand-line

Usando a configuração padrão , o CommandLineConfigurationProvider carrega a configuração de pares de chave-valor de argumento de linha de comando após as seguintes fontes de configuração:Using the default configuration, the CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs after the following configuration sources:

Por padrão, os valores de configuração definidos nos valores de configuração de substituição de linha de comando são definidos com todos os outros provedores de configuração.By default, configuration values set on the command-line override configuration values set with all the other configuration providers.

Argumentos de linha de comandoCommand-line arguments

O comando a seguir define chaves e valores usando = :The following command sets keys and values using =:

dotnet run MyKey="My key from command line" Position:Title=Cmd Position:Name=Cmd_Rick

O comando a seguir define chaves e valores usando / :The following command sets keys and values using /:

dotnet run /MyKey "Using /" /Position:Title=Cmd_ /Position:Name=Cmd_Rick

O comando a seguir define chaves e valores usando -- :The following command sets keys and values using --:

dotnet run --MyKey "Using --" --Position:Title=Cmd-- --Position:Name=Cmd--Rick

O valor da chave:The key value:

  • Deve seguir = , ou a chave deve ter um prefixo -- ou / quando o valor segue um espaço.Must follow =, or the key must have a prefix of -- or / when the value follows a space.
  • Não será necessário se = for usado.Isn't required if = is used. Por exemplo, MySetting=.For example, MySetting=.

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

Mapeamentos de comutadorSwitch mappings

Os mapeamentos de switch permitem a lógica de substituição de nome de chave .Switch mappings allow key name replacement logic. Forneça um dicionário de substituições de switch para o AddCommandLine método.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 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 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 - ou -- .Switches must start with - or --.
  • O dicionário de mapeamentos de comutador chave não deve conter chaves duplicadas.The switch mappings dictionary must not contain duplicate keys.

Para usar um dicionário de mapeamentos de opção, passe-o para a chamada para AddCommandLine :To use a switch mappings dictionary, pass it into the call to AddCommandLine:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var switchMappings = new Dictionary<string, string>()
         {
             { "-k1", "key1" },
             { "-k2", "key2" },
             { "--alt3", "key3" },
             { "--alt4", "key4" },
             { "--alt5", "key5" },
             { "--alt6", "key6" },
         };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddCommandLine(args, switchMappings);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

O código a seguir mostra os valores de chave para as chaves substituídas:The following code shows the key values for the replaced keys:

public class Test3Model : PageModel
{
    private readonly IConfiguration Config;

    public Test3Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        return Content(
                $"Key1: '{Config["Key1"]}'\n" +
                $"Key2: '{Config["Key2"]}'\n" +
                $"Key3: '{Config["Key3"]}'\n" +
                $"Key4: '{Config["Key4"]}'\n" +
                $"Key5: '{Config["Key5"]}'\n" +
                $"Key6: '{Config["Key6"]}'");
    }
}

O comando a seguir funciona para testar a substituição da chave:The following command works to test key replacement:

dotnet run -k1 value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Observação: no momento, = não pode ser usado para definir valores de substituição de chave com um único traço - .Note: Currently, = cannot be used to set key-replacement values with a single dash -. Consulte este problema do GitHub.See this GitHub issue.

dotnet run -k1=value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6

Para aplicativos que usam mapeamentos de opção, a chamada CreateDefaultBuilder para não deve passar argumentos.For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. A CreateDefaultBuilder chamada do método AddCommandLine não inclui opções mapeadas e não há como passar o dicionário de mapeamento de opção para CreateDefaultBuilder .The CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no way to pass the switch-mapping dictionary to CreateDefaultBuilder. A solução não é passar os argumentos para CreateDefaultBuilder , mas sim permitir que o ConfigurationBuilder método do método AddCommandLine processe os 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.

Dados de configuração hierárquicaHierarchical configuration data

A API de configuração lê dados de configuração hierárquicas mesclando os dados hierárquicos com o uso de um delimitador nas chaves de configuração.The Configuration API reads hierarchical configuration data by flattening the hierarchical data with the use of a delimiter in the configuration keys.

O download de exemplo contém os seguintes appsettings.jsno arquivo:The sample download contains the following appsettings.json file:

{
    "Position": {
        "Title": "Editor",
        "Name": "Joe Smith"
    },
    "MyKey": "My appsettings.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

O código a seguir do download de exemplo exibe várias das configurações:The following code from the sample download displays several of the configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

A maneira preferida de ler dados de configuração hierárquicos é usar o padrão de opções.The preferred way to read hierarchical configuration data is using the options pattern. Para obter mais informações, consulte associar dados de configuração hierárquica neste documento.For more information, see Bind hierarchical configuration data in this document.

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.

Chaves de configuração e valoresConfiguration keys and values

Chaves de configuração:Configuration keys:

  • Não diferenciam maiúsculas de minúsculas.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 uma chave e um valor for definido em mais de um provedor de configuração, o valor do último provedor adicionado será usado.If a key and value is set in more than one configuration providers, the value from the last provider added is used. Para obter mais informações, consulte configuração padrão.For more information, see Default configuration.
  • 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, __ , tem suporte em todas as plataformas e é automaticamente convertido em dois-pontos : .A double underscore, __, is supported by all platforms and is automatically converted into a colon :.
    • Em Azure Key Vault, as chaves hierárquicas usam -- como um separador.In Azure Key Vault, hierarchical keys use -- as a separator. O provedor de configuração Azure Key Vault substitui automaticamente -- por um : quando os segredos são carregados na configuração do aplicativo.The Azure Key Vault configuration provider automatically replaces -- with a : 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.

Valores de configuração:Configuration values:

  • São cadeias de caracteres.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.

Provedores de configuraçãoConfiguration providers

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.

ProvedorProvider Fornece a configuração de Provides configuration from
Provedor de configuração de Azure Key VaultAzure Key Vault configuration provider Cofre de Chave do AzureAzure Key Vault
Provedor de configuração de Azure AppAzure App configuration provider Configuração de Aplicativo do AzureAzure App Configuration
Provedor de configuração de linha de comandoCommand-line configuration provider Parâmetros da 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 e XMLINI, JSON, and XML files
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
Gerenciador de segredoSecret Manager Arquivo no diretório de perfil do usuárioFile in the user profile directory

As fontes de configuração são lidas na ordem em que seus provedores de configuração são especificados.Configuration sources are read in the order that their configuration providers are specified. Solicite provedores de configuração no código para se adequar às prioridades das fontes de configuração subjacentes que o aplicativo requer.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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

  1. appsettings.jsonappsettings.json
  2. appSettings. Environment . JSONappsettings.Environment.json
  3. Gerenciador de segredoSecret Manager
  4. Variáveis de ambiente usando o provedor de configuração de variáveis de ambiente.Environment variables using the Environment Variables configuration provider.
  5. Argumentos de linha de comando usando o provedor de configuração de linha de comando.Command-line arguments using the Command-line configuration provider.

Uma prática comum é adicionar o provedor de configuração de linha de comando pela última vez em uma série de provedores para permitir que argumentos de linha de comando substituam a configuração definida pelos outros provedores.A common practice is to add the Command-line configuration provider last in a series of providers to allow command-line arguments to override configuration set by the other providers.

A sequência anterior de provedores é usada na configuração padrão.The preceding sequence of providers is used in the default configuration.

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.The Configuration API has special processing rules for four connection string environment variables. Essas cadeias de conexão estão envolvidas na configuração de cadeias de conexão do Azure para o ambiente de aplicativo.These connection strings are 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 com a configuração padrão ou quando nenhum prefixo é fornecido para AddEnvironmentVariables .Environment variables with the prefixes shown in the table are loaded into the app with the default configuration or when no prefix is supplied to AddEnvironmentVariables.

Prefixo da cadeia de conexãoConnection string prefix ProvedorProvider
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 JSONJSON configuration provider

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

Sobrecargas podem especificar:Overloads can specify:

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

Considere o seguinte código:Consider the following code:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyConfig.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

O código anterior:The preceding code:

Normalmente, você não deseja que um arquivo JSON personalizado substitua valores definidos no provedor de configuração de variáveis de ambiente e no provedor de configuração de linha de comando.You typically don't want a custom JSON file overriding values set in the Environment variables configuration provider and the Command-line configuration provider.

O código a seguir limpa todos os provedores de configuração e adiciona vários provedores de configuração:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

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

                config.AddJsonFile("MyConfig.json", optional: true, reloadOnChange: true)
                      .AddJsonFile($"MyConfig.{env.EnvironmentName}.json",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

No código anterior, as configurações na MyConfig.jsem e myconfig. Environment . arquivos JSON :In the preceding code, settings in the MyConfig.json and MyConfig.Environment.json files:

O download de exemplo contém os seguintes MyConfig.jsno arquivo:The sample download contains the following MyConfig.json file:

{
    "Position": {
        "Title": "Meu título de Config",
        "Name": "My Config Smith"
    },
    "MyKey": "MyConfig.json Value",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"
}

O código a seguir do download de exemplo exibe várias das configurações anteriores:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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 seguintes provedores de configuração derivam de FileConfigurationProvider :The following configuration providers derive from FileConfigurationProvider:

Provedor de configuração INIINI configuration provider

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

O código a seguir limpa todos os provedores de configuração e adiciona vários provedores de configuração:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddIniFile("MyIniConfig.ini", optional: true, reloadOnChange: true)
                      .AddIniFile($"MyIniConfig.{env.EnvironmentName}.ini",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

No código anterior, as configurações no MyIniConfig.ini e MyIniConfig. Environment . os arquivos ini são substituídos pelas configurações no:In the preceding code, settings in the MyIniConfig.ini and MyIniConfig.Environment.ini files are overridden by settings in the:

O download de exemplo contém o seguinte arquivo de MyIniConfig.ini :The sample download contains the following MyIniConfig.ini file:

MyKey="MyIniConfig.ini Value"

[Position]
Title="My INI Config title"
Name="My INI Config name"

[Logging:LogLevel]
Default=Information
Microsoft=Warning

O código a seguir do download de exemplo exibe várias das configurações anteriores:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

Provedor de configuração XMLXML configuration provider

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

O código a seguir limpa todos os provedores de configuração e adiciona vários provedores de configuração:The following code clears all the configuration providers and adds several configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.Sources.Clear();

                var env = hostingContext.HostingEnvironment;

                config.AddXmlFile("MyXMLFile.xml", optional: true, reloadOnChange: true)
                      .AddXmlFile($"MyXMLFile.{env.EnvironmentName}.xml",
                                     optional: true, reloadOnChange: true);

                config.AddEnvironmentVariables();

                if (args != null)
                {
                    config.AddCommandLine(args);
                }
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

No código anterior, as configurações no MyXMLFile.xml e MyXMLFile. Environment . os arquivos XML são substituídos pelas configurações no:In the preceding code, settings in the MyXMLFile.xml and MyXMLFile.Environment.xml files are overridden by settings in the:

O download de exemplo contém o seguinte arquivo de MyXMLFile.xml :The sample download contains the following MyXMLFile.xml file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <MyKey>MyXMLFile Value</MyKey>
  <Position>
    <Title>Title from  MyXMLFile</Title>
    <Name>Name from MyXMLFile</Name>
  </Position>
  <Logging>
    <LogLevel>
      <Default>Information</Default>
      <Microsoft>Warning</Microsoft>
    </LogLevel>
  </Logging>
</configuration>

O código a seguir do download de exemplo exibe várias das configurações anteriores:The following code from the sample download displays several of the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

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 00</key>
    <key name="key1">value 01</key>
  </section>
  <section name="section1">
    <key name="key0">value 10</key>
    <key name="key1">value 11</key>
  </section>
</configuration>

O código a seguir lê o arquivo de configuração anterior e exibe as chaves e valores:The following code reads the previous configuration file and displays the keys and values:

public class IndexModel : PageModel
{
    private readonly IConfiguration Configuration;

    public IndexModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var key00 = "section:section0:key:key0";
        var key01 = "section:section0:key:key1";
        var key10 = "section:section1:key:key0";
        var key11 = "section:section1:key:key1";

        var val00 = Configuration[key00];
        var val01 = Configuration[key01];
        var val10 = Configuration[key10];
        var val11 = Configuration[key11];

        return Content($"{key00} value: {val00} \n" +
                       $"{key01} value: {val01} \n" +
                       $"{key10} value: {val10} \n" +
                       $"{key10} value: {val11} \n"
                       );
    }
}

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

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

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

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

Provedor de configuração de chave por arquivoKey-per-file configuration provider

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

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

As sobrecargas permitem especificar:Overloads permit specifying:

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

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

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

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

Provedor de configuração de memóriaMemory configuration provider

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

O código a seguir adiciona uma coleção de memória ao sistema de configuração:The following code adds a memory collection to the configuration system:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var Dict = new Dictionary<string, string>
        {
           {"MyKey", "Dictionary MyKey Value"},
           {"Position:Title", "Dictionary_Title"},
           {"Position:Name", "Dictionary_Name" },
           {"Logging:LogLevel:Default", "Warning"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(Dict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

O código a seguir do download de exemplo exibe as configurações anteriores:The following code from the sample download displays the preceding configurations settings:

public class TestModel : PageModel
{
    // requires using Microsoft.Extensions.Configuration;
    private readonly IConfiguration Configuration;

    public TestModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var myKeyValue = Configuration["MyKey"];
        var title = Configuration["Position:Title"];
        var name = Configuration["Position:Name"];
        var defaultLogLevel = Configuration["Logging:LogLevel:Default"];


        return Content($"MyKey value: {myKeyValue} \n" +
                       $"Title: {title} \n" +
                       $"Name: {name} \n" +
                       $"Default Log Level: {defaultLogLevel}");
    }
}

No código anterior, config.AddInMemoryCollection(Dict) é adicionado após os provedores de configuração padrão.In the preceding code, config.AddInMemoryCollection(Dict) is added after the default configuration providers. Para obter um exemplo de como ordenar os provedores de configuração, consulte provedor de configuração JSON.For an example of ordering the configuration providers, see JSON configuration provider.

Consulte associar uma matriz para outro exemplo usando MemoryConfigurationProvider .See Bind an array for another example using MemoryConfigurationProvider.

GetValueGetValue

ConfigurationBinder.GetValue<T>extrai um único valor da configuração com uma chave especificada e converte-o no tipo especificado:ConfigurationBinder.GetValue<T> extracts a single value from configuration with a specified key and converts it to the specified type:

public class TestNumModel : PageModel
{
    private readonly IConfiguration Configuration;

    public TestNumModel(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public ContentResult OnGet()
    {
        var number = Configuration.GetValue<int>("NumberKey", 99);
        return Content($"{number}");
    }
}

No código anterior, se NumberKey não for encontrado na configuração, o valor padrão de 99 será usado.In the preceding code, if NumberKey isn't found in the configuration, the default value of 99 is used.

GetSection, GetChildren e ExistsGetSection, GetChildren, and Exists

Para os exemplos a seguir, considere o seguinte MySubsection.jsno arquivo:For the examples that follow, consider the following MySubsection.json file:

{
  "section0": {
    "key0": "value00",
    "key1": "value01"
  },
  "section1": {
    "key0": "value10",
    "key1": "value11"
  },
  "section2": {
    "subsection0": {
      "key0": "value200",
      "key1": "value201"
    },
    "subsection1": {
      "key0": "value210",
      "key1": "value211"
    }
  }
}

O código a seguir adiciona MySubsection.js aos provedores de configuração:The following code adds MySubsection.json to the configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MySubsection.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

GetSectionGetSection

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

O código a seguir retorna valores para section1 :The following code returns values for section1:

public class TestSectionModel : PageModel
{
    private readonly IConfiguration Config;

    public TestSectionModel(IConfiguration configuration)
    {
        Config = configuration.GetSection("section1");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section1:key0: '{Config["key0"]}'\n" +
                $"section1:key1: '{Config["key1"]}'");
    }
}

O código a seguir retorna valores para section2:subsection0 :The following code returns values for section2:subsection0:

public class TestSection2Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection2Model(IConfiguration configuration)
    {
        Config = configuration.GetSection("section2:subsection0");
    }

    public ContentResult OnGet()
    {
        return Content(
                $"section2:subsection0:key0 '{Config["key0"]}'\n" +
                $"section2:subsection0:key1:'{Config["key1"]}'");
    }
}

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

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

GetChildren e existeGetChildren and Exists

O código a seguir chama IConfiguration. GetChildren e retorna valores para section2:subsection0 :The following code calls IConfiguration.GetChildren and returns values for section2:subsection0:

public class TestSection4Model : PageModel
{
    private readonly IConfiguration Config;

    public TestSection4Model(IConfiguration configuration)
    {
        Config = configuration;
    }

    public ContentResult OnGet()
    {
        string s = null;
        var selection = Config.GetSection("section2");
        if (!selection.Exists())
        {
            throw new System.Exception("section2 does not exist.");
        }
        var children = selection.GetChildren();

        foreach (var subSection in children)
        {
            int i = 0;
            var key1 = subSection.Key + ":key" + i++.ToString();
            var key2 = subSection.Key + ":key" + i.ToString();
            s += key1 + " value: " + selection[key1] + "\n";
            s += key2 + " value: " + selection[key2] + "\n";
        }
        return Content(s);
    }
}

O código anterior chama ConfigurationExtensions. Exists para verificar se a seção existe:The preceding code calls ConfigurationExtensions.Exists to verify the section exists:

Associar uma matrizBind an array

O ConfigurationBinder. bind dá suporte a matrizes de associação a objetos usando índices de matriz em chaves de configuração.The ConfigurationBinder.Bind supports binding arrays to objects using array indices in configuration keys. Qualquer formato de matriz que expõe um segmento de chave numérica é capaz de associar a matriz a uma matriz de classe poco .Any array format that exposes a numeric key segment is capable of array binding to a POCO class array.

Considere MyArray.js do download de exemplo:Consider MyArray.json from the sample download:

{
  "array": {
    "entries": {
      "0": "value00",
      "1": "value10",
      "2": "value20",
      "4": "value40",
      "5": "value50"
    }
  }
}

O código a seguir adiciona MyArray.js aos provedores de configuração:The following code adds MyArray.json to the configuration providers:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("MyArray.json", 
                    optional: true, 
                    reloadOnChange: true);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

O código a seguir lê a configuração e exibe os valores:The following code reads the configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

O código anterior retorna a seguinte saída:The preceding code returns the following output:

Index: 0  Value: value00
Index: 1  Value: value10
Index: 2  Value: value20
Index: 3  Value: value40
Index: 4  Value: value50

Na saída anterior, o índice 3 tem valor value40 , correspondente a "4": "value40", no MyArray.jsem.In the preceding output, Index 3 has value value40, corresponding to "4": "value40", in MyArray.json. Os índices de matriz associados são contínuos e não associados ao índice de chave de configuração.The bound array indices are continuous and not bound to the configuration key index. O associador de configuração não é capaz de ligar valores nulos ou criar entradas nulas em objetos associadosThe configuration binder isn't capable of binding null values or creating null entries in bound objects

O código a seguir carrega a array:entries configuração com o AddInMemoryCollection método de extensão:The following code loads the array:entries configuration with the AddInMemoryCollection extension method:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

O código a seguir lê a configuração no arrayDict Dictionary e exibe os valores:The following code reads the configuration in the arrayDict Dictionary and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

O código anterior retorna a seguinte saída:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value4
Index: 4  Value: value5

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 de matriz nas chaves de configuração são 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 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 à ArrayExample instância por qualquer provedor de configuração que leia o # par chave/valor do índice 3.The missing configuration item for index #3 can be supplied before binding to the ArrayExample instance by any configuration provider that reads the index #3 key/value pair. Considere o seguinte Value3.jsno arquivo do download de exemplo:Consider the following Value3.json file from the sample download:

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

O código a seguir inclui a configuração para o Value3.jsno e no arrayDict Dictionary :The following code includes configuration for Value3.json and the arrayDict Dictionary:

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

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var arrayDict = new Dictionary<string, string>
        {
            {"array:entries:0", "value0"},
            {"array:entries:1", "value1"},
            {"array:entries:2", "value2"},
            //              3   Skipped
            {"array:entries:4", "value4"},
            {"array:entries:5", "value5"}
        };

        return Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddInMemoryCollection(arrayDict);
                config.AddJsonFile("Value3.json",
                                    optional: false, reloadOnChange: false);
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
    }
}

O código a seguir lê a configuração anterior e exibe os valores:The following code reads the preceding configuration and displays the values:

public class ArrayModel : PageModel
{
    private readonly IConfiguration Config;
    public ArrayExample _array { get; private set; }

    public ArrayModel(IConfiguration config)
    {
        Config = config;
    }

    public ContentResult OnGet()
    {
        _array = Config.GetSection("array").Get<ArrayExample>();
        string s = null;

        for (int j = 0; j < _array.Entries.Length; j++)
        {
            s += $"Index: {j}  Value:  {_array.Entries[j]} \n";
        }

        return Content(s);
    }
}

O código anterior retorna a seguinte saída:The preceding code returns the following output:

Index: 0  Value: value0
Index: 1  Value: value1
Index: 2  Value: value2
Index: 3  Value: value3
Index: 4  Value: value4
Index: 5  Value: value5

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.

Provedor de Configuração personalizadoCustom configuration provider

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

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

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

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

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

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

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

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

// using Microsoft.EntityFrameworkCore;

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:

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

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

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

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

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

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

    public override void Load()
    {
        var builder = new DbContextOptionsBuilder<EFConfigurationContext>();

        OptionsAction(builder);

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

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

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

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

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

// using Microsoft.EntityFrameworkCore;
// using Microsoft.Extensions.Configuration;

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:

// using Microsoft.EntityFrameworkCore;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddEFConfiguration(
                options => options.UseInMemoryDatabase("InMemoryDb"));
        })

Configuração de acesso na inicializaçãoAccess configuration in Startup

O código a seguir exibe dados de configuração em Startup métodos:The following code displays configuration data in Startup methods:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        Console.WriteLine($"MyKey : {Configuration["MyKey"]}");
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        Console.WriteLine($"Position:Title : {Configuration["Position:Title"]}");

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

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.

Configuração de acesso em Razor páginasAccess configuration in Razor Pages

O código a seguir exibe os dados de configuração em uma Razor página:The following code displays configuration data in a Razor Page:

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

Configuration value for 'MyKey': @Configuration["MyKey"]

No código a seguir, MyOptions é adicionado ao contêiner de serviço com Configure e associado à configuração:In the following code, MyOptions is added to the service container with Configure and bound to configuration:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(Configuration.GetSection("MyOptions"));

    services.AddRazorPages();
}

A marcação a seguir usa a @inject Razor diretiva para resolver e exibir os valores de opções:The following markup uses the @inject Razor directive to resolve and display the options values:

@page
@model SampleApp.Pages.Test3Model
@using Microsoft.Extensions.Options
@inject IOptions<MyOptions> optionsAccessor


<p><b>Option1:</b> @optionsAccessor.Value.Option1</p>
<p><b>Option2:</b> @optionsAccessor.Value.Option2</p>

Acessar a configuração em um arquivo de exibição do MVCAccess configuration in a MVC view file

O código a seguir exibe os dados de configuração em uma exibição do MVC:The following code displays configuration data in a MVC view:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

Configuration value for 'MyKey': @Configuration["MyKey"]

Configurar opções com um delegadoConfigure options with a delegate

As opções configuradas em um delegado substituem valores definidos nos provedores de configuração.Options configured in a delegate override values set in the configuration providers.

A configuração de opções com um delegado é demonstrada como o exemplo 2 no aplicativo de exemplo.Configuring options with a delegate is demonstrated as Example 2 in the sample app.

No código a seguir, um IConfigureOptions<TOptions> serviço é adicionado ao contêiner de serviço.In the following code, an IConfigureOptions<TOptions> service is added to the service container. Ele usa um delegado para configurar valores para MyOptions :It uses a delegate to configure values for MyOptions:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyOptions>(myOptions =>
    {
        myOptions.Option1 = "Value configured in delegate";
        myOptions.Option2 = 500;
    });

    services.AddRazorPages();
}

O código a seguir exibe os valores de opções:The following code displays the options values:

public class Test2Model : PageModel
{
    private readonly IOptions<MyOptions> _optionsDelegate;

    public Test2Model(IOptions<MyOptions> optionsDelegate )
    {
        _optionsDelegate = optionsDelegate;
    }

    public ContentResult OnGet()
    {
        return Content($"Option1: {_optionsDelegate.Value.Option1} \n" +
                       $"Option2: {_optionsDelegate.Value.Option2}");
    }
}

No exemplo anterior, os valores de Option1 e Option2 são especificados em appsettings.js e, em seguida, substituídos pelo delegado configurado.In the preceding example, the values of Option1 and Option2 are specified in appsettings.json and then overridden by the configured delegate.

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

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

Configuração de host padrãoDefault host configuration

Para obter detalhes sobre a configuração padrão ao usar o host da Web, confira a versão do ASP.NET Core 2.2 deste tópico.For details on the default configuration when using the Web Host, see the ASP.NET Core 2.2 version of this topic.

  • A configuração do host é fornecida de:Host configuration is provided from:
  • A configuração padrão do host da Web foi estabelecida (ConfigureWebHostDefaults):Web Host default configuration is established (ConfigureWebHostDefaults):
    • O Kestrel é usado como o servidor Web e configurado usando provedores de configuração do aplicativo.Kestrel is used as the web server and configured using the app's configuration providers.
    • Adicione o middleware de filtragem de host.Add Host Filtering Middleware.
    • Adicione o middleware de cabeçalhos encaminhados se a variável de ambiente ASPNETCORE_FORWARDEDHEADERS_ENABLED for definida para true.Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true.
    • Habilite a integração de IIS.Enable IIS integration.

Outra configuraçãoOther configuration

Este tópico pertence apenas à configuração do aplicativo.This topic only pertains to app configuration. Outros aspectos da execução e Hospedagem de aplicativos ASP.NET Core são configurados usando arquivos de configuração não abordados neste tópico:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.jsem / As launchSettings.jsno são arquivos de configuração de ferramentas para o ambiente de desenvolvimento, descritos:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config é um arquivo de configuração de servidor, descrito nos seguintes tópicos:web.config is a server configuration file, described in the following topics:

As variáveis de ambiente definidas no launchSettings.js substituir aquelas definidas no ambiente do sistema.Environment variables set in launchSettings.json override those set in the system environment.

Para obter mais informações sobre como migrar a configuração de aplicativo de versões anteriores do ASP.NET, consulte Migrar do ASP.NET para o ASP.NET Core .For more information on migrating app configuration from earlier versions of ASP.NET, see Migrar do ASP.NET para o ASP.NET Core.

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

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

Recursos adicionaisAdditional resources

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:

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

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

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

using Microsoft.Extensions.Configuration;

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

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

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

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

Outra configuraçãoOther configuration

Este tópico pertence apenas à configuração do aplicativo.This topic only pertains to app configuration. Outros aspectos da execução e Hospedagem de aplicativos ASP.NET Core são configurados usando arquivos de configuração não abordados neste tópico:Other aspects of running and hosting ASP.NET Core apps are configured using configuration files not covered in this topic:

  • launch.jsem / As launchSettings.jsno são arquivos de configuração de ferramentas para o ambiente de desenvolvimento, descritos:launch.json/launchSettings.json are tooling configuration files for the Development environment, described:
  • web.config é um arquivo de configuração de servidor, descrito nos seguintes tópicos:web.config is a server configuration file, described in the following topics:

Para obter mais informações sobre como migrar a configuração de aplicativo de versões anteriores do ASP.NET, consulte Migrar do ASP.NET para o ASP.NET Core .For more information on migrating app configuration from earlier versions of ASP.NET, see Migrar do ASP.NET para o ASP.NET Core.

Configuração padrãoDefault configuration

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

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

SegurançaSecurity

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

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

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

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

Dados de configuração hierárquicaHierarchical configuration data

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

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

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

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

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

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

ConvençõesConventions

Origens e provedoresSources and providers

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

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

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

Nos exemplos a seguir, o _config campo é usado para acessar os valores de configuração:In the following examples, the _config field is used to access configuration values:

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }
}
public class HomeController : Controller
{
    private readonly IConfiguration _config;

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

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.

simétricasKeys

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. Para obter mais informações sobre chaves JSON duplicadas, consulte este problema do GitHub.For more information on duplicate JSON keys, see this GitHub issue.
  • Chaves hierárquicasHierarchical keys
    • Ao interagir com a API de configuração, um separador de dois-pontos (:) funciona em todas as plataformas.Within the Configuration API, a colon separator (:) works on all platforms.
    • Nas variáveis de ambiente, talvez um separador de dois-pontos não funcione em todas as plataformas.In environment variables, a colon separator may not work on all platforms. Um sublinhado duplo (__) é compatível com todas as plataformas e é convertido automaticamente em dois-pontos.A double underscore (__) is supported by all platforms and is automatically converted into a colon.
    • No Azure Key Vault, as chaves hierárquicas usam -- (dois traços) como separador.In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. Escreva o código para substituir os traços por dois-pontos quando os segredos forem carregados na configuração do aplicativo.Write code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
  • O ConfigurationBinder dá suporte a matrizes de associação para objetos usando os índices em chaves de configuração.The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. A associação de matriz está descrita na seção Associar uma matriz a uma classe.Array binding is described in the Bind an array to a class section.

ValoresValues

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

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

ProvedoresProviders

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

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

Na inicialização, as fontes de configuração são lidas na ordem especificada pelos provedores de configuração.Configuration sources are read in the order that their configuration providers are specified at startup. Os provedores de configuração descritos neste tópico são descritos em ordem alfabética, não na ordem em que o código os organiza.The configuration providers described in this topic are described in alphabetical order, not in the order that the code arranges them. Solicite provedores de configuração no código para se adequar às prioridades das fontes de configuração subjacentes que o aplicativo requer.Order configuration providers in code to suit the priorities for the underlying configuration sources that the app requires.

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

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

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

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

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

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

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

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

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

ConfigureAppConfigurationConfigureAppConfiguration

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

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

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

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

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

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

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

Remover provedores adicionados por CreateDefaultBuilderRemove providers added by CreateDefaultBuilder

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

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

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

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

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

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

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

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

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

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

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

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

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

ExemploExample

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

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

ArgumentosArguments

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

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

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

Exemplo de comandos:Example commands:

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

Mapeamentos de comutadorSwitch mappings

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

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

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

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

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

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

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

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

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

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

ChaveKey ValorValue
-CLKey1 CommandLineKey1
-CLKey2 CommandLineKey2

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

dotnet run -CLKey1=value1 -CLKey2=value2

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

ChaveKey ValorValue
CommandLineKey1 value1
CommandLineKey2 value2

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

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

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

O : separador não funciona com chaves hierárquicas de variáveis de ambiente em todas as plataformas.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, o sublinhado duplo é:__, the double underscore, is:

  • Compatível com todas as plataformas.Supported by all platforms. Por exemplo, o : separador não tem suporte do bash, mas sim __ .For example, the : separator is not supported by Bash, but __ is.
  • Substituído automaticamente por um:Automatically replaced by a :

Azure app serviço permite definir 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 setting environment variables in the Azure Portal that can override app configuration using the Environment Variables Configuration Provider. Para saber mais, confira Aplicativos do Azure: substituir a configuração do aplicativo usando o portal do Azure.For more information, see Azure Apps: Override app configuration using the Azure Portal.

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

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

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

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

Para fornecer a configuração de aplicativo de variáveis de ambiente adicionais, chame os provedores adicionais do aplicativo no ConfigureAppConfiguration e chame AddEnvironmentVariables com o prefixo:To provide app configuration from additional environment variables, call the app's additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix:

.ConfigureAppConfiguration((hostingContext, config) =>
{
    config.AddEnvironmentVariables(prefix: "PREFIX_");
})

Chame AddEnvironmentVariables Last para permitir que as variáveis de ambiente com o prefixo fornecido substituam valores de outros provedores.Call AddEnvironmentVariables last to allow environment variables with the given prefix to override values from other providers.

ExemploExample

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

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

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

Para expor todas as variáveis de ambiente disponíveis para o aplicativo, altere o FilteredConfiguration em pages/index. cshtml. cs para o seguinte:To expose all of the environment variables available to the app, change the FilteredConfiguration in Pages/Index.cshtml.cs to the following:

FilteredConfiguration = _config.AsEnumerable();

PrefixosPrefixes

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

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

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

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

Prefixos de cadeia de conexãoConnection string prefixes

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

Prefixo da cadeia de conexãoConnection string prefix ProvedorProvider
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

ExemploExample

Uma variável de ambiente de cadeia de conexão personalizada é criada no servidor:A custom connection string environment variable is created on the server:

  • Nome: CUSTOMCONNSTR_ReleaseDBName: CUSTOMCONNSTR_ReleaseDB
  • Valor: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=TrueValue: Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True

Se IConfiguration for injetado e atribuído a um campo chamado _config , leia o valor:If IConfiguration is injected and assigned to a field named _config, read the value:

_config["ConnectionStrings:ReleaseDB"]

Provedor de Configuração de ArquivoFile Configuration Provider

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

Provedor de Configuração INIINI Configuration Provider

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

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

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

As sobrecargas permitem especificar:Overloads permit specifying:

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

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

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

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

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

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

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

Provedor de Configuração JSONJSON Configuration Provider

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

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

As sobrecargas permitem especificar:Overloads permit specifying:

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

AddJsonFileé chamado automaticamente duas vezes quando um novo Construtor de hosts é inicializado com o CreateDefaultBuilder .AddJsonFile is automatically called twice when a new host builder is initialized with CreateDefaultBuilder. O método é chamado para carregar a configuração de:The method is called to load configuration from:

  • appsettings.jsem: este 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 do ambiente do arquivo é carregada com base no IHostingEnvironment. environmentname.appsettings.{Environment}.json: The environment version of the file is loaded based on the IHostingEnvironment.EnvironmentName.

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

CreateDefaultBuilder também carrega:CreateDefaultBuilder also loads:

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

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

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

ExemploExample

O aplicativo de exemplo aproveita o método de conveniência estática CreateDefaultBuilder para criar o host, que inclui duas chamadas para AddJsonFile :The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host, which includes two calls to AddJsonFile:

  • A primeira chamada para AddJsonFile carrega a configuração de appsettings.jsem:The first call to AddJsonFile loads configuration from appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    
  • A segunda chamada para AddJsonFile carrega a configuração de appSettings. { Ambiente}. JSON.The second call to AddJsonFile loads configuration from appsettings.{Environment}.json. Para appsettings.Development.js no aplicativo de exemplo, o seguinte arquivo é carregado:For appsettings.Development.json in the sample app, the following file is loaded:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Debug",
          "System": "Information",
          "Microsoft": "Information"
        }
      }
    }
    
  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. A saída contém pares chave-valor para a configuração com base no ambiente do aplicativo.The output contains key-value pairs for the configuration based on the app's environment. O nível de log para a chave Logging:LogLevel:Default é Debug ao executar o aplicativo no ambiente de desenvolvimento.The log level for the key Logging:LogLevel:Default is Debug when running the app in the Development environment.
  3. Execute o aplicativo de exemplo novamente no ambiente de produção:Run the sample app again in the Production environment:
    1. Abra as Propriedades/launchSettings.jsno arquivo.Open the Properties/launchSettings.json file.
    2. No ConfigurationSample perfil, altere o valor da variável de ASPNETCORE_ENVIRONMENT ambiente para Production .In the ConfigurationSample profile, change the value of the ASPNETCORE_ENVIRONMENT environment variable to Production.
    3. Salve o arquivo e execute o aplicativo com o dotnet run em um shell de comando.Save the file and run the app with dotnet run in a command shell.
  4. As configurações no appsettings.Development.js não substituem mais as configurações no appsettings.js.The settings in the appsettings.Development.json no longer override the settings in appsettings.json. O nível de log para a chave Logging:LogLevel:Default é Warning .The log level for the key Logging:LogLevel:Default is Warning.

Provedor de Configuração XMLXML Configuration Provider

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

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

As sobrecargas permitem especificar:Overloads permit specifying:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

As sobrecargas permitem especificar:Overloads permit specifying:

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

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

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

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

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

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

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

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

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

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

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

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

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

GetValueGetValue

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

O exemplo a seguir:The following example:

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

    public int NumberConfig { get; private set; }

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

GetSection, GetChildren e ExistsGetSection, GetChildren, and Exists

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

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

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

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

GetSectionGetSection

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

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

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

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

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

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

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

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

GetChildrenGetChildren

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

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

var children = configSection.GetChildren();

ExistsExists

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

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

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

Associar a 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. Assim como acontece com a associação de um objeto simples, somente as propriedades públicas de leitura/gravação são associadas.As with binding a simple object, only public read/write properties are bound.

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

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>

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

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

ConfigurationBinder.Get<T>associa e retorna o tipo especificado.ConfigurationBinder.Get<T> binds and returns the specified type. O Get<T> é mais conveniente do que usar Bind.Get<T> is more convenient than using Bind. O código a seguir mostra como usar Get<T> o com o exemplo anterior:The following code shows how to use Get<T> with the preceding example:

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 expõe um segmento de chave numérico ( :0: , :1: , … :{n}: ) é capaz de associar a matriz 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.AddInMemoryCollection(arrayDict);
                config.AddJsonFile(
                    "json_array.json", optional: false, reloadOnChange: false);
                config.AddJsonFile(
                    "starship.json", optional: false, reloadOnChange: false);
                config.AddXmlFile(
                    "tvshow.xml", optional: false, reloadOnChange: false);
                config.AddEFConfiguration(
                    options => options.UseInMemoryDatabase("InMemoryDb"));
                config.AddCommandLine(args);
            })
            .UseStartup<Startup>();
}

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

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

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

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

ConfigurationBinder.Get<T>a sintaxe 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>();

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 ArrayExample.Entries ValorArrayExample.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"
}

Em ConfigureAppConfiguration:In ConfigureAppConfiguration:

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

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

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

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

Índice ArrayExample.EntriesArrayExample.Entries Index ArrayExample.Entries ValorArrayExample.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"
    ]
  }
}

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

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 JsonArrayExample.Subsection ValorJsonArrayExample.Subsection Value
00 valueBvalueB
11 valueCvalueC
22 valueDvalueD

Provedor de Configuração personalizadoCustom configuration provider

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Action<DbContextOptionsBuilder> OptionsAction { get; }

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

        OptionsAction(builder);

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

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

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

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

        dbContext.SaveChanges();

        return configValues;
    }
}

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

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

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

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

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

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

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

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

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

public class Startup
{
    private readonly IConfiguration _config;

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

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

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

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

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

Para acessar as definições de configuração em uma Razor página de páginas ou em uma exibição do MVC, adicione uma diretiva using (referência C#: usando diretiva) para o namespaceMicrosoft.Extensions.Configuração e insira IConfiguration na página ou 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 Razor página de páginas:In a Razor Pages page:

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

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

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

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

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

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

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

Recursos adicionaisAdditional resources