Tutorial: começar a usar o SDK do Azure WebJobs para executar um processamento em segundo plano controlado por evento
Comece a usar o SDK do Azure WebJobs para executar o Serviço de Aplicativo do Azure a fim de permitir que aplicativos Web executem tarefas em segundo plano, tarefas agendadas e respondam a eventos.
Use o Visual Studio 2022 para criar um aplicativo de console do .NET Core que usa o SDK de WebJobs para responder às mensagens da Fila de Armazenamento do Azure, executar o projeto localmente e implantá-lo no Azure.
Neste tutorial, você aprenderá a:
- Criar um aplicativo de console
- Adicionar uma função
- Testar localmente
- Implantar no Azure
- Habilitar o registro em log do Application Insights
- Adicionar associações de entrada/saída
Pré-requisitos
Ter o Visual Studio 2022 com uma carga de trabalho de desenvolvimento do Azure. Instalar o Visual Studio 2022.
Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Criar um aplicativo de console
Inicie esta seção criando um projeto no Visual Studio 2022. Depois você vai adicionar ferramentas para executar o desenvolvimento do Azure, a publicação de código e funções que detectam gatilhos, bem como funções de chamada. Por fim, você vai configurar o registro em log do console que desabilitará uma ferramenta de monitoramento herdada e habilitará um provedor de console com uma filtragem padrão.
Observação
Os procedimentos deste artigo são verificados para a criação de um aplicativo de console do .NET Core executado no .NET Core 6.0.
Criar um projeto
No Visual Studio, selecione Arquivo>Novo>Projeto.
Em Criar um projeto, selecione Aplicativo de Console (C#) , depois clique em Próximo.
Em Configurar seu novo projeto, nomeie o projeto como WebJobsSDKSample, depois clique em Criar.
Selecione sua Estrutura de destino, depois clique em Criar. Este tutorial foi verificado usando o .NET Core 6.0.
Instalar pacotes NuGet de WebJobs
Instale o pacote NuGet de WebJobs mais recente. Esse pacote inclui o Microsoft.Azure.WebJobs (SDK de WebJobs), que permite publicar seu código de função em WebJobs no Serviço de Aplicativo do Azure.
Obtenha a versão 4.x estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Extensions.
No Visual Studio, acesse Ferramentas>Gerenciador de Pacotes NuGet.
Selecione o Console do Gerenciador de Pacotes. Você verá uma lista de cmdlets NuGet, um link para a documentação e o ponto de entrada
PM>
.No comando abaixo, substitua
<4_X_VERSION>
pelo número de versão atual encontrado na etapa 1.Install-Package Microsoft.Azure.WebJobs.Extensions -version <4_X_VERSION>
Execute o comando no Console do Gerenciador de Pacotes. A lista de extensões será exibida e instalada de modo automático.
Crie o Host
O host é o contêiner de runtime de funções que escuta gatilhos e chama funções. As etapas a seguir criam um host que implementa o IHost
, que é o host genérico no ASP.NET Core.
Selecione a guia Program.cs, remova o conteúdo existente e adicione estas instruções
using
:using System.Threading.Tasks; using Microsoft.Extensions.Hosting;
Ainda na guia 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 instância do HostBuilder
. Para saber mais, confira Host Genérico do .NET. O método de extensão ConfigureWebJobs
inicializa o host do WebJobs. Em ConfigureWebJobs
, inicialize extensões de associação específicas, como a extensão de associação do Armazenamento e defina as propriedades dessas extensões.
Habilitar o registro em log de console
Configure o registro em log do console que usa a estrutura de registros do ASP.NET Core. Essa estrutura, Microsoft.Extensions.Logging, inclui uma API que funciona com vários provedores de registros em log integrados e de terceiros.
Obtenha a versão estável mais recente do pacote NuGet
Microsoft.Extensions.Logging.Console
, que inclui oMicrosoft.Extensions.Logging
.No comando abaixo, substitua
<6_X_VERSION>
pelo número de versão atual encontrado 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>
No Console do Gerenciador de Pacotes, preencha o número de versão atual e execute o comando. A lista de extensões será exibida e instalada de modo automático.
Na guia Program.cs, adicione esta instrução
using
:using Microsoft.Extensions.Logging;
Ainda em Program.cs, adicione o método
ConfigureLogging
aoHostBuilder
, antes do comandoBuild
. O métodoAddConsole
adiciona o log de console na configuração.builder.ConfigureLogging((context, b) => { b.AddConsole(); });
O método
Main
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(); } }
Essa adição vai executar as seguintes alterações:
- Desabilita o registro em log do painel. O painel é um ferramenta de monitoramento herdada, e o registro em log do painel não é recomendado para cenários de produção de alta taxa de transferência.
- Adiciona o provedor de console com filtragem padrão.
Agora, você pode adicionar uma função disparada por mensagens que chegam a uma fila de Armazenamento do Microsoft Azure.
Adicionar uma função
Função é uma unidade de código executada em uma agenda. Ela é disparada com base em eventos ou executada sob demanda. O gatilho detecta um evento de serviço. No contexto do SDK de WebJobs, uma função disparada não se refere ao modo de implantação. Os WebJobs agendados ou controlados por evento criados usando o SDK sempre deverão ser implantados como WebJobs contínuos com o "Always On" habilitado.
Nesta seção, você vai criar uma função disparada por mensagens em uma fila de Armazenamento do Azure. Primeiro, é preciso adicionar uma extensão de associação para se conectar ao Armazenamento do Azure.
Instalar a extensão de associação do Armazenamento
Da versão 3 em diante do SDK de WebJobs, será preciso instalar um pacote separado de extensões de associação do Armazenamento para se conectar aos serviços de Armazenamento do Azure.
Observação
Começando com 5.x, Microsoft.Azure.WebJobs.Extensions.Storage foi dividido pelo serviço de armazenamento e migrou o método de extensão AddAzureStorage()
por tipo de serviço.
Obtenha a versão estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Extensions.Storage versão 5.x.
No comando abaixo, substitua
<5_X_VERSION>
pelo número de versão atual encontrado 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>
No Console do Gerenciador de Pacotes execute o comando usando o número de versão atual no ponto de entrada
PM>
.Ainda em Program.cs, no método de extensão
ConfigureWebJobs
, adicione o métodoAddAzureStorageQueues
na instânciaHostBuilder
(antes do comandoBuild
) para inicializar a extensão do Armazenamento. Neste momento, o métodoConfigureWebJobs
será semelhante ao seguinte:builder.ConfigureWebJobs(b => { b.AddAzureStorageCoreServices(); b.AddAzureStorageQueues(); });
Adicione o código abaixo ao método
Main
depois que obuilder
criar uma instância:builder.UseEnvironment(EnvironmentName.Development);
A execução no modo de desenvolvimento reduz a retirada exponencial da sondagem da fila que poderá atrasar de modo significativo o tempo que o runtime leva para localizar a mensagem e invocar a função. Será necessário remover essa linha de código ou alternar para
Production
ao finalizar o desenvolvimento e o teste.O método
Main
agora deve ser semelhante ao seguinte exemplo: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 disparada por filas
O atributo QueueTrigger
informa o runtime para chamar esta função quando uma nova mensagem é gravada em uma fila de Armazenamento do Microsoft Azure chamada queue
. O conteúdo da mensagem da fila é fornecido para o código do método no parâmetro message
. O corpo do método é onde você processa os dados de gatilho. Neste exemplo, o código apenas registra a mensagem.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto, clique em Adicionar>Novo Item, depois selecione Classe.
Nomeie o novo arquivo de classe C# como Functions.cs, depois clique em Adicionar.
Em 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 runtime acesse e execute o método. No exemplo de código acima, quando uma mensagem for adicionada a uma fila chamadaqueue
, a função será executada e a cadeia de caracteresmessage
será gravada nos logs. A fila monitorada está na conta padrão de Armazenamento do Azure, que será criada a seguir.
O parâmetro message
não precisa ser uma cadeia de caracteres. Você também pode associar a um objeto JSON, uma matriz de bytes ou um objeto CloudQueueMessage. Consulte Uso de gatilho de fila. Cada tipo de associação (como filas, blobs ou tabelas) tem um conjunto diferente de tipos de parâmetros que você pode associar.
Criar uma conta de armazenamento do Azure
O emulador do Armazenamento do Microsoft Azure executado localmente não tem todos os recursos de que o WebJobs SDK precisa. Você vai criar uma conta de armazenamento no Azure e configurar o projeto para usá-la.
Para saber como criar uma conta de armazenamento v2 para uso geral, confira como Criar uma conta de Armazenamento do Azure.
Localizar e copiar uma cadeia de conexão
É necessário usar uma cadeia de conexão para configurar o armazenamento. Mantenha essa cadeia de conexão para as próximas etapas.
No portal do Azure, acesse sua conta de armazenamento e selecione Configurações.
Em Configurações, selecione Chaves de acesso.
Na Cadeia de conexão em key1, clique no ícone Copiar para a área de transferência.
Configurar o armazenamento para executar localmente
O SDK do WebJobs procura a cadeia de conexão de armazenamento nas Configurações de Aplicativo no Azure. Quando você executa localmente, ele procura esse valor no arquivo de configuração local ou nas variáveis de ambiente.
Clique com o botão direito do mouse no projeto, clique em Adicionar>Novo Item, selecione Arquivo de configuração JSON do JavaScript, nomeie o novo arquivo como appsettings.json, depois clique em Adicionar.
No novo arquivo, adicione um campo
AzureWebJobsStorage
, como no exemplo a seguir:{ "AzureWebJobsStorage": "{storage connection string}" }
Substitua a {cadeia de conexão de armazenamento} pela cadeia de conexão copiada anteriormente.
Selecione o arquivo appsettings.json no Gerenciador de Soluções e, na janela Propriedades, defina uma ação de Copiar para Diretório de Saída para Copiar caso seja mais recente.
Como esse arquivo contém um segredo de cadeia de conexão, não recomendamos armazenar o arquivo em um repositório remoto de código. Após publicar seu projeto no Azure, será possível adicionar a mesma configuração do aplicativo da cadeia de conexão em seu aplicativo no Serviço de Aplicativo do Azure.
Testar localmente
Crie e execute o projeto localmente, depois crie uma fila de mensagens para disparar a função.
No portal do Azure, navegue até sua conta de armazenamento e selecione a guia Filas (1). Selecione + Fila (2) e insira a fila como o nome da Fila (3). Em seguida, selecione OK (4).
Clique na nova fila e selecione Adicionar mensagem.
Na caixa de diálogo Adicionar mensagem, insira Olá, mundo! como o texto da mensageme, em seguida, selecione OK. Agora há uma mensagem na fila.
Pressione Ctrl+F5 para executar o projeto.
O console mostrará que o runtime encontrou sua função. Como você usou o atributo
QueueTrigger
na funçãoProcessQueueMessage
, o runtime de WebJobs detectará mensagens da fila chamadaqueue
. Quando ele encontra uma nova mensagem nessa fila, o runtime executa uma chamada à função, transmitindo o valor da cadeia de caracteres da mensagem.Volte para a janela Fila e atualize-a. A mensagem desaparece porque foi processada pela função que é executada localmente.
Feche a janela do console.
Agora é preciso publicar seu projeto do SDK de WebJobs no Azure.
Implantar no Azure
Durante a implantação, crie uma instância do serviço de aplicativo em que você vai executar suas funções. Ao publicar um aplicativo de console do .NET no Serviço de Aplicativo do Azure, ele será executado de modo automático como um WebJob. Para saber mais sobre a publicação, consulte Desenvolver e implantar WebJobs usando o Visual Studio.
Criar recursos do Azure
No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Publicar.
Na caixa de diálogo Publicar, selecione Azure como Destino e, em seguida, Avançar.
Selecione Azure WebJobs para Destino específico e, em seguida, selecione Avançar.
Acima das instâncias do Serviço de Aplicativo, selecione o botão mais ( + ) para Criar um novo WebJob do Azure.
Na caixa de diálogo Serviço de Aplicativo (Windows) , use as configurações de hospedagem na tabela a seguir.
Configuração Valor sugerido Description Nome Nome globalmente exclusivo Nome que identifica seu novo aplicativo de funções de forma exclusiva. Assinatura Escolha sua assinatura A assinatura do Azure a utilizar. Grupo de recursos myResourceGroup Nome do grupo de recursos no qual criar o seu aplicativo de funções. Escolha Novo para criar um novo grupo de recursos. Plano de hospedagem Plano do Serviço de Aplicativo Um plano do Serviço de Aplicativo especifica o local, tamanho e recursos do farm de servidores Web que hospeda o aplicativo. Você pode economizar dinheiro ao hospedar vários aplicativos configurando os aplicativos Web para compartilhar um único plano do Serviço de Aplicativo. 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). Selecione Novo para criar um novo plano do Serviço de Aplicativo. Os níveis Gratuito e Básico não têm suporte para a opção Always On, para manter o site continuamente em execução. Selecione Criar para criar um WebJob e recursos relacionados no Azure com essas configurações e implantar seu código de projeto.
Selecione Concluir para retornar à página Publicar.
Habilitar Always On
A fim de obter um WebJob contínuo, será preciso habilitar a configuração do Always On no site para que seus WebJobs sejam executados de modo adequado. Caso não habilite o Always On, o runtime ficará ocioso após alguns minutos de inatividade.
Na página de Publicação, clique nos três pontos acima de Hosting para exibir Ações da seção de perfil de hospedagem, depois clique em Abrir no portal do Azure.
Em Configurações, selecione Configuração>Configurações gerais, defina Always On como Ativado, depois clique em Salvar e Continuar para reiniciar o site.
Publicar o projeto
Com o aplicativo Web criado no Azure, agora é preciso publicar o projeto WebJobs.
Na página de Publicação, em Hosting, clique no botão de edição e altere o Tipo de WebJob para
Continuous
, depois clique em Salvar. Isso garantirá que o WebJob vai estar em execução quando as mensagens forem adicionadas à fila. Os WebJobs disparados geralmente são usados somente em webhooks manuais.Clique no botão Publicar no canto superior direito da página de Publicação. Após a conclusão da operação, o WebJob será executado no Azure.
Definir a configuração do aplicativo de conexão de armazenamento
É preciso definir a mesma configuração da cadeia de conexão de armazenamento no Azure usada localmente em seu arquivo de configuração appsettings.json. Isso permite armazenar a cadeia de conexão com mais segurança.
Na página de perfil de Publicação, clique nos três pontos acima de Hosting para exibir Ações da seção de perfil de hospedagem, depois clique em Gerenciar configurações do Serviço de Aplicativo do Azure.
Em Configurações do aplicativo, clique em + Adicionar configuração.
Em Novo nome de configuração do aplicativo, digite
AzureWebJobsStorage
, depois clique em OK.Em Remoto, cole a cadeia de conexão de sua configuração local, depois clique em OK.
A cadeia de conexão agora está definida em seu aplicativo no Azure.
Disparar a função no Azure
Verifique se a execução não está sendo feita localmente. Feche a janela do console caso ela ainda esteja aberta. Caso contrário, a instância local poderá ser a primeira a processar mensagens da fila criada.
Na página Fila do Visual Studio, adicione uma mensagem à fila como antes.
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
Ao executar um WebJob no Azure, não é possível monitorar a execução da função exibindo a saída do console. Para que seja possível monitorar seu WebJob, será preciso criar uma instância associada do Application Insights ao publicar seu projeto.
Crie uma instância do Application Insights
Na página de perfil de Publicação, clique nos três pontos acima de Hosting para exibir Ações da seção de perfil de hospedagem, depois clique em Abrir no portal do Azure.
Em Configurações do aplicativo Web, selecione Application Insights, depois clique em Ativar o Application Insights.
Verifique o Nome do recurso gerado para a instância e a Localização, depois clique em Aplicar.
Em Configurações, selecione Configuração e verifique se um
APPINSIGHTS_INSTRUMENTATIONKEY
foi criado. Essa chave é usada para conectar a instância do WebJob ao Application Insights.
Para aproveitar o registro em log do Application Insights, também será preciso atualizar seu código de registro em log.
Instalar uma extensão do Application Insights
Obtenha a versão estável mais recente do pacote NuGet Microsoft.Azure.WebJobs.Logging.ApplicationInsights versão 3.x.
No comando abaixo, substitua
<3_X_VERSION>
pelo número de versão atual encontrado 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>
No Console do Gerenciador de Pacotes execute o comando usando o número de versão atual no ponto de entrada
PM>
.
Inicializar o provedor de registro em log do Application Insights
Abra o Program.cs e adicione o seguinte inicializador no ConfigureLogging
após executar uma chamada ao 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 código do método Main
agora deve ser semelhante ao seguinte exemplo:
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 vai inicializar o provedor de registro em log do Application Insights com a filtragem padrão. Ao executar localmente, todas as informações e os logs de nível superior são gravados no console e no Application Insights.
Republicar o projeto e disparar a função novamente
No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Publicar.
Use o portal do Azure para criar uma mensagem da fila, conforme executado anteriormente. No entanto, como alteração, insira Olá, App Insights! como texto da mensagem.
Na página de perfil de Publicação, clique nos três pontos acima de Hosting para exibir Ações da seção de perfil de hospedagem, depois clique em Abrir no portal do Azure.
Em Configurações do aplicativo Web, selecione Application Insights, depois clique em Exibir dados do Application Insights.
Selecione Pesquisar, depois clique em Conferir todos os dados das últimas 24 horas.
Se você não vir a mensagem Hello App Insights!,selecione Atualizar periodicamente por vários minutos. Os logs não serão exibidos de modo imediato porque o cliente do Application Insights demora um pouco para liberar os logs que ele processa.
Adicionar associações de entrada/saída
As associações simplificam o código que lê e grava dados. As associações de entrada simplificam o código que lê dados. As associações de saía simplificam o código que grava dados.
Adicionar associações
As associações de entrada simplificam o código que lê dados. Neste exemplo, a mensagem da fila é o nome de um blob que será usado 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.
Em Functions.cs, adicione um
using
:using System.IO;
Substitua o método
ProcessQueueMessage
pelo seguinte código: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); }
Nesse código,
queueTrigger
é uma expressão de associação, o que significa que ele resolve para um valor diferente no runtime. No runtime, ele tem o conteúdo da mensagem da fila.Esse código usa associações de saída para criar uma cópia do arquivo identificado pela mensagem da fila. A cópia do arquivo tem o prefixo copy-.
Em Program.cs, no método de extensão
ConfigureWebJobs
, adicione o métodoAddAzureStorageBlobs
na instânciaHostBuilder
(antes do comandoBuild
) para inicializar a extensão do Armazenamento. Neste momento, o métodoConfigureWebJobs
será semelhante ao seguinte:builder.ConfigureWebJobs(b => { b.AddAzureStorageCoreServices(); b.AddAzureStorageQueues(); b.AddAzureStorageBlobs(); });
Crie um contêiner de blob em sua conta de armazenamento.
a. No portal do Azure, navegue até a guia Contêineres abaixo do 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 depois clique em Criar.
Carregue o arquivo Program.cs para o contêiner de blob. (Esse arquivo é usado aqui como um exemplo; você pode carregar qualquer arquivo de texto e criar uma mensagem da fila com o nome do arquivo.)
a. Selecione o novo contêiner criado
b. Selecione o botão Carregar.
c. Localize e selecione Program.cs e, em seguida, selecione OK.
Republicar o projeto
No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Publicar.
Na caixa de diálogo Publicar, verifique se o perfil atual está selecionado, depois clique em Publicar. Os resultados da publicação são detalhados na janela Saída.
Crie uma mensagem da fila na fila criada anteriormente, com Program.cs como o texto da mensagem.
Uma cópia do arquivo copy-Program.cs será exibida no contêiner de blob.
Próximas etapas
Este tutorial mostrou de que modo criar, executar e implantar um projeto do SDK de WebJobs 3.x.