Compartilhar via

Tutorial: Usar a configuração dinâmica usando a atualização por push em um aplicativo .NET

Importante

Configurar notificações por push requer uma configuração cuidadosa. O modelo de pesquisa para atualização de configuração fornece uma configuração mais simples e deve ser usado na maioria dos casos, a menos que haja uma necessidade específica de notificações por push. Para saber mais sobre como usar o modelo de pesquisa, visite o tutorial de configuração dinâmica do .NET.

A biblioteca de clientes .NET da Configuração de Aplicativos do Azure fornece suporte para atualizar as configurações sob demanda sem exigir que um aplicativo seja reiniciado. Você pode configurar um aplicativo para detectar alterações na Configuração de Aplicativos usando uma ou ambas as duas abordagens a seguir:

  • Um modelo de pesquisa: essa abordagem é o comportamento padrão. Ele usa sondagem para detectar alterações na configuração. Após o intervalo de atualização de uma configuração decorrido, a próxima chamada para TryRefreshAsync ou RefreshAsync envia uma solicitação para o servidor. A solicitação verifica se há alterações na configuração. Se necessário, também obtém a configuração atualizada.

  • Um modelo push: essa abordagem usa eventos de Configuração de Aplicativo para detectar alterações na configuração. Com essa abordagem, você configura a Configuração do Aplicativo para enviar eventos de alteração de chave-valor para a Grade de Eventos do Azure. O aplicativo usa esses eventos para otimizar o número total de solicitações necessárias para manter a configuração atualizada. O aplicativo pode assinar esses eventos diretamente da Grade de Eventos ou por meio de um manipulador de eventos com suporte. Exemplos de manipuladores de eventos incluem um webhook, uma Azure Function ou um tópico do Azure Service Bus.

Neste tutorial, você:

  • Configure uma assinatura para enviar eventos de alteração de configuração do App Configuration para um tópico do Service Bus.
  • Configure seu aplicativo .NET para atualizar sua configuração em resposta às alterações na Configuração de Aplicativos.
  • Consuma a configuração mais recente em seu aplicativo.

Pré-requisitos

  • O aplicativo .NET que você atualiza ao concluir as etapas no Tutorial: Use a configuração dinâmica em um aplicativo .NET. Este tutorial mostra como usar a atualização por push para implementar atualizações de configuração dinâmicas em seu código. Ele se baseia no tutorial para usar a configuração dinâmica em um aplicativo .NET.
  • O pacote NuGet Microsoft.Extensions.Configuration.AzureAppConfiguration versão 5.0.0 ou posterior.
  • O Azure.Messaging.ServiceBus pacote NuGet.
  • Um editor de código, como o Visual Studio Code, que está disponível para as plataformas Windows, macOS e Linux.

Configurar assinatura e tópico do Barramento de Serviço

Este tutorial utiliza a integração do Service Bus no Event Grid para otimizar a detecção de mudanças de configuração. Se você não quiser que seu aplicativo pesquise continuamente a Configuração de Aplicativos para obter alterações, use essa integração. O SDK do Service Bus fornece uma API que você pode usar para registrar um handler de mensagens. Você pode usar esse manipulador para atualizar sua configuração quando forem detectadas alterações na Configuração de Aplicativos.

  1. Crie um namespace, um tópico e uma assinatura do Barramento de Serviço seguindo as etapas descritas no início rápido Use o portal do Azure para criar um tópico do Barramento de Serviço e assinaturas para o tópico.

  2. Use os comandos a seguir para configurar variáveis de ambiente. O código do aplicativo usa essas variáveis para registrar um manipulador de eventos para alterações de configuração.

    setx ServiceBusConnectionString "<Service-Bus-namespace-connection-string>"
setx ServiceBusTopic "<Service-Bus-topic-name>"
setx ServiceBusSubscription "<Service-Bus-subscription-name>"

    Depois de executar esses comandos, feche e reabra o Prompt de Comando para que as alterações entrem em vigor.

