Tutorial: Introdução ao SDK de WebJobs do Azure para processamento em segundo plano baseado em eventos
Introdução ao SDK de WebJobs do Azure para Serviço de Aplicações do Azure para permitir que as suas aplicações Web executem tarefas em segundo plano, tarefas agendadas e respondam a eventos.
Utilize o Visual Studio 2022 para criar uma aplicação de consola .NET Core que utiliza o SDK webJobs para responder às mensagens da Fila de Armazenamento do Azure, executar o projeto localmente e, por fim, implementá-lo no Azure.
Neste tutorial, vai aprender a:
- Criar uma aplicação de consola
- Adicionar uma função
- Testar localmente
- Implementar no Azure
- Ativar o registo do Application Insights
- Adicionar enlaces de entrada/saída
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 secção, começa por criar um projeto no Visual Studio 2022. Em seguida, irá adicionar ferramentas para desenvolvimento do Azure, publicação de código e funções que ouvem acionadores e funções de chamada. Por fim, irá configurar o registo da consola que desativa uma ferramenta de monitorização legada e ativa um fornecedor de consola com filtragem predefinida.
Nota
Os procedimentos neste artigo são verificados para criar uma aplicação de consola .NET Core que é executada no .NET 6.0.
Criar um projeto
No Visual Studio, selecione Ficheiro>Novo>Projeto.
Em Criar um novo projeto, selecione Aplicação de Consola (C#)e, em seguida, selecione Seguinte.
Em Configurar o novo projeto, atribua um nome ao projeto WebJobsSDKSample e, em seguida, selecione Seguinte.
Selecione a sua arquitetura de destino e selecione Criar. Este tutorial foi verificado com o .NET 6.0.
Instalar pacotes NuGet do WebJobs
Instale o pacote NuGet do WebJobs mais recente. Este pacote inclui Microsoft.Azure.WebJobs (SDK webJobs), que lhe permite publicar o código de função no WebJobs no Serviço de Aplicações do Azure.
Obtenha a versão estável 4.x mais recente do pacote NuGet Microsoft.Azure.WebJobs.Extensions.
No Visual Studio, aceda a Ferramentas>Gestor de Pacotes NuGet.
Selecione Consola do Gestor de Pacotes. Verá uma lista de cmdlets NuGet, uma ligação para a documentação e um
PM>
ponto de entrada.No seguinte comando, substitua
<4_X_VERSION>
pelo número da versão atual que encontrou no passo 1.Install-Package Microsoft.Azure.WebJobs.Extensions -version <4_X_VERSION>
Na Consola do Gestor de Pacotes, execute o comando . A lista de extensões é apresentada e é instalada automaticamente.
Criar o Anfitrião
O anfitrião é o contentor de runtime para funções que escutam funções de acionadores e chamadas. Os passos seguintes criam um anfitrião que implementa IHost
, que é o Anfitrião Genérico no ASP.NET Core.
Selecione o separador Program.cs , remova os conteúdos existentes e adicione estas
using
instruções:using System.Threading.Tasks; using Microsoft.Extensions.Hosting;
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 do anfitrião são definidas através da chamada de métodos na HostBuilder
instância. Para obter mais informações, veja Anfitrião Genérico do .NET. O ConfigureWebJobs
método de extensão inicializa o anfitrião WebJobs. No ConfigureWebJobs
, inicialize extensões de enlace específicas, como a extensão de enlace de armazenamento, e defina as propriedades dessas extensões.
Ativar o registo da consola
Configure o registo da consola que utiliza a arquitetura de registo de ASP.NET Core. Esta arquitetura, Microsoft.Extensions.Logging, inclui uma API que funciona com uma variedade de fornecedores de registo incorporados e de terceiros.
Obtenha a versão estável mais recente do
Microsoft.Extensions.Logging.Console
pacote NuGet, que incluiMicrosoft.Extensions.Logging
.No seguinte comando, substitua
<6_X_VERSION>
pelo número da versão atual que encontrou no passo 1. Cada tipo de Pacote NuGet tem um número de versão exclusivo.Install-Package Microsoft.Extensions.Logging.Console -version <6_X_VERSION>
Na Consola do Gestor de Pacotes, preencha o número da versão atual e execute o comando. A lista de extensões é apresentada e é instalada automaticamente.
No separador Program.cs, adicione esta
using
instrução:using Microsoft.Extensions.Logging;
Continuando em Program.cs, adicione o
ConfigureLogging
método aHostBuilder
, antes doBuild
comando. OAddConsole
método adiciona o registo da consola à configuração.builder.ConfigureLogging((context, b) => { b.AddConsole(); });
O
Main
método tem agora o seguinte aspeto: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 efetua estas alterações:
- Desativa o registo do dashboard. O dashboard é uma ferramenta de monitorização legada e o registo de dashboards não é recomendado para cenários de produção de alto débito.
- Adiciona o fornecedor de consola com filtragem predefinida.
Agora, pode adicionar uma função que é acionada por mensagens que chegam numa fila do Armazenamento do Azure.
Adicionar uma função
Uma função é uma unidade de código que é executada numa agenda, é acionada com base em eventos ou é executada a pedido. Um acionador escuta um evento de serviço. No contexto do SDK webJobs, acionado não se refere ao modo de implementação. Os WebJobs agendados ou orientados por eventos criados com o SDK devem ser sempre implementados como WebJobs contínuos com "Always on" ativado.
Nesta secção, vai criar uma função acionada por mensagens numa fila do Armazenamento do Azure. Primeiro, tem de adicionar uma extensão de enlace para ligar ao Armazenamento do Azure.
Instalar a extensão de enlace do Armazenamento
A partir da versão 3 do SDK webJobs, para ligar aos serviços de Armazenamento do Azure, tem de instalar um pacote de extensão de enlace de armazenamento separado.
Nota
A partir de 5.x, Microsoft.Azure.WebJobs.Extensions.Storage foi dividido pelo serviço de armazenamento e migrou o AddAzureStorage()
método de extensão 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 seguinte comando, substitua
<5_X_VERSION>
pelo número da versão atual que encontrou no passo 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>
Na Consola do Gestor de Pacotes, execute o comando com o número da versão atual no
PM>
ponto de entrada.Continuando em Program.cs, no
ConfigureWebJobs
método de extensão, adicione oAddAzureStorageQueues
método naHostBuilder
instância (antes doBuild
comando) para inicializar a extensão de Armazenamento. Neste momento, o método tem oConfigureWebJobs
seguinte aspeto:builder.ConfigureWebJobs(b => { b.AddAzureStorageCoreServices(); b.AddAzureStorageQueues(); });
Adicione o seguinte código no
Main
método após abuilder
instanciação:builder.UseEnvironment(EnvironmentName.Development);
A execução no modo de desenvolvimento reduz o recuo exponencial das consultas de fila que pode atrasar significativamente o tempo necessário para que o runtime encontre a mensagem e invoque a função. Deve remover esta linha de código ou mudar para
Production
quando terminar o desenvolvimento e teste.O
Main
método deverá agora ter o 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 acionada por fila
O QueueTrigger
atributo indica ao runtime para chamar esta função quando uma nova mensagem é escrita numa fila do Armazenamento do Azure chamada queue
. Os conteúdos da mensagem de fila são fornecidos ao código do método no message
parâmetro . O corpo do método é onde processa os dados do acionador. Neste exemplo, o código apenas regista a mensagem.
Em Explorador de Soluções, clique com o botão direito do rato no projeto, selecione Adicionar>Novo Item e, em seguida, selecione Classe.
Atribua um nome ao novo ficheiro de classe C# Functions.cs e selecione 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); } } }
Deve marcar a classe Funções como
public static
para que o runtime aceda e execute o método. No exemplo de código acima, quando uma mensagem é adicionada a uma fila com o nomequeue
, a função é executada e amessage
cadeia é escrita nos registos. A fila que está a ser monitorizada encontra-se na conta de Armazenamento do Azure predefinida, que cria a seguir.
O message
parâmetro não tem de ser uma cadeia. Também pode vincular a um objeto JSON, a uma matriz de bytes ou a um objeto CloudQueueMessage .
Veja Utilização do acionador de fila. Cada tipo de enlace (como filas, blobs ou tabelas) tem um conjunto diferente de tipos de parâmetros aos quais pode vincular.
Criar uma conta de armazenamento do Azure
O Emulador de Armazenamento do Azure que é executado localmente não tem todas as funcionalidades de que o SDK do WebJobs precisa. Irá criar uma conta de armazenamento no Azure e configurar o projeto para o utilizar.
Para saber como criar uma conta de armazenamento v2 para fins gerais, veja Criar uma conta de Armazenamento do Azure.
Localizar e copiar a cadeia de ligação
É necessária uma cadeia de ligação para configurar o armazenamento. Mantenha esta cadeia de ligação para os próximos passos.
Na portal do Azure, navegue para a sua conta de armazenamento e selecione Definições.
Em Definições, selecione Chaves de acesso.
Para a Cadeia de ligação em key1, selecione o ícone Copiar para a área de transferência .
Configurar o armazenamento para ser executado localmente
O SDK do WebJobs procura a cadeia de ligação de armazenamento nas Definições da Aplicação no Azure. Quando é executado localmente, procura este valor no ficheiro de configuração local ou nas variáveis de ambiente.
Clique com o botão direito do rato no projeto, selecione Adicionar>Novo Item, selecione Ficheiro de configuração JSON javaScript, atribua um nome ao novo ficheiro appsettings.json e selecione Adicionar.
No novo ficheiro, adicione um
AzureWebJobsStorage
campo, tal como no exemplo seguinte:{ "AzureWebJobsStorage": "{storage connection string}" }
Substitua {storage connection string} pela cadeia de ligação que copiou anteriormente.
Selecione o ficheiro appsettings.json no Explorador de Soluções e, na janela Propriedades, defina a ação Copiar para Diretório de Saída como Copiar se for mais recente.
Uma vez que este ficheiro contém um segredo de cadeia de ligação, não deve armazenar o ficheiro num repositório de código remoto. Depois de publicar o projeto no Azure, pode adicionar a mesma definição de aplicação de cadeia de ligação na sua aplicação no Serviço de Aplicações do Azure.
Testar localmente
Crie e execute o projeto localmente e crie uma fila de mensagens para acionar a função.
Na portal do Azure, navegue para a sua conta de armazenamento e selecione o separador Filas (1). Selecione + Fila (2) e introduza 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, introduza Hello World! como texto da mensagem e, em seguida, selecione OK. Agora, existe uma mensagem na fila.
Prima Ctrl+F5 para executar o projeto.
A consola mostra que o runtime encontrou a função. Uma vez que utilizou o
QueueTrigger
atributo naProcessQueueMessage
função, o runtime do WebJobs escuta mensagens na fila com o nomequeue
. Quando encontra uma nova mensagem nesta fila, o runtime chama a função, transmitindo o valor da cadeia de mensagem.Voltar à janela Fila e atualize-a. A mensagem desapareceu, uma vez que foi processada pela sua função em execução localmente.
Feche a janela da consola.
Chegou o momento de publicar o seu projeto SDK de WebJobs no Azure.
Implementar no Azure
Durante a implementação, vai criar uma instância do serviço de aplicações onde irá executar as suas funções. Quando publica uma aplicação de consola .NET para Serviço de Aplicações no Azure, esta é executada automaticamente como um WebJob. Para saber mais sobre a publicação, veja Desenvolver e implementar WebJobs com o Visual Studio.
Criar recursos do Azure
No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.
Na caixa de diálogo Publicar , selecione Azure para Destino e, em seguida, selecione Seguinte.
Selecione WebJobs do Azure para Destino específico e, em seguida, selecione Seguinte.
Acima Serviço de Aplicações instâncias, selecione o botão de adição (+) para Criar um novo WebJob do Azure.
Na caixa de diálogo Serviço de Aplicações (Windows), utilize as definições de alojamento na tabela seguinte.
Definição Valor sugerido Descrição Nome Nome globalmente exclusivo Nome que identifica exclusivamente a sua nova aplicação de funções. Subscrição Escolher 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. Serviço de Aplicações planos definem a região, o tamanho da instância, a contagem de dimensionamento e o SKU (Gratuito, Partilhado, Básico, Standard ou Premium). Selecione Novo para criar um novo plano de Serviço de Aplicações. Os escalões Gratuito e Básico não suportam a opção AlwaysOn para manter o seu site em execução continuamente. Selecione Criar para criar um WebJob e recursos relacionados no Azure com estas definições e implemente o código do projeto.
Selecione Concluir para regressar à página Publicar .
Ativar o AlwaysOn
Para um WebJob contínuo, deve ativar a definição Alwayson no site para que os Seus WebJobs funcionem corretamente. Se não ativar o Always On, o runtime fica inativo após alguns minutos de inatividade.
Na página Publicar, selecione os três pontos acima de Alojamento para mostrar as ações da secção Perfil de alojamento e selecione Abrir no portal do Azure.
Em Definições, selecioneDefinições Gerais de Configuração>, defina Sempre ligado como Ligado e, em seguida, selecione Guardar e Continuar para reiniciar o site.
Publicar o projeto
Com a aplicação Web criada no Azure, está na altura de publicar o projeto WebJobs.
Na página Publicar em Alojamento, selecione o botão editar, altere o Tipo de WebJob para
Continuous
e selecione Guardar. Isto garante que o WebJob está em execução quando as mensagens são adicionadas à fila. Normalmente, os WebJobs acionados são utilizados apenas para webhooks manuais.Selecione o botão Publicar no canto superior direito da página Publicar . Quando a operação estiver concluída, o WebJob está em execução no Azure.
Criar uma definição de aplicação de ligação de armazenamento
Tem de criar a mesma definição de cadeia de ligação de armazenamento no Azure que utilizou localmente no ficheiro de configuração appsettings.json. Isto permite-lhe armazenar de forma mais segura a cadeia de ligação e
Na página Publicar perfil, selecione as reticências acima de Alojamento para mostrar as ações da secção Perfil de alojamento e selecione Gerir Serviço de Aplicações do Azure definições.
Em Definições da aplicação, selecione + Adicionar definição.
Em Novo nome da definição da aplicação, escreva
AzureWebJobsStorage
e selecione OK.Em Remoto, cole a cadeia de ligação a partir da definição local e selecione OK.
A cadeia de ligação está agora definida na sua aplicação no Azure.
Acionar a função no Azure
Certifique-se de que não está a ser executado localmente. Feche a janela da consola se ainda estiver aberta. Caso contrário, a instância local poderá ser a primeira a processar quaisquer mensagens de fila que criar.
Na página Fila no Visual Studio, adicione uma mensagem à fila como anteriormente.
Atualize a página Fila e a nova mensagem desaparece porque foi processada pela função em execução no Azure.
Ativar o registo do Application Insights
Quando o WebJob é executado no Azure, não pode monitorizar a execução de funções ao ver a saída da consola. Para poder monitorizar o Seu WebJob, deve criar uma instância do Application Insights associada quando publicar o seu projeto.
Criar uma instância do Application Insights
Na página Publicar perfil, selecione os três pontos acima de Alojamento para mostrar ações da secção Perfil de alojamento e selecione Abrir no Portal do Azure.
Na aplicação Web em Definições, selecione Application Insights e selecione Ativar o Application Insights.
Verifique o Nome do Recurso gerado para a instância e a Localização e selecione Aplicar.
Em Definições, selecione Configuração e verifique se foi criado um novo
APPINSIGHTS_INSTRUMENTATIONKEY
. Esta chave é utilizada para ligar a instância do WebJob ao Application Insights.
Para tirar partido do registo do Application Insights , também tem de atualizar o seu código de registo.
Instalar a 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 seguinte comando, substitua
<3_X_VERSION>
pelo número da versão atual que encontrou no passo 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>
Na Consola do Gestor de Pacotes, execute o comando com o número da versão atual no
PM>
ponto de entrada.
Inicializar o fornecedor de registos 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 deve agora ter o 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();
}
}
Isto inicializa o fornecedor de registos do Application Insights com filtragem predefinida. Ao executar localmente, todas as Informações e registos de nível superior são escritos na consola e no Application Insights.
Voltar a publicar o projeto e acionar a função novamente
No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.
Tal como anteriormente, utilize o portal do Azure para criar uma mensagem de fila como fez anteriormente, exceto introduza Hello App Insights! como o texto da mensagem.
Na página Publicar perfil, selecione os três pontos acima de Alojamento para mostrar ações da secção Perfil de alojamento e selecione Abrir no Portal do Azure.
Na aplicação Web em Definições, selecione Application Insights e selecione Ver dados do Application Insights.
Selecione Procurar e, em seguida, selecione Ver todos os dados nas últimas 24 horas.
Se não vir a mensagem Hello App Insights! , selecione Atualizar periodicamente durante vários minutos. Os registos não são apresentados imediatamente, porque o cliente do Application Insights demora algum tempo a remover os registos que processa.
Adicionar enlaces de entrada/saída
Os enlaces simplificam o código que lê e escreve dados. Os enlaces de entrada simplificam o código que lê dados. Os enlaces de saída simplificam o código que escreve dados.
Adicionar enlaces
Os enlaces de entrada simplificam o código que lê dados. Para este exemplo, a mensagem de fila é o nome de um blob, que irá utilizar para localizar e ler um blob no Armazenamento do Azure. Em seguida, irá utilizar enlaces de saída para escrever uma cópia do ficheiro no mesmo contentor.
Em Functions.cs, adicione um
using
:using System.IO;
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 enlace, o que significa que resolve para um valor diferente no runtime. No runtime, tem o conteúdo da mensagem de fila.Este código utiliza enlaces de saída para criar uma cópia do ficheiro identificado pela mensagem de fila. A cópia do ficheiro é prefixada com copy-.
Em Program.cs, no
ConfigureWebJobs
método de extensão, adicione oAddAzureStorageBlobs
método naHostBuilder
instância (antes doBuild
comando) para inicializar a extensão de Armazenamento. Neste momento, o método tem oConfigureWebJobs
seguinte aspeto:builder.ConfigureWebJobs(b => { b.AddAzureStorageCoreServices(); b.AddAzureStorageQueues(); b.AddAzureStorageBlobs(); });
Crie um contentor de blobs na sua conta de armazenamento.
a. No portal do Azure, navegue para o separador Contentores abaixo do Armazenamento de dados e selecione + Contentor
b. Na caixa de diálogo Novo contentor , introduza contentor como o nome do contentor e, em seguida, selecione Criar.
Carregue o ficheiro Program.cs para o contentor de blobs. (Este ficheiro é utilizado aqui como exemplo; pode carregar qualquer ficheiro de texto e criar uma mensagem de fila com o nome do ficheiro.)
a. Selecione o novo contentor que criou
b. Selecione o botão Carregar.
c. Localize e selecione Program.cs e, em seguida, selecione OK.
Voltar a publicar o projeto
No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar.
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 .
Crie uma mensagem de fila na fila que criou anteriormente, com Program.cs como o texto da mensagem.
Será apresentada uma cópia do ficheiro copy-Program.cs no contentor de blobs.
Passos seguintes
Este tutorial mostrou-lhe como criar, executar e implementar um projeto webJobs SDK 3.x.