Tutorial: Introdução ao SDK do Azure WebJobs para processamento em segundo plano controlado por eventos

Introdução ao SDK de WebJobs do Azure para o Serviço de Aplicativo do Azure para permitir que seus aplicativos Web executem tarefas em segundo plano, tarefas agendadas e respondam a eventos.

Use o Visual Studio 2022 para criar um aplicativo de console .NET Core que usa o SDK WebJobs para responder a mensagens da Fila de Armazenamento do Azure, executar o projeto localmente e, finalmente, implantá-lo no Azure.

Neste tutorial, vai aprender a:

Pré-requisitos

• Visual Studio 2022 com a carga de trabalho de desenvolvimento do Azure. Instale o Visual Studio 2022.

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.

Criar uma aplicação de consola

Nesta seção, você começa criando um projeto no Visual Studio 2022. Em seguida, você adicionará ferramentas para desenvolvimento do Azure, publicação de código e funções que escutam gatilhos e funções de chamada. Por último, você configurará o log do console que desabilita uma ferramenta de monitoramento herdada e habilita um provedor de console com filtragem padrão.

Criar um projeto

1. No Visual Studio, selecione Arquivo>Novo>Projeto.

2. Em Criar um novo projeto, selecione Aplicativo de Console (C#) e selecione Avançar.

3. Em Configurar seu novo projeto, nomeie o projeto WebJobsSDKSample e selecione Avançar.

4. Escolha sua estrutura de destino e selecione Criar. Este tutorial foi verificado usando o .NET 6.0.

Instalar pacotes NuGet WebJobs

Instale o pacote NuGet WebJobs mais recente. Este pacote inclui Microsoft.Azure.WebJobs (SDK WebJobs), que permite publicar seu código de função em WebJobs no Serviço de Aplicativo do Azure.

1. Obtenha a versão 4.x estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Extensions.

2. No Visual Studio, vá para Ferramentas>Gerenciador de Pacotes NuGet.

3. Selecione Console do Gerenciador de Pacotes. Você verá uma lista de cmdlets NuGet, um link para a documentação e um PM> ponto de entrada.

4. No comando a seguir, substitua <4_X_VERSION> pelo número da versão atual que você encontrou na etapa 1.

   Install-Package Microsoft.Azure.WebJobs.Extensions -version <4_X_VERSION>
   

5. No Console do Gerenciador de Pacotes, execute o comando. A lista de extensões aparece e é instalada automaticamente.

Criar o anfitrião

O host é o contêiner de tempo de execução para funções que escuta acionadores e chama funções. As etapas a seguir criam um host que implementa IHosto , que é o Host Genérico no ASP.NET Core.

1. Selecione a guia Program.cs , remova o conteúdo existente e adicione estas using instruções:

   using System.Threading.Tasks;
   using Microsoft.Extensions.Hosting;
   

2. Também em Program.cs, adicione o seguinte código:

   namespace WebJobsSDKSample
   {
       class Program
       {
           static async Task Main()
           {
               var builder = new HostBuilder();
               builder.ConfigureWebJobs(b =>
               {
                   b.AddAzureStorageCoreServices();
               });
               var host = builder.Build();
               using (host)
               {
                   await host.RunAsync();
               }
           }
       }
   }
   

No ASP.NET Core, as configurações de host são definidas chamando métodos na HostBuilder instância. Para obter mais informações, consulte .NET Generic Host. O ConfigureWebJobs método de extensão inicializa o host WebJobs. No ConfigureWebJobs, inicialize extensões de vinculação específicas, como a extensão de vinculação de armazenamento, e defina as propriedades dessas extensões.

Ativar o registo da consola

Configure o log do console que usa a estrutura de log do ASP.NET Core. Essa estrutura, Microsoft.Extensions.Logging, inclui uma API que funciona com uma variedade de provedores de log internos e de terceiros.

1. Obtenha a versão estável mais recente do Microsoft.Extensions.Logging.Console pacote NuGet, que inclui Microsoft.Extensions.Loggingo .

2. No comando a seguir, substitua <6_X_VERSION> pelo número da versão atual que você encontrou na etapa 1. Cada tipo de pacote NuGet tem um número de versão exclusivo.

   Install-Package Microsoft.Extensions.Logging.Console -version <6_X_VERSION>
   

3. No Console do Gerenciador de Pacotes, preencha o número da versão atual e execute o comando. A lista de extensões aparece e é instalada automaticamente.

4. Na aba Program.cs, adicione esta using instrução:

   using Microsoft.Extensions.Logging;
   

5. Continuando em Program.cs, adicione o ConfigureLogging método a HostBuilder, antes do Build comando. O AddConsole método adiciona o log do console à configuração.

   builder.ConfigureLogging((context, b) =>
   {
       b.AddConsole();
   });
   

   O Main método agora tem esta aparência:

   static async Task Main()
   {
       var builder = new HostBuilder();
       builder.ConfigureWebJobs(b =>
               {
                   b.AddAzureStorageCoreServices();
               });
       builder.ConfigureLogging((context, b) =>
               {
                   b.AddConsole();
               });
       var host = builder.Build();
       using (host)
       {
           await host.RunAsync();
       }
   }
   

   Esta adição faz estas alterações:

   • Desabilita o registro em log do painel. O painel é uma ferramenta de monitoramento herdada e o registro em log do painel não é recomendado para cenários de produção de alto rendimento.
   • Adiciona o provedor de console com filtragem padrão.

Agora, você pode adicionar uma função que é acionada por mensagens que chegam em uma fila de Armazenamento do Azure.

Adicionar uma função

Uma função é uma unidade de código que é executada em uma agenda, é acionada com base em eventos ou é executada sob demanda. Um gatilho ouve um evento de serviço. No contexto do SDK WebJobs, acionado não se refere ao modo de implantação. WebJobs programados ou orientados a eventos criados usando o SDK devem sempre ser implantados como WebJobs contínuos com "Always on" habilitado.

Nesta seção, você cria uma função acionada por mensagens em uma fila de Armazenamento do Azure. Primeiro, você precisa adicionar uma extensão de associação para se conectar ao Armazenamento do Azure.

Instalar a extensão de enlace do Armazenamento

A partir da versão 3 do SDK de WebJobs, para se conectar aos serviços de Armazenamento do Azure, você deve instalar um pacote de extensão de vinculação de Armazenamento separado.

1. Obtenha a versão estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Extensions.Storage , versão 5.x.

2. No comando a seguir, substitua <5_X_VERSION> pelo número da versão atual que você encontrou na etapa 1. Cada tipo de pacote NuGet tem um número de versão exclusivo.

   Install-Package Microsoft.Azure.WebJobs.Extensions.Storage -Version <5_X_VERSION>
   

3. No Console do Gerenciador de Pacotes, execute o comando com o número da versão atual no ponto de PM> entrada.

4. Continuando em Program.cs, no ConfigureWebJobs método extension, adicione o AddAzureStorageQueues HostBuilder método na instância (antes do Build comando) para inicializar a extensão Storage. Neste ponto, o ConfigureWebJobs método tem esta aparência:

   builder.ConfigureWebJobs(b =>
   {
       b.AddAzureStorageCoreServices();
       b.AddAzureStorageQueues();
   });
   

5. Adicione o seguinte código no Main método após o builder é instanciado:

   builder.UseEnvironment(EnvironmentName.Development);
   

   A execução no modo de desenvolvimento reduz o backoff exponencial de sondagem de fila que pode atrasar significativamente a quantidade de tempo que leva para o tempo de execução encontrar a mensagem e invocar a função. Você deve remover essa linha de código ou alternar para Production quando terminar o desenvolvimento e o teste.

   O Main método agora deve se parecer com o exemplo a seguir:

   static async Task Main()
   {
       var builder = new HostBuilder();
       builder.UseEnvironment(EnvironmentName.Development);
       builder.ConfigureLogging((context, b) =>
       {
           b.AddConsole();
       });
       builder.ConfigureWebJobs(b =>
       {
           b.AddAzureStorageCoreServices();
           b.AddAzureStorageQueues();
       });
       var host = builder.Build();
       using (host)
       {
           await host.RunAsync();
       }
   }
   

Criar uma função acionada por fila

O QueueTrigger atributo informa ao tempo de execução para chamar essa função quando uma nova mensagem é escrita em uma fila de Armazenamento do Azure chamada queue. O conteúdo da mensagem de fila é fornecido para o código do método no message parâmetro. O corpo do método é onde você processa os dados de gatilho. Neste exemplo, o código apenas registra a mensagem.

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto, selecione Adicionar>Novo Item e selecione Classe.

2. Nomeie o novo arquivo de classe C# Functions.cs e selecione Adicionar.

3. No Functions.cs, substitua o modelo gerado pelo seguinte código:

   using Microsoft.Azure.WebJobs;
   using Microsoft.Extensions.Logging;
   
   namespace WebJobsSDKSample
   {
       public class Functions
       {
           public static void ProcessQueueMessage([QueueTrigger("queue")] string message, ILogger logger)
           {
               logger.LogInformation(message);
           }
       }
   }
   

   Você deve marcar a classe Functions como public static para que o tempo de execução acesse e execute o método. No exemplo de código acima, quando uma mensagem é adicionada a uma fila chamada queue, a função é executada e a cadeia de caracteres é gravada message nos logs. A fila que está sendo monitorada está na conta de Armazenamento do Azure padrão, que você cria em seguida.

O message parâmetro não precisa ser uma cadeia de caracteres. Você também pode vincular a um objeto JSON, uma matriz de bytes ou um objeto CloudQueueMessage . Consulte Uso do gatilho de fila. Cada tipo de associação (como filas, blobs ou tabelas) tem um conjunto diferente de tipos de parâmetros aos quais você pode se associar.

Criar uma conta de armazenamento do Azure

O Emulador de Armazenamento do Azure que é executado localmente não tem todos os recursos que o SDK WebJobs precisa. Você criará uma conta de armazenamento no Azure e configurará o projeto para usá-la.

Para saber como criar uma conta de armazenamento v2 de uso geral, consulte Criar uma conta de armazenamento do Azure.

Localize e copie sua cadeia de conexão

Uma cadeia de conexão é necessária para configurar o armazenamento. Mantenha essa cadeia de conexão para as próximas etapas.

1. No portal do Azure, navegue até sua conta de armazenamento e selecione Configurações.

2. Em Configurações, selecione Teclas de acesso.

3. Para a Cadeia de conexão na tecla 1, selecione o ícone Copiar para a área de transferência.

   

Configurar o armazenamento para ser executado localmente

O SDK WebJobs procura a cadeia de conexão de armazenamento nas Configurações do Aplicativo no Azure. Quando você executa localmente, ele procura esse valor no arquivo de configuração local ou em variáveis de ambiente.

1. Clique com o botão direito do mouse no projeto, selecione Adicionar>Novo Item, selecione Arquivo de configuração JSON JavaScript, nomeie o novo arquivo appsettings.json arquivo e selecione Adicionar.

2. No novo arquivo, adicione um AzureWebJobsStorage campo, como no exemplo a seguir:

   {
       "AzureWebJobsStorage": "{storage connection string}"
   }
   

3. Substitua {storage connection string} pela cadeia de conexão que você copiou anteriormente.

4. Selecione o arquivo de appsettings.json no Gerenciador de Soluções e, na janela Propriedades , defina a ação Copiar para Diretório de Saída como Copiar se for mais recente.

Como esse arquivo contém um segredo de cadeia de conexão, você não deve armazenar o arquivo em um repositório de código remoto. Depois de publicar seu projeto no Azure, você pode adicionar a mesma configuração de aplicativo de cadeia de conexão em seu aplicativo no Serviço de Aplicativo do Azure.

Teste localmente

Crie e execute o projeto localmente e crie uma fila de mensagens para acionar a função.

1. No portal do Azure, navegue até sua conta de armazenamento e selecione a guia Filas (1). Selecione + Fila (2) e insira fila como o nome da fila (3). Em seguida, selecione OK (4).

   

2. Clique na nova fila e selecione Adicionar mensagem.

3. Na caixa de diálogo Adicionar mensagem, digite Hello World! como o texto da mensagem e selecione OK. Agora há uma mensagem na fila.

   

4. Pressione Ctrl+F5 para executar o projeto.

   O console mostra que o tempo de execução encontrou sua função. Como você usou o QueueTrigger ProcessQueueMessage atributo na função, o tempo de execução WebJobs escuta mensagens na fila chamada queue. Quando encontra uma nova mensagem nessa fila, o tempo de execução chama a função, passando o valor da cadeia de caracteres da mensagem.

5. Volte para a janela Fila e atualize-a. A mensagem desapareceu, uma vez que foi processada pela sua função em execução localmente.

6. Feche a janela do console.

Agora é hora de publicar seu projeto SDK WebJobs no Azure.

Implementar no Azure

Durante a implantação, você cria uma instância do serviço de aplicativo onde executará suas funções. Quando você publica um aplicativo de console .NET no Serviço de Aplicativo no Azure, ele é executado automaticamente como um WebJob. Para saber mais sobre publicação, consulte Desenvolver e implantar WebJobs usando o Visual Studio.

Criar recursos do Azure

1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.

2. Na caixa de diálogo Publicar, selecione Azure para Destino e, em seguida, selecione Avançar.

3. Selecione Azure WebJobs para destino específico e, em seguida, selecione Avançar.

4. Acima das instâncias do Serviço de Aplicativo, selecione o botão de adição (+) para Criar um novo WebJob do Azure.

5. Na caixa de diálogo Serviço de Aplicativo (Windows), use as configurações de hospedagem na tabela a seguir.

   Definição	Valor sugerido	Description
   Nome	Nome globalmente exclusivo	Nome que identifica exclusivamente a sua nova aplicação de funções.
   Subscrição	Selecione a sua subscrição	A subscrição do Azure que deve utilizar.
   Grupo de recursos	myResourceGroup	Nome do grupo de recursos no qual a sua aplicação de funções será criada. Escolha Novo para criar um grupo de recursos novo.
   Plano de Alojamento	Plano do Serviço de Aplicações	Um plano do serviço de aplicações especifica o local, tamanho e funcionalidades da farm de servidores Web que aloja a aplicação. Pode economizar dinheiro ao alojar várias aplicações, configurando as aplicações Web para partilhar um único plano do serviço de aplicações. Os planos do Serviço de Aplicativo definem a região, o tamanho da instância, a contagem de escala e a SKU (Gratuito, Compartilhado, Básico, Standard ou Premium). Escolha Novo para criar um novo plano do Serviço de Aplicativo. As camadas Gratuita e Básica não suportam a opção Always On para manter seu site funcionando continuamente.

   

6. Selecione Criar para criar um WebJob e recursos relacionados no Azure com essas configurações e implantar o código do projeto.

7. Selecione Concluir para retornar à página Publicar .

Ativar o AlwaysOn

Para um WebJob contínuo, você deve habilitar a configuração Always on no site para que seus WebJobs sejam executados corretamente. Se você não ativar o recurso Sempre ativado, o tempo de execução ficará ocioso após alguns minutos de inatividade.

1. Na página Publicar, selecione os três pontos acima de Hospedagem para mostrar as ações da seção Perfil de hospedagem e escolha Abrir no portal do Azure.

2. Em Configurações, escolha Configurações>gerais, defina Sempre ativado como Ativado e selecione Salvar e Continuar para reiniciar o site.

Publicar o projeto

Com o aplicativo Web criado no Azure, é hora de publicar o projeto WebJobs.

1. Na página Publicar em Hospedagem, selecione o botão Editar e altere o Tipo de Trabalho Web para Continuous e selecione Salvar. Isso garante que o WebJob esteja em execução quando as mensagens forem adicionadas à fila. WebJobs acionados são normalmente usados apenas para webhooks manuais.

   

2. Selecione o botão Publicar no canto superior direito da página Publicar . Quando a operação for concluída, seu WebJob será executado no Azure.

Criar uma configuração de aplicativo de conexão de armazenamento

Você precisa criar a mesma configuração de cadeia de conexão de armazenamento no Azure que você usou localmente em seu arquivo de configuração appsettings.json. Isso permite que você armazene com mais segurança a cadeia de conexão e

1. Na página Publicar perfil, selecione os três pontos acima de Hospedagem para mostrar as ações da seção Perfil de hospedagem e escolha Gerenciar configurações do Serviço de Aplicativo do Azure.

2. Em Configurações do aplicativo, escolha + Adicionar configuração.

3. Em Novo nome da configuração do aplicativo, digite AzureWebJobsStorage e selecione OK.

4. Em Remoto, cole a cadeia de conexão da configuração local e selecione OK.

A cadeia de conexão agora está definida em seu aplicativo no Azure.

Acionar a função no Azure

1. Certifique-se de que não está a executar localmente. Feche a janela do console se ela ainda estiver aberta. Caso contrário, a instância local pode ser a primeira a processar quaisquer mensagens de fila que você criar.

2. Na página Fila no Visual Studio, adicione uma mensagem à fila como antes.

3. Atualize a página Fila e a nova mensagem desaparece porque foi processada pela função em execução no Azure.

Habilitar o registro em log do Application Insights

Quando o WebJob é executado no Azure, você não pode monitorar a execução da função exibindo a saída do console. Para poder monitorar seu WebJob, você deve criar uma instância associada do Application Insights ao publicar seu projeto.

Criar uma instância do Application Insights

1. Na página Publicar perfil, selecione os três pontos acima de Hospedagem para mostrar as ações da seção Perfil de hospedagem e escolha Abrir no Portal do Azure.

2. No aplicativo Web, em Configurações, escolha Application Insights e selecione Ativar Application Insights.

3. Verifique o nome do recurso gerado para a instância e o local e selecione Aplicar.

4. Em Configurações, escolha Configuração e verifique se um novo APPINSIGHTS_INSTRUMENTATIONKEY foi criado. Essa chave é usada para conectar sua instância WebJob ao Application Insights.

Para aproveitar o log do Application Insights, você também precisa atualizar seu código de log.

Instalar a extensão do Application Insights

1. Obtenha a versão estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Logging.ApplicationInsights , versão 3.x.

2. No comando a seguir, substitua <3_X_VERSION> pelo número da versão atual que você encontrou na etapa 1. Cada tipo de pacote NuGet tem um número de versão exclusivo.

   Install-Package Microsoft.Azure.WebJobs.Logging.ApplicationInsights -Version <3_X_VERSION>
   

3. No Console do Gerenciador de Pacotes, execute o comando com o número da versão atual no ponto de PM> entrada.

Inicializar o provedor de log do Application Insights

Abra Program.cs e adicione o seguinte inicializador no ConfigureLogging após a chamada para AddConsole:

// If the key exists in settings, use it to enable Application Insights.
string instrumentationKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
if (!string.IsNullOrEmpty(instrumentationKey))
{
    b.AddApplicationInsightsWebJobs(o => o.InstrumentationKey = instrumentationKey);
}

O Main código do método agora deve se parecer com o exemplo a seguir:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment(EnvironmentName.Development);
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    builder.ConfigureLogging((context, b) =>
            {
                b.AddConsole();

                // If the key exists in settings, use it to enable Application Insights.
                string instrumentationKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
                if (!string.IsNullOrEmpty(instrumentationKey))
                {
                    b.AddApplicationInsightsWebJobs(o => o.InstrumentationKey = instrumentationKey);
                }
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Isso inicializa o provedor de log do Application Insights com filtragem padrão. Quando executadas localmente, todas as informações e logs de nível superior são gravados no console e no Application Insights.

Republique o projeto e acione a função novamente

1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.

2. Como antes, use o portal do Azure para criar uma mensagem de fila como fez anteriormente, exceto digite Hello App Insights! como o texto da mensagem.

3. Na página Publicar perfil, selecione os três pontos acima de Hospedagem para mostrar as ações da seção Perfil de hospedagem e escolha Abrir no Portal do Azure.

4. No aplicativo Web, em Configurações, escolha Application Insights e selecione Exibir dados do Application Insights.

5. Selecione Pesquisar e, em seguida, selecione Ver todos os dados nas últimas 24 horas.

   

6. Se não vir a mensagem Hello App Insights! , selecione Atualizar periodicamente durante vários minutos. Os logs não aparecem imediatamente, porque leva um tempo para o cliente do Application Insights liberar os logs que processa.

   

Adicionar ligações de entrada/saída

As ligações simplificam o código que lê e grava dados. As ligações de entrada simplificam o código que lê dados. As ligações de saída simplificam o código que grava dados.

Adicionar enlaces

As ligações de entrada simplificam o código que lê dados. Neste exemplo, a mensagem de fila é o nome de um blob, que você usará para localizar e ler um blob no Armazenamento do Azure. Em seguida, você usará associações de saída para gravar uma cópia do arquivo no mesmo contêiner.

1. Em Functions.cs, adicione um using:

   using System.IO;
   

2. Substitua o método ProcessQueueMessage pelo código abaixo:

   public static void ProcessQueueMessage(
       [QueueTrigger("queue")] string message,
       [Blob("container/{queueTrigger}", FileAccess.Read)] Stream myBlob,
       [Blob("container/copy-{queueTrigger}", FileAccess.Write)] Stream outputBlob,
       ILogger logger)
   {
       logger.LogInformation($"Blob name:{message} \n Size: {myBlob.Length} bytes");
       myBlob.CopyTo(outputBlob);
   }
   

   Neste código, queueTrigger é uma expressão de ligação, o que significa que ele resolve para um valor diferente em tempo de execução. No tempo de execução, ele tem o conteúdo da mensagem de fila.

   Esse código usa associações de saída para criar uma cópia do arquivo identificado pela mensagem de fila. A cópia do arquivo é prefixada com copy-.

3. No Program.cs, no ConfigureWebJobs método extension, adicione o AddAzureStorageBlobs HostBuilder método na instância (antes do Build comando) para inicializar a extensão Storage. Neste ponto, o ConfigureWebJobs método tem esta aparência:

   builder.ConfigureWebJobs(b =>
   {
       b.AddAzureStorageCoreServices();
       b.AddAzureStorageQueues();
       b.AddAzureStorageBlobs();
   });
   

4. Crie um contêiner de blob em sua conta de armazenamento.

   a. No portal do Azure, navegue até a guia Contêineres abaixo de Armazenamento de dados e selecione + Contêiner

   b. Na caixa de diálogo Novo contêiner, digite contêiner como o nome do contêiner e selecione Criar.

5. Carregue o arquivo Program.cs para o contêiner de blob. (Este arquivo é usado aqui como exemplo; você pode carregar qualquer arquivo de texto e criar uma mensagem de fila com o nome do arquivo.)

   a. Selecione o novo contêiner que você criou

   b. Selecione o botão Carregar.

   

   c. Localize e selecione Program.cs e, em seguida, selecione OK.

Republicar o projeto

1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.

2. Na caixa de diálogo Publicar, certifique-se de que o perfil atual está selecionado e, em seguida, selecione Publicar. Os resultados da publicação são detalhados na janela Saída .

3. Crie uma mensagem de fila na fila criada anteriormente, com Program.cs como o texto da mensagem.

   

4. Uma cópia do arquivo, copy-Program.cs, aparecerá no contêiner de blob.

Próximos passos

Este tutorial mostrou como criar, executar e implantar um projeto WebJobs SDK 3.x.