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

Este tutorial mostra como habilitar atualizações de configuração dinâmicas em um aplicativo ASP.NET Core. Ele se baseia no aplicativo Web introduzido nos Inícios Rápidos. Seu aplicativo aproveitará a biblioteca de provedores de Configuração de Aplicativos para os recursos internos de cache e atualização de configuração. Antes de continuar, conclua Criar um aplicativo ASP.NET Core com a Configuração de Aplicativo primeiro.

Neste tutorial, você aprenderá como:

• Configurar seu aplicativo para atualizar a configuração em resposta a alterações em um repositório de Configuração de Aplicativos.
• Injetar a configuração mais recente no aplicativo.

Pré-requisitos

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

Adicionar uma chave sentinela

A 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 é detectada, o aplicativo atualiza todos os valores de configuração. Essa abordagem ajuda a garantir a consistência da configuração no aplicativo e reduz o número geral de solicitações feitas ao repositório de Configuração de Aplicativos em comparação ao monitoramento de todas as chaves quanto a alterações.

1. No portal do Azure, abra o repositório de Configuração de Aplicativos e selecione Explorador de Configuração > Criar > Valor de chave.
2. Para Chave, insira TestApp:Settings:Sentinel. Para Valor, insira "1". Deixe Rótulo e Tipo de conteúdo em branco.
3. Escolha Aplicar.

Recarregar os dados da Configuração de Aplicativo

1. Abra Program.cs e atualize o método AddAzureAppConfiguration que você adicionou 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 método Select é usado para carregar todos os valores de chave cujo nome de chave começa com TestApp: e que não têm rótulo. Você pode chamar o método Select mais de uma vez para carregar configurações com diferentes prefixos ou rótulos. Se você compartilha um repositório de Configuração de Aplicativos com vários aplicativos, essa abordagem ajuda a carregar apenas a configuração relevante para o aplicativo atual em vez de carregar tudo de seu repositório.

   No método ConfigureRefresh, você registra as chaves que deseja monitorar quanto a alterações no repositório de Configuração de Aplicativos. O parâmetro refreshAll para o método Register indica que todas as configurações especificadas pelo método Select serão recarregadas se a chave registrada for alterada.

   Dica

   Você pode adicionar uma chamada para o método refreshOptions.SetCacheExpiration 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 você precisar reduzir o número de solicitações feitas ao repositório de Configuração de Aplicativos.

2. Adicione o middleware da Configuração de Aplicativos do Azure à coleção de serviços do 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 método UseAzureAppConfiguration . Isso permite que o aplicativo use o middleware da Configuração de Aplicativos 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 o aplicativo para usar o padrão de opções em ASP.NET Core durante o início rápido. Quando a configuração subjacente do aplicativo for atualizada da Configuração de Aplicativos, o objeto Settings fortemente tipado obtido por meio de IOptionsSnapshot<T> será atualizado automaticamente. Observe que você não deve usar o IOptions<T> se a atualização de configuração dinâmica for desejada porque ela não lê os dados de configuração depois que o aplicativo é iniciado.

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

A atualização de configuração é disparada pelas solicitações de entrada ao aplicativo Web. Nenhuma atualização ocorrerá se o aplicativo estiver ocioso. Quando o aplicativo estiver ativo, o middleware da Configuração de Aplicativos monitorará a chave sentinela ou quaisquer outras chaves registradas para serem atualizadas na chamada ConfigureRefresh. O middleware é disparado após cada solicitação de entrada para o aplicativo. No entanto, o middleware enviará solicitações para verificar o valor na Configuração de Aplicativos somente quando o tempo de término do cache definido tiver passado.

• Se uma solicitação à Configuração de Aplicativos para detecção de alterações falhar, o aplicativo continuará a usar a configuração armazenada em cache. Novas tentativas de verificar se há alterações serão feitas periodicamente enquanto houver novas solicitações de entrada no aplicativo.
• A atualização de configuração ocorre de forma assíncrona para o processamento das solicitações de entrada do aplicativo. Ela não bloqueará nem reduzirá a velocidade da solicitação de entrada que disparou a atualização. Talvez a solicitação que disparou a atualização não receba os valores de configuração atualizados, mas solicitações posteriores receberão.
• Para verificar se o middleware foi disparado, chame o método app.UseAzureAppConfiguration() assim que possível no pipeline de solicitação para que outro middleware não o ignore no aplicativo.

Compilar e executar 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 construção for concluída com êxito, execute o seguinte comando para executar o aplicativo Web localmente:

       dotnet run
   

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

   

4. Entre no portal do Azure. Escolha Todos os recursos e escolha o repositório de Configuração de Aplicativos que você criou no início rápido.

5. Selecione Explorador de Configurações e atualize os valores das seguintes chaves. Por fim, lembre-se de atualizar a chave sentinela.

   Chave	Valor
   TestApp:Settings:BackgroundColor	green
   TestApp:Settings:FontColor	lightGray
   TestApp:Settings:Message	Dados da Configuração de Aplicativo do Azure – agora com atualizações dinâmicas!
   TestApp:Settings:Sentinel	2

6. Atualize o navegador algumas vezes. Quando o cache expirar após 30 segundos, a página mostrará o conteúdo atualizado.

   

Log e monitoramento

Os logs são emitidos após a atualização da configuração e contêm informações detalhadas sobre os valores-chave recuperados do seu armazenamento de Configuração de Aplicativos e as alterações de configuração feitas no seu aplicativo.

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

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

  Nível de log	Descrição
  Depurar	Os registros incluem a chave e o rótulo dos valores-chave que seu aplicativo monitora em busca de alterações no seu repositório de Configuração de Aplicativos. As informações também incluem se o valor da chave foi alterado em comparação com o que já foi carregado por seu aplicativo. Habilite os logs nesse nível para solucionar os problemas do seu aplicativo se uma alteração de configuração não acontecer conforme o esperado.
  Informações	Os registros incluem as chaves das definições de configuração atualizadas durante uma atualização da configuração. Os valores das definições de configuração são omitidos no log para evitar o vazamento de dados confidenciais. Você pode monitorar os logs nesse nível para garantir que seu aplicativo receba 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 os 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 no nível do registro Debug adicionando o exemplo a seguir ao seu arquivo appsettings.json. Esse exemplo também se aplica a todos os outros níveis de log.

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

• A categoria de registro é Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, que aparece antes de cada registro. 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 de ILogger é o método preferido em aplicativos ASP.NET e é priorizado como fonte de registro se uma instância de ILoggerFactory estiver presente. No entanto, se ILoggerFactory não estiver disponível, os registros podem ser habilitados e configurados alternativamente por meio das instruções para aplicativos.NET Core. Para obter mais informações, consulte Registro em log no .NET Core e no ASP.NET Core.

Observação

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

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

Limpar recursos

Se não deseja continuar usando os recursos criados neste artigo, exclua o grupo de recursos que você criou aqui para evitar encargos.

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se tiver criado os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que você deseja manter, exclua cada um individualmente do respectivo 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..., digite o nome do seu grupo de recursos.
3. Na lista de resultados, selecione o nome do grupo de recursos para conferir uma visão geral.
4. Selecione Excluir grupo de recursos.
5. Você receberá uma solicitação para confirmar a exclusão do grupo de recursos. Insira o nome do grupo de recursos para confirmar e selecione Excluir.

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

Próximas etapas

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

Acessar a Configuração de Aplicativos usando identidade gerenciada