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

A biblioteca do provedor .NET de Configuração do Aplicativo oferece 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âmica em seu código. Ele se baseia no aplicativo introduzido no início rápido. Você deve concluir Criar um aplicativo .NET com a Configuração do Aplicativo antes de continuar.

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

Neste tutorial, você aprenderá a:

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

Pré-requisitos

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

Conclua o início rápido Crie um aplicativo .NET com a Configuração do Aplicativo.

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

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

Você usa o DefaultAzureCredential para autenticar na sua loja de 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 de Configuração do Aplicativo.

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 do Aplicativo a recarregar toda a configuração sempre que detetar uma alteração em qualquer um dos valores-chave selecionados (neste caso, apenas TestApp:Settings:Message). Para obter mais informações sobre como monitorar alterações de configuração, consulte Práticas recomendadas para atualização de configuração.

O SetRefreshInterval método especifica o tempo mínimo que deve decorrer antes que uma nova solicitação seja feita à Configuração do Aplicativo para verificar se há alterações na configuração. Neste exemplo, você substitui o tempo de expiração padrão de 30 segundos, especificando um tempo de 10 segundos para fins de demonstração.

Chamar o ConfigureRefresh método sozinho não fará com que a configuração seja atualizada automaticamente. Você chama o TryRefreshAsync método da interface IConfigurationRefresher para disparar uma atualização. Esse design é para evitar solicitações enviadas para a Configuração do aplicativo mesmo quando seu aplicativo está ocioso. Você vai querer incluir a TryRefreshAsync chamada onde você considera seu aplicativo ativo. Por exemplo, pode ser quando você processa uma mensagem de entrada, um pedido ou uma iteração de uma tarefa complexa. Ele também pode estar em um temporizador se seu aplicativo estiver ativo o tempo todo. Neste exemplo, tu chamas TryRefreshAsync sempre que premir a tecla Enter. Mesmo se a chamada TryRefreshAsync falhar por qualquer motivo, seu aplicativo continuará a usar a configuração em cache. Faz-se outra tentativa quando o intervalo de atualização configurado tiver passado e a chamada for acionada novamente pela atividade da aplicação TryRefreshAsync. A chamada TryRefreshAsync é um no-op antes do intervalo de atualização configurado passar, 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á consultar as etapas a seguir.

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

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

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

Atualize a sua configuração obtendo uma instância de IConfigurationRefresherProvider da sua coleção de serviços e invocando TryRefreshAsync em cada um dos 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();
        }
    }
}

Crie e execute o aplicativo localmente

Defina uma variável de ambiente chamada Ponto de Extremidade para o ponto de extremidade da sua loja de Configuração de Aplicativo encontrado na Visão geral da sua loja no portal do Azure.

Se você usar o prompt de comando do Windows, execute o seguinte comando 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 seguinte comando:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Execute o seguinte comando para criar o aplicativo de console:
```
 dotnet build
```
Depois que a compilação for concluída com êxito, execute o seguinte comando para executar o aplicativo localmente:
```
 dotnet run
```
Inicie sessão no portal Azure. Selecione Todos os recursos e selecione a instância da App Configuration Store que você criou no início rápido.
Selecione Configuration Explorer e atualize os valores das seguintes chaves:

Chave Valor

TestApp:Configurações:Mensagem Dados da Configuração do Aplicativo do Azure - Atualizado
Pressione a tecla Enter para acionar uma atualização e imprimir o valor atualizado na janela Prompt de Comando ou 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 para a definição de configuração só será atualizado se pelo menos 10 segundos tiverem decorrido desde a última atualização para essa configuração.

Chave	Valor
TestApp:Configurações:Mensagem	Dados da Configuração do Aplicativo do Azure - Atualizado

Registo e monitorização

Os logs são enviados após a atualização da configuração e contêm informações detalhadas sobre os valores-chave recuperados da sua loja de configuração de aplicativos e as alterações de configuração feitas em seu aplicativo. Se você tiver um aplicativo ASP.NET Core, consulte estas instruções para Registro em log e monitoramento no ASP.NET Core. Alternativamente, pode ativar o registo seguindo as instruções para ativar o registo com o SDK do Azure.

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

Nível do Evento	Descrição
Verbose	Os registos incluem a chave e o rótulo dos valores-chave que a sua aplicação monitoriza para alterações na sua loja de configuração da aplicação. As informações também incluem se o valor-chave foi alterado em comparação com o que seu aplicativo já carregou. Habilite os logs nesse nível para solucionar problemas do seu aplicativo se uma alteração de configuração não ocorrer conforme o esperado.
Informação	Os logs incluem as chaves das definições de configuração atualizadas durante uma atualização de configuração. Os valores das definições de configuração são omitidos do log para evitar o vazamento de dados confidenciais. Você pode monitorar logs nesse nível para garantir que seu aplicativo capte as alterações de configuração esperadas.
Advertência	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 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 Verbose evento especificando o EventLevel.Verbose parâmetro, como feito no exemplo a seguir. Estas instruções também se aplicam a todos os outros níveis de evento. Este exemplo também habilita logs apenas 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 log é Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, que aparece antes de cada log. Aqui estão alguns exemplos de logs 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 registo estará disponível se usares a versão 6.0.0 ou posterior de qualquer um dos seguintes pacotes.

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

Limpeza de recursos

Se não quiser continuar a utilizar os recursos criados neste artigo, elimine o grupo de recursos que criou aqui para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são excluídos permanentemente. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. Se você criou os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que deseja manter, exclua cada recurso individualmente de seu respetivo painel em vez de excluir o grupo de recursos.

Entre no portal do Azure e selecione Grupos de recursos.
Na caixa Filtrar por nome, introduza o nome do seu grupo de recursos.
Na lista de resultados, selecione o nome do grupo de recursos para ver uma visão geral.
Selecione Eliminar grupo de recursos.
É-lhe pedido que confirme a eliminação do grupo de recursos. Insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

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

Próximos passos

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

Integração de identidade gerenciada

Comentários

Esta página foi útil?

Last updated on 2025-04-17