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

2025-04-21

A biblioteca de clientes .NET da Configuração de Aplicativo dá suporte à atualização da configuração sob demanda sem fazer com que um aplicativo seja reiniciado. Um aplicativo pode ser configurado para detectar alterações na Configuração de Aplicativos usando uma das abordagens a seguir ou ambas.

Modelo de sondagem: este é o comportamento padrão que usa a sondagem para detectar alterações na configuração. Depois que o intervalo de atualização de uma configuração decorrido, a próxima chamada para TryRefreshAsync ou RefreshAsync envia uma solicitação ao servidor para verificar se a configuração foi alterada e efetua pull da configuração atualizada, se necessário.
Modo de push: usa eventos da Configuração de Aplicativos para detectar alterações na configuração. Depois que a Configuração de Aplicativo é configurada para enviar eventos de alteração de valor de chave para a Grade de Eventos do Azure, o aplicativo pode usar esses eventos para otimizar o número total de solicitações necessárias para manter a configuração atualizada. Os aplicativos podem optar por se inscrever diretamente na Grade de Eventos ou por meio de um dos manipuladores de eventos com suporte, como um webhook, uma função do Azure ou um tópico do Barramento de Serviço.

Este tutorial mostra como você pode implementar atualizações de configuração dinâmica no código usando a atualização por push. Ele se baseia no aplicativo introduzido no tutorial. Antes de continuar, conclua o Tutorial: use a configuração dinâmica em um aplicativo .NET primeiro.

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:

Configurar uma assinatura para enviar eventos de alteração de configuração da Configuração de Aplicativos para um tópico do Barramento de Serviço
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

Tutorial: Usar a configuração dinâmica em um aplicativo .NET
Pacote NuGet Microsoft.Extensions.Configuration.AzureAppConfiguration versão 5.0.0 ou posterior

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

Este tutorial usa a integração de Barramento de Serviço à Grade de Eventos para simplificar a detecção de alterações de configuração para aplicativos que não desejam sondar continuamente a Configuração de Aplicativos do Azure em busca de alterações. O SDK do Barramento de Serviço do Azure fornece uma API para registrar um manipulador de mensagens que pode ser usado para atualizar a configuração quando alterações são detectadas na Configuração de Aplicativos. Siga as etapas no Início Rápido: Usar o portal do Azure para criar um tópico e uma assinatura do Barramento de Serviço para criar um namespace, um tópico e uma assinatura do Barramento de Serviço.

Depois que os recursos forem criados, adicione as variáveis de ambiente a seguir. Elas serão usadas para registrar um manipulador de eventos para alterações de configuração no código do aplicativo.

Chave	Valor
ServiceBusConnectionString	Cadeia de conexão para o namespace do Barramento de Serviço
ServiceBusTopic	Nome do tópico do Barramento de Serviço
Assinatura do ServiceBusSubscription	Nome da assinatura do Barramento de Serviço

Configurar a assinatura do Evento

Abra o recurso da Configuração de Aplicativos no portal do Azure e clique em + Event Subscription no painel Events.
Insira um nome para o Event Subscription e o System Topic.
Selecione o Endpoint Type como Service Bus Topic, escolha o tópico do Barramento de Serviço e clique em Confirm Selection.
Clique em Create para criar a assinatura do evento.
Clique no Event Subscriptions no painel Events para confirmar que a assinatura foi criada com êxito.

Observação

Ao assinar alterações de configuração, um ou mais filtros podem ser usados para reduzir o número de eventos enviados ao aplicativo. Eles podem ser configurados como Filtros de assinatura da Grade de Eventos ou Filtros de assinatura do Barramento de Serviço. Por exemplo, um filtro de assinatura pode ser usado para assinar somente eventos de alterações em uma chave que começa com uma cadeia de caracteres específica.

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

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

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";
        // e.g. Endpoint=https://{store_name}.azconfig.io;Id={id};Secret={secret}
        
        private const string ServiceBusConnectionStringEnvVarName = "ServiceBusConnectionString";
        // e.g. 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 with key "TestApp:Settings:Message" and no label
                    options.Select("TestApp:Settings:Message");
                    // Reload configuration if any selected key-values have changed.
                    options.ConfigureRefresh(refresh =>
                        refresh
                            .RegisterAll()
                            // Important: Reduce poll 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 EventGridEvent from notification message
                EventGridEvent eventGridEvent = EventGridEvent.Parse(BinaryData.FromBytes(processMessageEventArgs.Message.Body));

                // Create PushNotification from eventGridEvent
                eventGridEvent.TryCreatePushNotification(out PushNotification pushNotification);

                // Prompt Configuration Refresh based on the PushNotification
                _refresher.ProcessPushNotification(pushNotification);

                return Task.CompletedTask;
            };

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

            await serviceBusProcessor.StartProcessingAsync();
        }
    }
}

