Tutorial: Usar a configuração dinâmica em um aplicativo ASP.NET Core

Este tutorial mostra como você pode habilitar atualizações de configuração dinâmica em um aplicativo ASP.NET Core. Ele se baseia no aplicativo Web introduzido nos inícios rápidos. Seu aplicativo aproveitará a biblioteca do provedor de Configuração de Aplicativo para seus recursos internos de configuração, cache e atualização. Antes de continuar, conclua primeiro Criar um aplicativo ASP.NET Core com a Configuração do Aplicativo.

Neste tutorial, irá aprender a:

• Configure seu aplicativo para atualizar sua configuração em resposta a alterações em uma loja de configuração de aplicativos.
• Injete a configuração mais recente em seu aplicativo.

Pré-requisitos

Conclua o início rápido: crie um aplicativo ASP.NET Core com a Configuração do aplicativo.

Adicionar uma chave sentinela

Uma chave sentinela é uma chave que você atualiza depois de concluir a alteração de todas as outras chaves. Seu aplicativo monitora a chave sentinela. Quando uma alteração é detetada, seu aplicativo atualiza todos os valores de configuração. Essa abordagem ajuda a garantir a consistência da configuração em seu aplicativo e reduz o número geral de solicitações feitas à sua loja de configuração de aplicativos, em comparação com o monitoramento de todas as chaves para alterações.

1. No portal do Azure, abra seu repositório de Configuração de Aplicativo e selecione Configuration Explorer > Create > Key-value.
2. Em Key, digite TestApp:Settings:Sentinel. Em Valor, insira 1. Deixe Rótulo e Tipo de conteúdo em branco.
3. Selecione Aplicar.

Recarregar dados da Configuração do Aplicativo

1. Abra Program.cs e atualize o AddAzureAppConfiguration método adicionado anteriormente durante o início rápido.

   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(connectionString)
              // Load all keys that start with `TestApp:` and have no label
              .Select("TestApp:*", LabelFilter.Null)
              // Configure to reload configuration if the registered sentinel key is modified
              .ConfigureRefresh(refreshOptions =>
                   refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
   });
   

   O Select método é usado para carregar todos os valores-chave cujo nome da chave começa com TestApp: e que não têm rótulo. Você pode chamar o Select método mais de uma vez para carregar configurações com diferentes prefixos ou rótulos. Se partilhar uma App Configuration Store com várias aplicações, esta abordagem ajuda a carregar a configuração apenas relevante para a sua aplicação atual, em vez de carregar tudo a partir da sua loja.

   No método, você registra as ConfigureRefresh chaves que deseja monitorar para alterações em sua loja de configuração de aplicativos. O refreshAll parâmetro para o Register método indica que todas as configurações especificadas pelo Select método serão recarregadas se a chave registrada for alterada.

   Gorjeta

   Você pode adicionar uma chamada ao refreshOptions.SetCacheExpiration método para especificar o tempo mínimo entre as atualizações de configuração. Neste exemplo, você usa o valor padrão de 30 segundos. Ajuste para um valor mais alto se precisar reduzir o número de solicitações feitas à sua App Configuration Store.

2. Adicione o middleware de Configuração de Aplicativo do Azure à coleção de serviços do seu aplicativo.

   Atualize Program.cs com o código a seguir.

   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Add Azure App Configuration middleware to the container of services.
   builder.Services.AddAzureAppConfiguration();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. Chame o UseAzureAppConfiguration método. Ele permite que seu aplicativo use o middleware de Configuração do Aplicativo para atualizar a configuração automaticamente.

   Atualize Program.cs com o código a seguir.

   // Existing code in Program.cs
   // ... ...
   
   var app = builder.Build();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }
   
   // Use Azure App Configuration middleware for dynamic configuration refresh.
   app.UseAzureAppConfiguration();
   
   // The rest of existing code in program.cs
   // ... ...
   

Você configurou seu aplicativo para usar o padrão de opções no ASP.NET Core durante o início rápido. Quando a configuração subjacente do seu aplicativo é atualizada a partir da Configuração do aplicativo, seu objeto fortemente tipado Settings obtido via IOptionsSnapshot<T> é atualizado automaticamente. Observe que você não deve usar a IOptions<T> atualização de configuração dinâmica se for desejada porque ela não lê os dados de configuração depois que o aplicativo for iniciado.

Atualização de configuração orientada por solicitação

A atualização da configuração é acionada pelas solicitações de entrada para seu aplicativo Web. Nenhuma atualização ocorrerá se seu aplicativo estiver ocioso. Quando seu aplicativo está ativo, o middleware de Configuração do Aplicativo monitora a chave sentinela ou qualquer outra chave que você registrou para atualização na ConfigureRefresh chamada. O middleware é acionado a cada solicitação de entrada no seu aplicativo. No entanto, o middleware só enviará solicitações para verificar o valor na Configuração do Aplicativo quando o tempo de expiração do cache definido tiver passado.

• Se uma solicitação à Configuração do Aplicativo para deteção de alterações falhar, seu aplicativo continuará a usar a configuração em cache. Novas tentativas de verificar alterações serão feitas periodicamente enquanto houver novas solicitações de entrada para seu aplicativo.
• A atualização de configuração acontece de forma assíncrona para o processamento das solicitações de entrada do seu aplicativo. Ele não bloqueará ou retardará a solicitação de entrada que disparou a atualização. A solicitação que disparou a atualização pode não obter os valores de configuração atualizados, mas as solicitações posteriores obterão novos valores de configuração.
• Para garantir que o middleware seja acionado, chame o app.UseAzureAppConfiguration() método o mais cedo possível no pipeline de solicitações para que outro middleware não o ignore em seu aplicativo.

