Configuração do aplicativo

A principal maneira de carregar a configuração do aplicativo no Web Forms é com entradas no arquivo web.config, seja no servidor ou em um arquivo de configuração relacionado referenciado por web.config. Você pode usar o objeto estático ConfigurationManager para interagir com configurações de aplicativo, cadeias de conexão de repositório de dados e outros provedores de configuração estendidos que são adicionados ao aplicativo. É comum ver interações com a configuração do aplicativo, conforme visto no seguinte código:

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

Com o ASP.NET Core e com o Blazorno lado do servidor, o arquivo web.config PODERÁ estar presente se seu aplicativo estiver hospedado em um servidor IIS do Windows. No entanto, não há interação de ConfigurationManager com essa configuração e você pode receber uma configuração de aplicativo mais estruturada de outras fontes. Vamos dar uma olhada em como a configuração é coletada e como você ainda pode acessar informações de configuração de um arquivo web.config.

Fontes de configuração

O ASP.NET Core reconhece que há muitas fontes de configuração que talvez você queira usar em seu aplicativo. A estrutura tenta oferecer o melhor desses recursos por padrão. A configuração é lida e agregada dessas várias fontes pelo ASP.NET Core. Os valores carregados posteriormente para a mesma chave de configuração têm precedência sobre valores anteriores.

O ASP.NET Core foi projetado para ter reconhecimento de nuvem e facilitar a configuração de aplicativos para operadores e desenvolvedores. O ASP.NET Core tem reconhecimento de ambiente e sabe se está em execução em seu ambiente de Production ou de Development. O indicador de ambiente é definido na variável de ambiente do sistema ASPNETCORE_ENVIRONMENT. Se nenhum valor for configurado, o aplicativo será executado no ambiente Production.

Seu aplicativo pode disparar e adicionar configuração de várias fontes com base no nome do ambiente. Por padrão, a configuração é carregada dos seguintes recursos na ordem listada:

1. Arquivo appsettings.json, se estiver presente
2. Arquivo appsettings.{ENVIRONMENT_NAME}.json, se estiver presente
3. Arquivo de segredos do usuário no disco, se estiver presente
4. Variáveis de ambiente
5. Argumentos de linha de comando

Formato appsettings.json e acesso

O arquivo appsettings.json pode ser hierárquico com valores estruturados como o seguinte JSON:

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

Quando apresentado com o JSON anterior, o sistema de configuração nivela valores filho e referencia seus caminhos hierárquicos totalmente qualificados. Um caractere de dois-pontos (:) separa cada propriedade na hierarquia. Por exemplo, a chave de configuração section1:key0 acessa o valor key0 do literal de objeto section1.

Segredos do usuário

Os segredos do usuário são:

• Valores de configuração armazenados em um arquivo JSON na estação de trabalho do desenvolvedor, fora da pasta de desenvolvimento do aplicativo.
• Carregado somente ao executar no ambiente Development.
• Associado a um aplicativo específico.
• Gerenciado com o comando user-secrets da CLI do .NET.

Configure seu aplicativo para armazenamento de segredos executando o comando user-secrets:

dotnet user-secrets init

O comando anterior adiciona um elemento UserSecretsId ao arquivo de projeto. O elemento contém um GUID, que é usado para associar segredos ao aplicativo. Em seguida, você pode definir um segredo com o comando set. Por exemplo:

dotnet user-secrets set "Parent:ApiKey" "12345"

O comando anterior disponibiliza a chave de configuração Parent:ApiKey disponível na estação de trabalho de um desenvolvedor com o valor 12345.

Para saber mais sobre como criar, armazenar e gerenciar segredos do usuário, confira o documento Armazenamento seguro de segredos do aplicativo em desenvolvimento no ASP.NET Core.

Variáveis de ambiente

