Compartilhar via

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

  • Artigo

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 na resposta às alterações em um repositório de Configuração de Aplicativos.
  • Consuma a configuração mais recente no seu serviço em segundo plano.

Pré-requisitos

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:Settings:Message 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.

  1. Crie uma nova pasta para o seu projeto.

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

  1. Adicione referências ao pacote Microsoft.Extensions.Configuration.AzureAppConfiguration NuGet executando o seguinte comando:

    dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

  2. Execute o seguinte comando para restaurar pacotes do projeto:

    dotnet restore

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

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

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

    Você usa a autenticação DefaultAzureCredential no 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:`.
        .Select("TestApp:*")
        // Configure to reload the key 'TestApp:Settings:Message' if it is modified.
        .ConfigureRefresh(refreshOptions =>
        {
            refreshOptions.Register("TestApp:Settings:Message");
        });

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

    No método ConfigureRefresh, uma chave em seu repositório de Configuração de Aplicativos é registrada para monitoramento de alterações. O método Register tem um parâmetro booliano opcional refreshAll que pode ser usado para indicar se todos os valores de configuração deverão ser atualizados se a chave registrada for alterada. Neste exemplo, somente a chave TestApp:Settings:Message será atualizada. Todas as configurações registradas para atualização têm um término de cache padrão de 30 segundos antes de tentar uma nova atualização. Ele pode ser atualizado chamando o método AzureAppConfigurationRefreshOptions.SetCacheExpiration.

  5. 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. É possível incluir a chamada TryRefreshAsync quando você considerar 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. Se o aplicativo ficar ativo todo o tempo, a chamada poderá ser incluída por meio de um temporizador. 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 tempo de expiração do cache configurado tiver passado e a chamada TryRefreshAsync for disparada pela atividade do aplicativo novamente. Chamar TryRefreshAsync é uma não operação antes que o tempo de expiração do cache configurado decorra, portanto, seu impacto no desempenho é mínimo, mesmo se essa chamada é realizada com frequência.

Compilar e executar o aplicativo localmente

  1. Defina uma variável de ambiente.

    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>'

  2. Execute o comando a seguir para compilar o aplicativo.

    dotnet build

  3. Depois que a compilação for concluída com sucesso, execute o comando a seguir para executar o aplicativo localmente.

    dotnet run

  4. Você deve ver as seguintes saídas no console.

    Captura de tela do serviço em segundo plano.

  5. 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:Settings:Message Dados da Configuração de Aplicativos do Azure – Atualizados

  6. Aguarde alguns instantes até que o intervalo de atualização passe. Você verá as saídas do console alteradas.

    Captura de tela do serviço em segundo plano atualizado.

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. Não exclua acidentalmente grupo de recursos ou recursos incorretos. 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.

  1. Entre no portal do Azure e selecione Grupos de recursos.
  2. Na caixa Filtrar por nome..., digite o nome do seu grupo de recursos.
  3. Na lista de resultados, selecione o nome do grupo de recursos para conferir uma visão geral.
  4. Selecione Excluir grupo de recursos.
  5. 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