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

Artigo
02/20/2024

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, irá 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 subscrição do Azure, crie uma conta gratuita do Azure 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.

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, uma chave dentro da sua App Configuration Store é registrada para monitoramento de ConfigureRefresh alterações. O Register método tem um parâmetro refreshAll booleano opcional que pode ser usado para indicar se todos os valores de configuração devem ser atualizados se a chave registrada for alterada. Neste exemplo, apenas a chave TestApp:Settings:Message será atualizada. O SetCacheExpiration 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, você liga TryRefreshAsync sempre que pressiona a tecla Enter. Mesmo se a chamada TryRefreshAsync falhar por qualquer motivo, seu aplicativo continuará a usar a configuração em cache. Outra tentativa é feita quando o tempo de expiração do cache configurado já passou e a chamada é acionada pela atividade do TryRefreshAsync aplicativo novamente. A chamada TryRefreshAsync é um no-op antes que o tempo de expiração do cache configurado transcorra, 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.

Registre os serviços de Configuração de Aplicativo necessários invocando AddAzureAppConfiguration o .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 sua configuração resolvendo uma instância de sua coleção de IConfigurationRefresherProvider serviços e invocando TryRefreshAsync cada uma de suas atualizações.

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 ConnectionString e defina-a como a chave de acesso à sua loja de configuração de aplicativos. 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 ConnectionString "connection-string-of-your-app-configuration-store"
```
Se você usar o Windows PowerShell, execute o seguinte comando:
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
Se você usa macOS ou Linux, execute o seguinte comando:
```
 export ConnectionString='connection-string-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 do 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:

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

Nota

Como o tempo de expiração do cache foi definido como 10 segundos usando o SetCacheExpiration 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.

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

Registos 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. Caso contrário, você pode habilitar o log usando as instruções para registrar 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	Description
Verboso	Os logs incluem a chave e o rótulo dos valores-chave que seu aplicativo monitora para alterações da sua loja de configuração de aplicativos. 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.
Informativo	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.
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 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'

Nota

O registro em log estará disponível se você usar 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

Clean up resources (Limpar 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

Partilhar via