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

2025-04-21

A biblioteca de provedores .NET da Configuração de Aplicativo dá suporte à atualização da configuração sob demanda sem fazer com que um aplicativo seja reiniciado. Este tutorial mostra como você pode implementar atualizações de configuração dinâmicas em seu código. Ele se baseia no aplicativo introduzido no início rápido. Você deve concluir a criação de um aplicativo .NET com a Configuração de Aplicativos antes de continuar.

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:

Configure seu aplicativo .NET para atualizar sua configuração em resposta a alterações em um repositório de Configuração de Aplicativos.
Consuma a configuração mais recente em seu aplicativo.

Pré-requisitos

Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

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

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

Abra Program.cs e atualize o arquivo com o código a seguir. Você pode se conectar à Configuração de Aplicativos usando o Microsoft Entra ID (recomendado) ou uma cadeia de conexão. O trecho de código a seguir demonstra o uso do Microsoft Entra ID.

Use a autenticação DefaultAzureCredential no repositório da Configuração de Aplicativos. Ao concluir o início rápido listado nos pré-requisitos, você já atribuiu sua credencial à função Leitor de Dados da Configuração de Aplicativos.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(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!");

}

Dentro do ConfigureRefresh método, você chama o RegisterAll método para instruir o provedor de Configuração de Aplicativos a recarregar toda a configuração sempre que detectar uma alteração em qualquer um dos valores de chave selecionados (nesse caso, apenas TestApp:Settings:Message). Para obter mais informações sobre como monitorar alterações de configuração, consulte As práticas recomendadas para atualização de configuração.

O método SetRefreshInterval 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ê chama TryRefreshAsync sempre que pressiona a tecla Enter. Mesmo que a chamada TryRefreshAsync falhe por algum motivo, seu aplicativo continuará usando a configuração armazenada em cache. Outra tentativa será feita quando o intervalo de atualização configurado tiver passado e a chamada TryRefreshAsync for disparada pela atividade do aplicativo. A chamada de TryRefreshAsync é uma não operação antes do término do intervalo de atualização configurado, portanto, seu impacto no desempenho é mínimo, mesmo que seja chamado 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 de IConfigurationRefresher para invocar TryRefreshAsync. Como alternativa, se você estiver usando a injeção de dependência para resolver seus serviços, poderá referenciar as etapas a seguir.

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

Adicione o seguinte código em Program.cs.
```
// Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();
```

Atualize sua configuração resolvendo uma instância de 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

Defina a variável de ambiente chamada Ponto de Extremidade para o ponto de extremidade do repositório de Configuração de Aplicativos encontrado na Visão Geral do seu repositório no portal do Azure.

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 Endpoint "<endpoint-of-your-app-configuration-store>"
```
Se você usar o PowerShell, execute o seguinte comando:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Se você usa macOS ou Linux, execute o comando a seguir:
```
export Endpoint='<endpoint-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
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

Como o intervalo de atualização foi definido como 10 segundos usando o SetRefreshInterval método ao especificar a configuração para a operação de atualização, o valor da configuração só será atualizado se pelo menos 10 segundos tiver decorrido desde a última atualização para essa configuração.

Chave	Valor
TestApp:Configurações:Mensagem	Dados da Configuração de Aplicativos do Azure – Atualizados

Registro 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 sobre log e monitoramento no ASP.NET Core. Caso contrário, você poderá 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.

Nível de evento	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 evento de nível Verbose especificando o parâmetro EventLevel.Verbose, como mostrado 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 Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh categoria.

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 é 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'

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 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