O ProcessPushNotification método redefine o intervalo de atualização para um pequeno atraso aleatório. Isso faz com que futuras chamadas a RefreshAsync ou TryRefreshAsync revalidem os valores em cache na Configuração de Aplicativos e os atualizem conforme necessário. Neste exemplo, você se registra para monitorar as alterações em todos os valores de chave selecionados (TestApp:Settings:Message) com um intervalo de atualização de um dia. Isso significa que nenhuma solicitação para a Configuração de Aplicativos será feita antes de um dia ter passado desde a última verificação. Ao chamar ProcessPushNotification seu aplicativo, enviará solicitações à Configuração de Aplicativos nos próximos segundos. Seu aplicativo carregará os novos valores de configuração logo após as App Configuration alterações ocorrerem no repositório sem a necessidade de sondar constantemente as atualizações. Caso seu aplicativo perca a notificação de alteração por qualquer motivo, ele ainda verificará se há alterações de configuração uma vez por dia.

O pequeno atraso aleatório para o intervalo de atualização é útil se você tiver muitas instâncias do seu aplicativo ou microsserviços conectados ao mesmo armazenamento da Configuração de Aplicativos com o modelo push. 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. Isso pode fazer com que o Serviço de Configuração de Aplicativos limite sua loja. O atraso do intervalo de atualização é definido como um número aleatório entre 0 e um máximo de 30 segundos por padrão, mas você pode alterar o valor máximo por meio do parâmetro maxDelay opcional para o ProcessPushNotification método.

O ProcessPushNotification método usa um PushNotification objeto que contém informações sobre qual alteração na Configuração de Aplicativo disparou a notificação por push. Isso ajuda a garantir que todas as alterações de configuração até o evento de gatilho sejam carregadas na atualização de configuração a seguir. O método SetDirty não garante que a alteração que dispara a notificação por push seja carregada durante uma atualização imediata de configuração. Se você estiver usando o SetDirty método para o modelo de push, recomendamos usar o ProcessPushNotification método.

Compilar e executar o aplicativo localmente

Defina uma variável de ambiente chamada AppConfigurationConnectionString e defina-a como a chave de acesso para o repositório de Configuração de Aplicativos.
Para compilar e executar o aplicativo localmente usando o prompt de comando Windows, execute o seguinte comando e reinicie o prompt de comando para permitir que a alteração entre em vigor:
```
setx AppConfigurationConnectionString "<connection-string-of-your-app-configuration-store>"
```
Se você usa o Windows PowerShell, execute o comando a seguir:
```
$Env:AppConfigurationConnectionString = "<connection-string-of-your-app-configuration-store>"
```
Se você usar o macOS, execute o seguinte comando:
```
export AppConfigurationConnectionString='<connection-string-of-your-app-configuration-store>'
```
Se você usar o Linux, execute o seguinte comando:
```
export AppConfigurationConnectionString='<connection-string-of-your-app-configuration-store>'
```
Execute o seguinte comando para compilar o aplicativo de console:
```
dotnet build
```
Depois que a construção for concluída com êxito, execute o seguinte comando para executar o aplicativo localmente:
```
dotnet run
```
Entre no portal do Azure. Selecione Todos os recursos e selecione a instância do repositório de Configuração de Aplicativos que você criou no início rápido.
Selecione o Configuration Explorer e atualize os valores das seguintes chaves:

Chave Valor

TestApp:Configurações:Mensagem Dados da Configuração de Aplicativos do Azure – Atualizados
Aguarde alguns instantes para permitir que o evento seja processado. Você verá a configuração atualizada.

Chave	Valor
TestApp:Configurações:Mensagem	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.

Entre no portal do Azure e selecione Grupos de recursos.
Na caixa Filtrar por nome..., digite o nome do seu grupo de recursos.
Na lista de resultados, selecione o nome do grupo de recursos para conferir uma visão geral.
Selecione Excluir grupo de recursos.
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 .NET 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.

Integração de identidade gerenciada

Compartilhar via