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

2025-04-24

Este tutorial mostra como habilitar atualizações de configuração dinâmicas em um aplicativo ASP.NET Core. Ele se baseia no aplicativo Web introduzido nos Inícios Rápidos. Seu aplicativo aproveitará a biblioteca de provedores da Configuração de Aplicativos para as funcionalidades internas de cache e atualização de configuração. Antes de continuar, conclua Criar um aplicativo ASP.NET Core com a Configuração de Aplicativo primeiro.

Neste tutorial, você aprenderá como:

Configurar seu aplicativo para atualizar a configuração em resposta às alterações em um repositório da Configuração de Aplicativos.
Injetar a configuração mais recente no aplicativo.

Pré-requisitos

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

Recarregar os dados da Configuração de Aplicativo

Abra Program.cs e atualize o método AddAzureAppConfiguration que você adicionou durante o início rápido. 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.

Você usa o DefaultAzureCredential para autenticar no seu repositório 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 da Configuração de Aplicativos.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
           // Load all keys that start with `TestApp:` and have no label.
           .Select("TestApp:*", LabelFilter.Null)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});
```
O método Select é usado para carregar todos os valores de chave cujo nome de chave começa com TestApp: e que não têm rótulo. Você pode chamar o método Select mais de uma vez para carregar configurações com diferentes prefixos ou rótulos. Se você compartilha um repositório de Configuração de Aplicativos com vários aplicativos, essa abordagem ajuda a carregar apenas a configuração relevante para o aplicativo atual em vez de carregar tudo de seu repositório.

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 (aqueles que começam com o TestApp: e sem rótulo). Para obter mais informações sobre como monitorar alterações de configuração, consulte As práticas recomendadas para atualização de configuração.

Dica

Você pode adicionar uma chamada para o método refreshOptions.SetRefreshInterval para especificar o tempo mínimo entre as atualizações de configuração. Neste exemplo, você usa o valor padrão de 30 segundos. Ajuste para um valor mais alto se você precisar reduzir o número de solicitações feitas ao repositório de Configuração de Aplicativos.

Adicione o middleware da Configuração de Aplicativos do Azure à coleção de serviços do aplicativo.

Atualize Program.cs com o código a seguir.

// Existing code in Program.cs
// ... ...

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Chame o método UseAzureAppConfiguration . Isso permite que o aplicativo use o middleware da Configuração de Aplicativos para atualizar a configuração automaticamente.

Atualize Program.cs com o código a seguir.

// Existing code in Program.cs
// ... ...

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

// The rest of existing code in program.cs
// ... ...

Você configurou o aplicativo para usar o padrão de opções em ASP.NET Core durante o início rápido. Quando a configuração subjacente do aplicativo for atualizada da Configuração de Aplicativos, o objeto Settings fortemente tipado obtido por meio de IOptionsSnapshot<T> será atualizado automaticamente. Observe que você não deve usar o IOptions<T> se a atualização de configuração dinâmica for desejada porque ela não lê os dados de configuração depois que o aplicativo é iniciado.

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

A atualização de configuração é disparada pelas solicitações de entrada ao aplicativo Web. Nenhuma atualização ocorrerá se o aplicativo estiver ocioso. Quando o seu aplicativo está ativo, o middleware da Configuração de Aplicativos monitora todas as chaves que você registrou para atualizar na chamada ConfigureRefresh. O middleware é acionado a cada solicitação de entrada para o aplicativo. No entanto, o middleware só enviará solicitações para verificar o valor na Configuração do Aplicativo quando o intervalo de atualização definido tiver passado.

Se uma solicitação à Configuração de Aplicativos para detecção de alterações falhar, o aplicativo continuará a usar a configuração armazenada em cache. Novas tentativas de verificar se há alterações serão feitas periodicamente enquanto houver novas solicitações de entrada no aplicativo.
A atualização de configuração ocorre de forma assíncrona para o processamento das solicitações de entrada do aplicativo. Ela não bloqueará nem reduzirá a velocidade da solicitação de entrada que disparou a atualização. Talvez a solicitação que disparou a atualização não receba os valores de configuração atualizados, mas solicitações posteriores receberão.
Para assegurar que o middleware seja acionado, chame o método app.UseAzureAppConfiguration() tão cedo quanto apropriado no pipeline de solicitações, para evitar que outro middleware o ignore em seu aplicativo.

Compilar e executar o aplicativo localmente

Para criar o aplicativo usando a CLI do .NET, execute o seguinte comando no shell de comando:
```
    dotnet build
```
Depois que a construção for concluída com êxito, execute o seguinte comando para executar o aplicativo Web localmente:
```
    dotnet run
```
Abra uma janela do navegador e vá para a URL mostrada na saída dotnet run.
Entre no portal do Azure. Escolha Todos os recursos e escolha o repositório de Configuração de Aplicativos que você criou no início rápido.

Selecione Explorador de Configurações e atualize os valores das seguintes chaves.

Chave	Valor
TestApp:Configurações:Cor de Fundo	verde
TestApp:Configurações:CorDaFonte	cinza claro
TestApp:Configurações:Mensagem	Dados da Configuração de Aplicativo do Azure – agora com atualizações dinâmicas!

Atualize o navegador algumas vezes. Quando o intervalo de atualização é decorrido após 30 segundos, a página é exibida com o conteúdo atualizado.

Registro de logs 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.

Um padrão ILoggerFactory é automaticamente adicionado quando services.AddAzureAppConfiguration() é invocado. O provedor de Configuração de Aplicativos usa este ILoggerFactory para criar uma instância de ILogger, que gera esses logs. O ASP.NET Core usa ILogger para registro em log por padrão, então você não precisa fazer alterações adicionais no código para habilitar o registro no provedor de Configuração de Aplicativos.

Os logs são emitidos em diferentes níveis de log. O nível padrão é Information.

Nível de log	Descrição
Depuração	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.
Informações	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 no nível do registro Debug adicionando o exemplo a seguir ao seu arquivo appsettings.json. Esse exemplo também se aplica a todos os outros níveis de log.

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

A categoria de registro é Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, que aparece antes de cada registro. Aqui estão alguns exemplos de logs em cada nível de log:

dbug: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    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'

O uso de ILogger é o método preferido em aplicativos ASP.NET e é priorizado como fonte de registro se uma instância de ILoggerFactory estiver presente. No entanto, se ILoggerFactory não estiver disponível, os registros podem ser habilitados e configurados alternativamente por meio das instruções para aplicativos.NET Core. Para obter mais informações, consulte Registro em log no .NET Core e no ASP.NET Core.

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 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. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. 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 Web ASP.NET Core 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.

Acessar a Configuração de Aplicativos usando identidade gerenciada

Compartilhar via