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

A biblioteca do provedor do .NET de Configuração de Aplicativos é compatível com a atualização de configuração sob demanda sem fazer o aplicativo reiniciar. Este tutorial mostra como você pode implementar atualizações de configuração dinâmica no código. Ele se baseia no aplicativo introduzido no início rápido. Antes de continuar, você deve concluir as ações em Criar um aplicativo .NET Core com a Configuração de Aplicativos.

Você pode usar qualquer editor de código para executar as etapas deste tutorial. Visual Studio Code é uma opção excelente que está disponível nas plataformas Windows, macOS e Linux.

Neste tutorial, você aprenderá como:

Pré-requisitos

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

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

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

Abra Program.cs e atualize o arquivo com o código a seguir.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(TimeSpan.FromSeconds(10));
            });

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

No método ConfigureRefresh, uma chave em seu repositório de Configuração de Aplicativos é registrada para monitoramento de alterações. O método Register tem um parâmetro booliano opcional refreshAll que pode ser usado para indicar se todos os valores de configuração deverão ser atualizados se a chave registrada for alterada. Neste exemplo, somente a chave TestApp:Settings:Message será atualizada. O método SetCacheExpiration especifica o tempo mínimo para fazer uma nova solicitação à Configuração de Aplicativos para verificar se há alterações de configuração. Neste exemplo, você substitui o tempo de expiração padrão de 30 segundos, especificando em lugar dele um tempo de dez segundos, para fins de demonstração.

Chamar o método ConfigureRefresh sozinho não fará com que a configuração seja atualizada automaticamente. Você chama o método TryRefreshAsync da interface IConfigurationRefresher para disparar uma atualização. Esse design serve para evitar solicitações enviadas à Configuração de Aplicativos mesmo quando o aplicativo está ocioso. Convém incluir a chamada TryRefreshAsync quando você considerar o aplicativo ativo. Por exemplo, isso pode ocorrer quando você processa uma mensagem de entrada, uma ordem ou uma iteração de uma tarefa complexa. Se o aplicativo ficar ativo todo o tempo, a chamada poderá ser incluída por meio de um temporizador. Neste exemplo, você chamará TryRefreshAsync toda vez que pressionar a tecla Enter. Se a chamada TryRefreshAsync falhar por algum motivo, seu aplicativo continuará a usar a configuração armazenada em cache. Outra tentativa será feita quando o tempo de expiração do cache configurado tiver passado e a chamada TryRefreshAsync for disparada pela atividade do aplicativo novamente. Chamar TryRefreshAsync é uma não operação antes que o tempo de expiração do cache configurado decorra, portanto, seu impacto no desempenho é mínimo, mesmo se essa chamada é realizada com frequência.

Atualização de configuração usando injeção de dependência

No código anterior, você está salvando manualmente uma instância do IConfigurationRefresher para invocar TryRefreshAsync. Como alternativa, se você estiver usando a injeção de dependência para resolve seus serviços, poderá referenciar as etapas a seguir.

1. Registre os serviços de Configuração de Aplicativos necessários invocando AddAzureAppConfiguration em seu IServiceCollection.

   Copie o seguinte código para Program.cs.

   // Existing code in Program.cs
   // ... ...
   
   // Add Azure App Configuration services to IServiceCollection
   builder.Services.AddAzureAppConfiguration();
   

2. Atualize sua configuração resolvendo uma instância do IConfigurationRefresherProvider de sua coleção de serviços e invocando TryRefreshAsync em cada um de seus atualizadores.

   class SampleConfigRefresher
   {
       private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;
   
       public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
       {
           _refreshers = refresherProvider.Refreshers;
       }
   
       public async Task RefreshConfiguration()
       {
           foreach (var refresher in _refreshers)
           {
               _ = refresher.TryRefreshAsync();
           }
       }
   }
   

Compilar e executar o aplicativo localmente

1. Defina uma variável de ambiente chamada ConnectionString e defina-a como a chave de acesso ao repositório de Configuração de Aplicativos. Se você usar o prompt de comando do Windows, execute o comando a seguir e reinicie o prompt de comando para permitir que a alteração entre em vigor:

    setx ConnectionString "<connection-string-of-your-app-configuration-store>"
   

   Se você usa o Windows PowerShell, execute o comando a seguir:

    $Env:ConnectionString = "<connection-string-of-your-app-configuration-store>"
   

   Se você usa macOS ou Linux, execute o comando a seguir:

    export ConnectionString='<connection-string-of-your-app-configuration-store>'
   

2. Execute o seguinte comando para compilar o aplicativo de console:

    dotnet build
   

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

    dotnet run
   

   

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

5. Selecione Gerenciador de Configurações e atualize os valores das seguintes chaves:

   Chave	Valor
   TestApp:Settings:Message	Dados da Configuração de Aplicativos do Azure – Atualizados

6. Pressione a tecla Enter para disparar uma atualização e imprimir o valor atualizado na janela do Prompt de Comando ou do PowerShell.

   

   Observação

   Uma vez que o tempo de expiração do cache foi definido como 10 segundos usando o método SetCacheExpiration ao especificar a configuração para a operação de atualização, o valor para a definição de configuração será atualizado apenas se pelo menos 10 segundos tiverem se passado desde a última atualização para essa configuração.

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. Se você tiver um aplicativo ASP.NET Core, consulte estas instruções para Registro em log e monitoramento em ASP.NET Core. Caso contrário, você pode habilitar o registro em log usando as instruções para registro em log com o SDK do Azure.

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

  Evento em nível	Descrição
  Detalhado	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.
  Informativo	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 em log no nível do evento Verboseespecificando o parâmetro EventLevel.Verbose, conforme feito no exemplo a seguir. Essas instruções também se aplicam a todos os outros níveis de evento. Este exemplo também habilita logs somente para a categoria Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh.

  using var listener = new AzureEventSourceListener((eventData, text) =>
  {
      if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
      {
          Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
      }
  }, EventLevel.Verbose);
  

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

  [Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'
  
  [Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  Setting updated. Key:'ExampleKey'
  
  [Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
  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'
  

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.

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

Nesse tutorial, você habilitou seu aplicativo .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.