Crie e execute o aplicativo localmente

1. Para criar o aplicativo usando a CLI do .NET, execute o seguinte comando no shell de comando:

       dotnet build
   

2. Depois que a compilação for concluída com êxito, execute o seguinte comando para executar o aplicativo Web localmente:

       dotnet run
   

3. Abra uma janela do dotnet run navegador e vá para o URL mostrado na saída.

   

4. Inicie sessão no portal do Azure. Selecione Todos os recursos e selecione a loja de configuração de aplicativos que você criou no início rápido.

5. Selecione Configuration explorer e atualize os valores das seguintes chaves. Lembre-se de atualizar finalmente a chave sentinela.

   Key	valor
   TestApp:Configurações:BackgroundColor	verde
   TestApp:Configurações:FontColor	cinza claro
   TestApp:Configurações:Mensagem	Dados da Configuração de Aplicativos do Azure - agora com atualizações em tempo real!
   TestApp:Configurações:Sentinel	2

6. Atualize o navegador algumas vezes. Quando o cache expira após 30 segundos, a página é exibida com conteúdo atualizado.

   

Registos e monitorização

Os logs são enviados após a atualização da configuração e contêm informações detalhadas sobre os valores-chave recuperados da sua loja de configuração de aplicativos e as alterações de configuração feitas em seu aplicativo.

• Um padrão ILoggerFactory é adicionado automaticamente quando services.AddAzureAppConfiguration() é invocado. O provedor de Configuração de Aplicativo usa isso ILoggerFactory para criar uma instância do ILogger, que gera esses logs. ASP.NET Core usa ILogger para registro em log por padrão, portanto, você não precisa fazer alterações de código adicionais para habilitar o registro em log para o provedor de Configuração de Aplicativo.

• Os logs são gerados em diferentes níveis de log. O nível padrão é Information.

  Nível do registo	Description
  Depurar	Os logs incluem a chave e o rótulo dos valores-chave que seu aplicativo monitora para alterações da sua loja de configuração de aplicativos. As informações também incluem se o valor-chave foi alterado em comparação com o que seu aplicativo já carregou. Habilite os logs nesse nível para solucionar problemas do seu aplicativo se uma alteração de configuração não ocorrer conforme o esperado.
  Informação	Os logs incluem as chaves das definições de configuração atualizadas durante uma atualização de configuração. Os valores das definições de configuração são omitidos do log para evitar o vazamento de dados confidenciais. Você pode monitorar logs nesse nível para garantir que seu aplicativo capte as alterações de configuração esperadas.
  Aviso	Os logs incluem falhas e exceções que ocorreram durante a atualização da configuração. Ocorrências ocasionais podem ser ignoradas porque o provedor de configuração continuará usando os dados armazenados em cache e tentará atualizar a configuração na próxima vez. Você pode monitorar logs nesse nível em busca de avisos repetitivos que possam indicar possíveis problemas. Por exemplo, você girou a cadeia de conexão, mas esqueceu de atualizar seu aplicativo.

  Você pode habilitar o registro em log no nível de Debug log adicionando o exemplo a seguir ao seu appsettings.json arquivo. Este exemplo também se aplica a todos os outros níveis de log.

  "Logging": {
      "LogLevel": {
          "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
      }
  }
  

• A categoria de log é Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, que aparece antes de cada log. Aqui estão alguns exemplos de logs em cada nível de log:

  dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      Setting updated. Key:'ExampleKey'
  
  warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
      A refresh operation failed while resolving a Key Vault reference.
  Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'
  

O uso ILogger é o método preferido em aplicativos ASP.NET e é priorizado como a fonte de registro se uma instância de ILoggerFactory estiver presente. No entanto, se ILoggerFactory não estiver disponível, os logs podem, alternativamente, ser habilitados e configurados por meio das instruções para aplicativos .NET Core. Para obter mais informações, consulte o registro em log no .NET Core e no ASP.NET Core.

Nota

O registro em log estará disponível se você usar a versão 6.0.0 ou posterior de qualquer um dos seguintes pacotes.

• Microsoft.Extensions.Configuration.AzureAppConfiguration
• Microsoft.Azure.AppConfiguration.AspNetCore
• Microsoft.Azure.AppConfiguration.Functions.Worker

Clean up resources (Limpar recursos)

Se não quiser continuar a utilizar os recursos criados neste artigo, elimine o grupo de recursos que criou aqui para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são excluídos permanentemente. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. Se você criou os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que deseja manter, exclua cada recurso individualmente de seu respetivo painel em vez de excluir o grupo de recursos.

1. Entre no portal do Azure e selecione Grupos de recursos.
2. Na caixa Filtrar por nome, introduza o nome do seu grupo de recursos.
3. Na lista de resultados, selecione o nome do grupo de recursos para ver uma visão geral.
4. Selecione Eliminar grupo de recursos.
5. É-lhe pedido que confirme a eliminação do grupo de recursos. Insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

Após alguns momentos, o grupo de recursos e todos os seus recursos são excluídos.

Próximos passos

Neste tutorial, você habilitou seu aplicativo Web ASP.NET Core para atualizar dinamicamente as definições de configuração da Configuração do aplicativo. Para saber como usar uma identidade gerenciada pelo Azure para simplificar o acesso à Configuração do Aplicativo, continue para o próximo tutorial.

Acessar a configuração do aplicativo usando identidade gerenciada