Configurar uma assinatura de evento

  1. Entre no portal do Azure e vá para o repositório de Configuração de Aplicativos no tutorial listado em Pré-requisitos.

  2. Selecione Eventos e selecione Assinatura de Evento.

    Captura de tela da página de visão geral no portal do Azure para um repositório de Configuração de Aplicativos. Eventos e Assinatura de Evento estão realçados.

  3. Na caixa de diálogo Criar Assinatura de Evento , insira as seguintes informações:

    • Em Detalhes da Assinatura do Evento, insira um nome para a assinatura do evento.
    • Em Detalhes do Tópico, insira um nome para o tópico do sistema.
    • Em Tipos de Evento, selecione Chave-valor modificado e Chave-valor excluído.

    Captura de tela da caixa de diálogo Criar Assinatura de Evento. A lista de filtros de tipo de evento e os nomes de assinatura e tópico são realçados.

  4. Em Detalhes do Ponto de Extremidade, faça as seguintes seleções:

    • Para Tipo de Ponto de Extremidade, selecione Tópico do Barramento de Serviço.
    • Ao lado do Ponto de Extremidade, selecione Configurar um ponto de extremidade.

    Captura de tela da caixa de diálogo Criar assinatura de evento. O tipo de ponto de extremidade Tópico do Barramento de Serviço e o link Configurar um ponto de extremidade estão destacados.

  5. Na caixa de diálogo Selecionar Tópico do Barramento de Serviço , selecione a assinatura e o grupo de recursos do namespace do Barramento de Serviço que você configurou na seção anterior. Selecione também o namespace e o tópico que você configurou e selecione Confirmar Seleção.

    Captura de tela da janela Selecionar Tópico do Barramento de Serviço. Todos os campos de entrada e o botão Confirmar Seleção estão realçados.

  6. Para criar a assinatura do evento, selecione Criar.

  7. Na página Eventos , acesse a guia Assinaturas de Eventos e verifique se a assinatura existe.

    Captura de tela da página de Eventos de uma loja de Configuração de Aplicativos. Eventos, Assinaturas de Eventos e uma assinatura na lista estão destacados.

Observação

Ao assinar as alterações de configuração, você pode usar um ou mais filtros para reduzir o número de eventos enviados ao seu aplicativo. Você pode configurar esses filtros como filtros de assinatura da Grade de Eventos ou filtros de assinatura do Barramento de Serviço. Por exemplo, você pode usar um filtro de assinatura para assinar apenas eventos para alterações em uma chave que começa com uma cadeia de caracteres específica.

Registrar um manipulador de eventos para recarregar dados da Configuração de Aplicativos

Vá para a pasta que contém o projeto de aplicativo .NET que você usou no tutorial listado em Pré-requisitos. Abra Program.cs e substitua o código existente pelo seguinte código:

using Azure.Messaging.EventGrid;
using Azure.Messaging.ServiceBus;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration.Extensions;
using System;
using System.Threading.Tasks;

namespace TestConsole
{
    class Program
    {
        private const string AppConfigurationConnectionStringEnvVarName = "AppConfigurationConnectionString";
        // An App Configuration connection string uses the following format:
        // Endpoint=https://{store-name}.azconfig.io;Id={id};Secret={secret}
        
        private const string ServiceBusConnectionStringEnvVarName = "ServiceBusConnectionString";
        // A Service Bus connection string uses the following format:
        // Endpoint=sb://{Service-Bus-name}.servicebus.windows.net/;SharedAccessKeyName={key-name};SharedAccessKey={key}
        
        private const string ServiceBusTopicEnvVarName = "ServiceBusTopic";
        private const string ServiceBusSubscriptionEnvVarName = "ServiceBusSubscription";

        private static IConfigurationRefresher _refresher = null;

        static async Task Main(string[] args)
        {
            string appConfigurationConnectionString = Environment.GetEnvironmentVariable(AppConfigurationConnectionStringEnvVarName);

            IConfiguration configuration = new ConfigurationBuilder()
                .AddAzureAppConfiguration(options =>
                {
                    options.Connect(appConfigurationConnectionString);
                    // Load the key-value that has the key "TestApp:Settings:Message" and no label.
                    options.Select("TestApp:Settings:Message");
                    // Reload the configuration when any selected key-values change.
                    options.ConfigureRefresh(refresh =>
                        refresh
                            .RegisterAll()
                            // Important: Reduce the polling frequency.
                            .SetRefreshInterval(TimeSpan.FromDays(1))  
                    );

                    _refresher = options.GetRefresher();
                }).Build();

            await RegisterRefreshEventHandler();
            var message = configuration["TestApp:Settings:Message"];
            Console.WriteLine($"Initial value: {configuration["TestApp:Settings:Message"]}");

            while (true)
            {
                await _refresher.TryRefreshAsync();

                if (configuration["TestApp:Settings:Message"] != message)
                {
                    Console.WriteLine($"New value: {configuration["TestApp:Settings:Message"]}");
                    message = configuration["TestApp:Settings:Message"];
                }

                await Task.Delay(TimeSpan.FromSeconds(1));
            }
        }

