Tutorial: Usar a configuração dinâmica em um serviço em segundo plano do .NET

Os dados da Configuração do Aplicativo podem ser carregados como Configurações do Aplicativo em um aplicativo .NET. Para obter mais informações, consulte o guia de início rápido. No entanto, como é projetado pelo .NET, as Configurações do aplicativo só podem ser atualizadas após a reinicialização do aplicativo. O provedor .NET de Configuração de Aplicativo é uma biblioteca .NET Standard. Ele suporta cache e atualização de configuração dinamicamente sem reinicialização do aplicativo. Este tutorial mostra como você pode implementar atualizações de configuração dinâmica em um serviço em segundo plano do .NET.

Neste tutorial, irá aprender a:

Configure seu serviço em segundo plano .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 serviço em segundo plano.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie um gratuitamente.
Uma loja de configuração de aplicativos, conforme mostrado no tutorial para criar uma loja.
.NET SDK 6.0 ou posterior - também disponível no Azure Cloud Shell.

Adicionar um valor-chave

Adicione o seguinte valor-chave à loja de Configuração de Aplicativos e deixe Rótulo e Tipo de Conteúdo com seus valores padrão. Para obter mais informações sobre como adicionar valores-chave a uma loja usando o portal do Azure ou a CLI, vá para Criar um valor-chave.

Chave	valor
TestApp:Configurações:Mensagem	Dados da Configuração do Aplicativo do Azure

Criar um serviço em segundo plano do .NET

Você usa a interface de linha de comando (CLI) do .NET para criar um novo projeto de aplicativo .NET. A vantagem de usar a CLI do .NET sobre o Visual Studio é que ela está disponível nas plataformas Windows, macOS e Linux. Como alternativa, use as ferramentas pré-instaladas disponíveis no Azure Cloud Shell.

Crie uma pasta nova para o projeto.
Na nova pasta, execute o seguinte comando para criar um novo projeto de serviço em segundo plano do .NET:
```
dotnet new worker
```

Recarregar dados da Configuração do Aplicativo

Adicione referências ao Microsoft.Extensions.Configuration.AzureAppConfiguration pacote NuGet executando o seguinte comando:
```
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
```
Execute o seguinte comando para restaurar pacotes para o seu projeto:
```
dotnet restore
```

Abra Program.cs e adicione as seguintes instruções:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

Conecte-se à Configuração do Aplicativo usando a ID do Microsoft Entra (recomendado) ou uma cadeia de conexão.

Microsoft Entra ID (recomendado)
Cadeia de ligação

Você usa o DefaultAzureCredential para autenticar no seu armazenamento de configuração de aplicativos. Siga as instruções para atribuir à sua credencial a função de Leitor de Dados de Configuração do Aplicativo. Certifique-se de dar tempo suficiente para que a permissão se propague antes de executar seu aplicativo.

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());
        // Load all keys that start with `TestApp:` and have no label.
        .Select("TestApp:*")
        // Reload configuration if any selected key-values have changed.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.RegisterAll();
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

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

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

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
        // Load all keys that start with `TestApp:` and have no label.
        .Select("TestApp:*")
        // Reload configuration if any selected key-values have changed.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.RegisterAll();
        });

    // Register the refresher so that the Worker service can consume it through DI
    builder.Services.AddSingleton(options.GetRefresher());
});

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

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.

Sugestão

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.

Abra Worker.cs. Injete IConfiguration e IConfigurationRefresher no serviço Worker e registe os dados de configuração da Configuração da Aplicação.
```
public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;
    private readonly IConfiguration _configuration;
    private readonly IConfigurationRefresher _refresher;

    public Worker(ILogger<Worker> logger, IConfiguration configuration, IConfigurationRefresher refresher)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
        _refresher = refresher ?? throw new ArgumentNullException(nameof(refresher));
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Intentionally not await TryRefreshAsync to avoid blocking the execution.
            _refresher.TryRefreshAsync(stoppingToken);

            if (_logger.IsEnabled(LogLevel.Information))
            {
                _logger.LogInformation(_configuration["TestApp:Settings:Message"] ?? "No data.");
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}
```
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ê pode 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ê chama TryRefreshAsync toda vez que o serviço em segundo plano é executado. Observe que, mesmo se a chamada TryRefreshAsync falhar por qualquer motivo, seu aplicativo continuará a usar a configuração em cache. Outra tentativa será feita quando o intervalo de atualização configurado tiver passado e a chamada for acionada pela atividade do TryRefreshAsync aplicativo novamente. 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.

Crie e execute o aplicativo localmente

Defina uma variável de ambiente.
- Microsoft Entra ID (recomendado)
- Cadeia de ligação
Defina a variável de ambiente chamada Ponto de Extremidade como 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>'
```
Defina a variável de ambiente chamada ConnectionString como a cadeia de conexão somente leitura da sua loja de Configuração de Aplicativos encontrada em Chaves de acesso 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 ConnectionString "<connection-string-of-your-app-configuration-store>"
```
Se você usar o 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.
```
dotnet build
```
Depois que a compilação for concluída com êxito, execute o seguinte comando para executar o aplicativo localmente.
```
dotnet run
```
Você deve ver as seguintes saídas no console.
No portal do Azure, navegue até o Gerenciador de configurações do seu repositório de configuração de aplicativos e atualize o valor da chave a seguir.

Chave valor

TestApp:Configurações:Mensagem Dados da Configuração do Aplicativo do Azure - Atualizado
Aguarde alguns instantes até que a janela de intervalo de atualização passe. Você verá as saídas do console alteradas.

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

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 serviço em segundo plano do .NET para atualizar dinamicamente as definições de configuração da Configuração do aplicativo. Para saber como habilitar a configuração dinâmica em um aplicativo Web ASP.NET, continue para o próximo tutorial:

Habilitar a configuração dinâmica em ASP.NET aplicativos Web

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

Feedback

Esta página foi útil?

Last updated on 2025-04-21