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

Este tutorial mostra como você pode habilitar atualizações de configuração dinâmica em um aplicativo ASP.NET Core. Baseia-se na aplicação web introduzida nos tutoriais de início rápido. A sua aplicação irá utilizar a biblioteca do fornecedor de Configuração de Aplicações para as suas capacidades internas de cache e atualização de configurações. Antes de continuar, primeiro conclua Criar uma aplicação ASP.NET Core com a Configuração da Aplicação.

Neste tutorial, irá aprender a:

Configure seu aplicativo para atualizar sua configuração em resposta a alterações em uma loja de configuração de aplicativos.
Injete a configuração mais recente em seu aplicativo.

Pré-requisitos

Conclua o quickstart: Crie uma aplicação ASP.NET Core com Configuração de Aplicação.

Recarregar dados da Configuração do Aplicativo

Abra Program.cs e atualize o AddAzureAppConfiguration método adicionado durante o início rápido. Você pode se conectar à Configuração do Aplicativo usando o ID da 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 em 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.
```
// 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 Select método é usado para carregar todos os valores-chave cujo nome da chave começa com TestApp: e que não têm rótulo. Você pode chamar o Select método mais de uma vez para carregar configurações com diferentes prefixos ou rótulos. Se partilhar uma App Configuration Store com várias aplicações, esta abordagem ajuda a carregar a configuração apenas relevante para a sua aplicação atual, em vez de carregar tudo a partir da sua loja.

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

Gorjeta

Você pode adicionar uma chamada ao refreshOptions.SetRefreshInterval método 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 precisar reduzir o número de solicitações feitas à sua App Configuration Store.

Adicione o middleware de Configuração de Aplicativo do Azure à coleção de serviços do seu 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. Permite que o seu aplicativo utilize o middleware de Configuração da Aplicação para atualizar automaticamente as suas definições de configuração.

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 seu aplicativo para usar o padrão de opções no ASP.NET Core durante o início rápido. Quando a configuração subjacente da sua aplicação é atualizada a partir de App Configuration, o seu objeto com tipagem forte Settings obtido via IOptionsSnapshot<T> é atualizado automaticamente. Observe que você não deve usar a IOptions<T> atualização de configuração dinâmica se for desejada porque ela não lê os dados de configuração depois que o aplicativo for iniciado.

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

A atualização da configuração é acionada pelas solicitações de entrada para seu aplicativo Web. Nenhuma atualização ocorrerá se seu aplicativo estiver ocioso. Quando seu aplicativo está ativo, o middleware de Configuração do Aplicativo monitora todas as chaves registradas para atualização na ConfigureRefresh chamada. O middleware é acionado a cada solicitação de entrada no seu 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 do Aplicativo para deteção de alterações falhar, seu aplicativo continuará a usar a configuração em cache. Novas tentativas de verificar alterações serão feitas periodicamente enquanto houver novas solicitações de entrada para seu aplicativo.
A atualização de configuração acontece de forma assíncrona para o processamento das solicitações de entrada do seu aplicativo. Ele não bloqueará ou retardará a solicitação de entrada que disparou a atualização. A solicitação que disparou a atualização pode não obter os valores de configuração atualizados, mas as solicitações posteriores obterão novos valores de configuração.
Para garantir que o middleware seja acionado, chame o app.UseAzureAppConfiguration() método o mais cedo possível no pipeline de solicitações para que outro middleware não o ignore em seu aplicativo.

Crie e execute 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 compilação for concluída com êxito, execute o seguinte comando para executar o aplicativo Web localmente:
```
    dotnet run
```
Abra uma janela do navegador dotnet run e vá para o endereço URL mostrado na saída.
Inicie sessão no portal do Azure. Selecione Todos os recursos e selecione a loja de configuração de aplicativos que você criou no início rápido.

Selecione Configuration explorer e atualize os valores das seguintes chaves.

Chave	valor
TestApp:Configurações:BackgroundColor	verde
TestApp:Configurações:FontColor	cinza claro
TestApp:Configurações:Mensagem	Dados da Configuração de Aplicativos do Azure - agora com atualizações em tempo real!

Atualize o navegador algumas vezes. Quando o intervalo de atualização expira após 30 segundos, a página é exibida com conteúdo 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.

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

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

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

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

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 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 ILogger é o método preferido em aplicativos ASP.NET e é priorizado como a fonte de registro se uma instância de ILoggerFactory estiver presente. No entanto, se ILoggerFactory não estiver disponível, os logs podem, alternativamente, ser habilitados e configurados por meio das instruções para aplicativos .NET Core. Para mais informações, consulte logging no .NET Core e no ASP.NET Core.

Nota

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

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 Web ASP.NET Core para atualizar dinamicamente as definições de configuração da Configuração do aplicativo. Para saber como usar uma identidade gerenciada pelo Azure para simplificar o acesso à Configuração do Aplicativo, continue para o próximo tutorial.

Acessar a configuração do aplicativo usando identidade gerenciada

Comentários

Esta página foi útil?

Last updated on 2025-11-21