        private static async Task RegisterRefreshEventHandler()
        {
            string serviceBusConnectionString = Environment.GetEnvironmentVariable(ServiceBusConnectionStringEnvVarName);
            string serviceBusTopic = Environment.GetEnvironmentVariable(ServiceBusTopicEnvVarName);
            string serviceBusSubscription = Environment.GetEnvironmentVariable(ServiceBusSubscriptionEnvVarName); 
            ServiceBusClient serviceBusClient = new ServiceBusClient(serviceBusConnectionString);
            ServiceBusProcessor serviceBusProcessor = serviceBusClient.CreateProcessor(serviceBusTopic, serviceBusSubscription);

            serviceBusProcessor.ProcessMessageAsync += (processMessageEventArgs) =>
            {
                // Build an EventGridEvent instance from the notification message.
                EventGridEvent eventGridEvent = EventGridEvent.Parse(BinaryData.FromBytes(processMessageEventArgs.Message.Body));

                // Create a PushNotification instance from the Event Grid event.
                eventGridEvent.TryCreatePushNotification(out PushNotification pushNotification);

                // Prompt a configuration refresh based on the push notification.
                _refresher.ProcessPushNotification(pushNotification);

                return Task.CompletedTask;
            };

            serviceBusProcessor.ProcessErrorAsync += (exceptionargs) =>
            {
                Console.WriteLine($"{exceptionargs.Exception}");
                return Task.CompletedTask;
            };

            await serviceBusProcessor.StartProcessingAsync();
        }
    }
}

Nesse código, a chamada para ConfigureRefresh especifica que todos os valores-chave selecionados devem ser monitorados para alterações. Nesse caso, a única chave selecionada para monitoramento é TestApp:Settings:Message.

O parâmetro na SetRefreshInterval chamada especifica que nenhuma solicitação à Configuração de Aplicativo é feita antes de um dia passar desde a última verificação. No entanto, o ProcessPushNotification método redefine o intervalo de atualização para um atraso curto e aleatório. Essa redefinição faz com que chamadas futuras a RefreshAsync ou TryRefreshAsync revalidem os valores armazenados em cache na Configuração de Aplicativos e os atualizem, se necessário. Como resultado, quando ProcessPushNotification é chamado, seu aplicativo envia solicitações para a Configuração de Aplicativos dentro de alguns segundos. O resultado final é que seu aplicativo carrega novos valores de configuração logo após as alterações ocorrerem no repositório de Configuração de Aplicativos. Não há necessidade de consultar constantemente por atualizações.

Se o aplicativo perder uma notificação de alteração, ele ainda será informado sobre a atualização dentro de um dia, pois verifica se há alterações de configuração diariamente.

O atraso curto e aleatório usado para o intervalo de atualização será útil se muitas instâncias do seu aplicativo ou microsserviços usarem o modelo de push para se conectar ao mesmo repositório de Configuração de Aplicativos. Sem esse atraso, todas as instâncias do aplicativo podem enviar solicitações ao repositório de Configuração de Aplicativos simultaneamente, assim que receberem uma notificação de alteração. Esse comportamento pode fazer com que o App Configuration limite sua loja. Por padrão, o atraso do intervalo de atualização é definido como um número aleatório entre 0 e um máximo de 30 segundos. Você pode alterar o valor máximo usando o parâmetro maxDelay opcional do ProcessPushNotification método.

O ProcessPushNotification método usa um PushNotification objeto que contém informações sobre a alteração na Configuração de Aplicativos que disparou a notificação por push. Ter essas informações ajuda a garantir que todas as alterações de configuração até o evento de gatilho sejam carregadas na atualização de configuração subsequente. O SetDirty método pode ser usado para marcar o valor armazenado em cache de um valor-chave como sujo. Mas o SetDirty método não garante que a alteração que dispara uma notificação por push seja carregada em uma atualização de configuração imediata. Recomendamos que você use o ProcessPushNotification método em vez do SetDirty método para o modelo de push.

Compilar e executar o aplicativo localmente

  1. Configurar uma variável de ambiente chamada AppConfigurationConnectionString. Defina seu valor como a chave de acesso do repositório de Configuração de Aplicativos.

    setx AppConfigurationConnectionString "<App-Configuration-store-connection-string>"

    Depois de executar esse comando, feche e reabra o Prompt de Comando para que a alteração entre em vigor.

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

    dotnet build

  3. Depois que o build for concluído com êxito, execute o seguinte comando para executar o aplicativo localmente:

    dotnet run

    Captura de tela de uma janela do Prompt de Comando. A saída de um aplicativo de console inclui uma linha com o valor Inicial do texto: dados da Configuração de Aplicativos do Azure.

  4. Entre no portal do Azure e vá para o repositório de Configuração de Aplicativos no tutorial listado em Pré-requisitos.

  5. Selecione o Configuration Explorer e atualize o valor da seguinte chave:

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

  6. Aguarde alguns instantes para que o evento seja processado. A configuração atualizada aparece na saída do aplicativo.

    Captura de tela de uma janela do Prompt de Comando. A saída de um aplicativo de console inclui uma linha com o texto Novo valor: Dados da Configuração de Aplicativos do Azure – Atualizados.

Limpar os 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óxima etapa

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

Integração de identidade gerenciada

  • Last updated on