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

2025-04-21

Os dados da Configuração de Aplicativos podem ser carregados como Configurações de Aplicativo em um aplicativo .NET. Para obter mais informações, confira o Início Rápido. Porém, como foi projetado pelo .NET, as Configurações do Aplicativo só podem ser atualizadas de reinicializar o aplicativo. O provedor .NET da Configuração de Aplicativos é uma biblioteca .NET Standard. Ele dá suporte ao cache e à atualização da configuração dinamicamente, sem reinicialização do aplicativo. Este tutorial mostra como você pode implementar as atualizações de configuração dinâmicas em um serviço em segundo plano do .NET.

Neste tutorial, você aprenderá a:

Configure seu serviço em segundo plano do .NET para atualizar sua configuração em resposta a alterações na Central de Configurações de Aplicativos.
Consuma a configuração mais recente no seu serviço em segundo plano.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente.
Um repositório de Configuração de Aplicativos. Criar um repositório.
SDK .NET 6.0 ou posterior - também disponível no Azure Cloud Shell.

Adicionar um valor-chave

Adicione o valor-chave a seguir ao repositório de Configuração de Aplicativos e deixe os campos Rótulo e Tipo de Conteúdo com seus valores padrão. Para mais informações sobre como adicionar valores-chave a um repositório usando o portal do Azure ou a CLI, acesse Criar um valor-chave.

Chave	Valor
TestApp:Configurações:Mensagem	Dados da Configuração de 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 em relação ao 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 nova pasta para o seu 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 os dados da Configuração de Aplicativo

Adicione referências ao pacote Microsoft.Extensions.Configuration.AzureAppConfiguration NuGet executando o seguinte comando:
```
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
```
Execute o seguinte comando para restaurar pacotes do 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 de Aplicativos usando o Microsoft Entra ID (recomendado) ou uma cadeia de conexão.

Microsoft Entra ID (recomendado)
Cadeia de conexão

Você usa o DefaultAzureCredential para autenticar-se no seu repositório de Configuração de Aplicativos. Siga as instruções para atribuir à credencial a função Leitor de Dados de Configuração de Aplicativo. Certifique-se de permitir tempo suficiente para a permissão se propagar 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 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.

Abra o Worker.cs. Injete IConfiguration e IConfigurationRefresher no serviço Worker e registre os dados de configuração na Configuração do Aplicativo.
```
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 método ConfigureRefresh sozinho não fará com que a configuração seja atualizada automaticamente. Você chama o método TryRefreshAsync da interface IConfigurationRefresher para disparar uma atualização. Esse design serve para evitar solicitações enviadas à Configuração de Aplicativos mesmo quando o aplicativo está ocioso. Você pode incluir a chamada TryRefreshAsync quando considera o aplicativo ativo. Por exemplo, isso pode ocorrer quando você processa uma mensagem de entrada, uma ordem ou uma iteração de uma tarefa complexa. Também pode estar em um temporizador se o seu aplicativo estiver ativo o tempo todo. Neste exemplo, você chama TryRefreshAsync sempre que o serviço em segundo plano é executado. Observe que, mesmo que a chamada TryRefreshAsync falhe por algum motivo, seu aplicativo continuará a usar a configuração armazenada em cache. Outra tentativa será feita quando o intervalo de atualização configurado tiver passado e a TryRefreshAsync chamada for disparada pela atividade do aplicativo novamente. Chamar TryRefreshAsync é uma operação no-op antes que o intervalo de atualização configurado expire, portanto, seu impacto no desempenho é mínimo, mesmo que seja chamado com frequência.

Compilar e executar o aplicativo localmente

Defina uma variável de ambiente.
- Microsoft Entra ID (recomendado)
- Cadeia de conexão
Defina a variável de ambiente chamada Ponto de Extremidade para o ponto de extremidade do repositório de Configuração de Aplicativos encontrado na Visão Geral da sua loja no portal do Azure.

Se você usar o prompt de comando do Windows, execute o comando a seguir 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 comando a seguir:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Defina a variável de ambiente chamada ConnectionString como a cadeia de conexão somente leitura do repositório de Configuração de Aplicativos encontrada nas Chaves de acesso do seu repositório no portal do Azure.

Se você usar o prompt de comando do Windows, execute o comando a seguir 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 comando a seguir:
```
export ConnectionString='<connection-string-of-your-app-configuration-store>'
```
Execute o comando a seguir para compilar o aplicativo.
```
dotnet build
```
Depois que a compilação for concluída com sucesso, execute o comando a seguir para executar o aplicativo localmente.
```
dotnet run
```
Você deve ver as seguintes saídas no console.
No portal do Azure, navegue até o Explorador de configuração 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 de Aplicativos do Azure – Atualizados
Aguarde alguns instantes até que o intervalo de atualização passe. Você verá as saídas do console alteradas.

Chave	Valor
TestApp:Configurações:Mensagem	Dados da Configuração de Aplicativos do Azure – Atualizados

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

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

Para aprender a usar uma identidade gerenciada pelo Azure para simplificar o acesso à Configuração de Aplicativos, prossiga para o próximo tutorial:

Integração de identidade gerenciada