O próximo conjunto de valores carregados na configuração do aplicativo são as variáveis de ambiente do sistema. Todas as configurações de variável de ambiente do seu sistema agora estão acessíveis para você por meio da API de configuração. Os valores hierárquicos são nivelados e separados por caracteres de dois-pontos quando lidos dentro do aplicativo. No entanto, alguns sistemas operacionais não permitem nomes de variáveis de ambiente de caracteres de dois pontos. O ASP.NET Core resolve essa limitação convertendo valores que têm sublinhados duplos (__) em dois pontos quando são acessados. O valor Parent:ApiKey da seção de segredos do usuário acima pode ser substituído pela variável de ambiente Parent__ApiKey.

Argumentos de linha de comando

A configuração também pode ser fornecida como argumentos de linha de comando quando seu aplicativo é iniciado. Use a notação de traço duplo (--) ou de barra (/) para indicar o nome do valor de configuração a ser definido e o valor a ser configurado. A sintaxe se assemelha aos seguintes comandos:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

O retorno de web.config

Se você tiver implantado seu aplicativo no Windows no IIS, o arquivo web.config ainda configurará o IIS para gerenciar seu aplicativo. Por padrão, o IIS adiciona uma referência ao ANCM (Módulo do ASP.NET Core). ANCM é um módulo nativo do IIS que hospeda seu aplicativo no lugar do servidor Web Kestrel. Essa seção web.config se assemelha à seguinte marcação XML:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

A configuração específica do aplicativo pode ser definida aninhando um elemento environmentVariables no elemento aspNetCore. Os valores definidos nesta seção são apresentados ao aplicativo ASP.NET Core como variáveis de ambiente. As variáveis de ambiente são carregadas adequadamente durante esse segmento de inicialização do aplicativo.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

Configuração de leitura no aplicativo

O ASP.NET Core fornece a configuração do aplicativo por meio da interface IConfiguration. Essa interface de configuração deve ser solicitada por seus componentes do Blazor, páginas do Blazor e qualquer outra classe gerenciada por ASP.NET Core que precise de acesso à configuração. A estrutura do ASP.NET Core preencherá automaticamente essa interface com a configuração resolvida configurada anteriormente. Em uma página Blazor ou marcação Razor de um componente, você pode injetar o objeto IConfiguration com uma diretiva @inject na parte superior do arquivo .razor, como esta:

@inject IConfiguration Configuration

Essa instrução anterior disponibiliza o objeto IConfiguration como a variável Configuration em todo o restante do modelo do Razor.

As configurações individuais podem ser lidas especificando a hierarquia de configuração buscada como um parâmetro de indexador:

var mySetting = Configuration["section1:key0"];

Você pode buscar seções de configuração inteiras usando o método GetSection para recuperar uma coleção de chaves em um local específico com uma sintaxe semelhante a GetSection("section1") para recuperar a configuração da seção1 do exemplo anterior.

Configuração fortemente tipada

Com o Web Forms, foi possível criar um tipo de configuração fortemente tipado que herdou do tipo ConfigurationSection e dos tipos associados. Um ConfigurationSection permitiu que você configurasse algumas regras de negócios e processamento para esses valores de configuração.

No ASP.NET Core, você pode especificar uma hierarquia de classe que receberá os valores de configuração. Essas classes:

• Não precisam herdar de uma classe pai.
• Devem incluir propriedades public que correspondam às propriedades e referências de tipo para a estrutura de configuração que você deseja capturar.

Para o exemplo appsettings.json anterior, você pode definir as seguintes classes para capturar os valores:

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

Essa hierarquia de classe pode ser preenchida adicionando a linha a seguir ao método Startup.ConfigureServices (ou local apropriado em Program.cs usando a propriedade builder.Services em vez de services):

services.Configure<MyConfig>(Configuration);

No restante do aplicativo, você pode adicionar um parâmetro de entrada a classes ou uma diretiva @inject nos modelos Razor de tipo IOptions<MyConfig> para receber as configurações fortemente tipadas. A propriedade IOptions<MyConfig>.Value produzirá o valor MyConfig preenchido a partir das configurações.

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

Veja mais informações sobre o recurso Opções no documento Opções padrão em ASP.NET Core.