Tutorial: Usar integrações de mensagens .NET Aspire no ASP.NET Core

Artigo
12/13/2024

Aplicativos nativos de nuvem geralmente exigem soluções de mensagens escalonáveis que fornecem recursos como filas de mensagens e tópicos e assinaturas. A integração do .NET Aspire simplifica o processo de conexão a diferentes provedores de mensagens, como Azure Service Bus. Neste tutorial, você criará um aplicativo ASP.NET Core que usa integrações .NET Aspire para se conectar a Azure Service Bus para criar um sistema de notificação. Mensagens submetidas serão enviadas para um tópico do Barramento de Serviço para serem consumidas por assinantes. Você aprenderá a:

Criar um aplicativo de .NET básico configurado para usar integrações .NET Aspire
Adicionar uma integração do tipo .NET Aspire para conectar-se a Azure Service Bus
Configurar e usar .NET.NET Aspire recursos de integração para enviar e receber dados

Pré-requisitos

Para trabalhar com .NET.NET Aspire, você precisa do seguinte instalado localmente:

.NET 8.0 ou .NET 9.0
Um runtime de contêiner compatível com OCI, como:
- Docker Desktop ou Podman. Para obter mais informações, consulte tempo de execução do contêiner.
Um IDE (Ambiente de Desenvolvedor Integrado) ou um editor de código, como:
- Visual Studio 2022 versão 17.9 ou superior (opcional)
- Visual Studio Code (opcional)
  - C# Dev Kit: Extensão (opcional)
- JetBrains Rider com .NET.NET Aspire plug-in (opcional)

Para obter mais informações, consulte .NET.NET Aspirede instalação e ferramentas e .NET.NET Aspiredo SDK.

Além dos pré-requisitos anteriores, você também precisa instalar a CLI do Azure. Para instalar o CLI Azure, siga as instruções no guia de instalação da CLI Azure.

Configurar a conta de Azure Service Bus

Para este tutorial, você precisará de acesso a um namespace Azure Service Bus com um tópico e uma assinatura configurados. Use uma das seguintes opções para configurar os recursos necessários:

Azure portal: Criar uma conta de barramento de serviço com um tópico e uma assinatura.

Alternativamente:

Azure CLI: execute os seguintes comandos na CLI Azure ou no CloudShell para configurar os recursos de Azure Service Bus necessários:

az group create -n <your-resource-group-name> --location eastus
az servicebus namespace create -g <your-resource-group-name> --name <your-namespace-name> --location eastus
az servicebus topic create -g <your-resource-group-name> --namespace-name <your-namespace-name> --name notifications
az servicebus topic subscription create -g <your-resource-group-name> --namespace-name <your-namespace-name> --topic-name notifications --name mobile

Nota

Substitua os espaços reservados seu-nome-de-grupo-de-recursos e seu-nome-de-namespace pelos seus próprios valores. Os nomes de namespace do Barramento de Serviço devem ser globalmente exclusivos em Azure.

autenticação Azure

Este início rápido pode ser concluído usando a autenticação sem senha ou uma cadeia de conexão. Conexões sem senha usam Azure Active Directory e RBAC (controle de acesso baseado em função) para se conectar a um namespace do Barramento de Serviço. Você não precisa se preocupar em ter uma cadeia de conexão codificada em código em seu código, um arquivo de configuração ou em um armazenamento seguro, como Azure Key Vault.

Você também pode usar uma cadeia de conexão para se conectar a um namespace do Barramento de Serviço, mas a abordagem sem senha é recomendada para aplicativos do mundo real e ambientes de produção. Para obter mais informações, leia sobre autenticação e autorização ou visite a página de visão geralsem senha.

Login sem senha (Recomendado)
cadeia de conexão

No namespace do Barramento de Serviço, atribua a seguinte função à conta de usuário com a qual você se conectou ao Visual Studio ou à CLI do Azure:

Proprietário de dados do Barramento de Serviço: atribuir uma função RBAC Azure

Criar a solução de exemplo

Para criar um novo aplicativo .NET Aspire Starter, você pode usar Visual Studio, Visual Studio Codeou a CLI do .NET.

Visual Studio fornece modelos .NET Aspire que cuidam de algumas configurações iniciais para você. Conclua as seguintes etapas para criar um projeto para este início rápido:

Na parte superior do Visual Studio, navegue até Arquivo>Novo>Projeto.
Na janela de diálogo, pesquise Aspire e selecione .NET.NET Aspire Aplicativo Inicial. Selecione Próximo.
Na tela , configure seu novo projeto:
- Insira um Nome do Projeto do AspireSample.
- Deixe o rest dos valores nas configurações padrão e selecione Avançar.
Na tela Informações adicionais:
- Verifique se .NET 9.0 (Suporte a Termos Padrão) está selecionado.
- Verifique se Usar Redis para cache (requer um runtime de contêiner com suporte) está marcado e selecione Criar.
- Opcionalmente, você pode selecionar Criar um projeto de testes. Para obter mais informações, consulte Escrever seu primeiro teste de .NET.NET Aspire.

Visual Studio cria uma nova solução que é estruturada para utilizar .NET Aspire.

Visual Studio Code fornece modelos de projeto .NET Aspire que lidam com algumas configurações iniciais para você. Conclua as seguintes etapas para criar um projeto para este início rápido:

Em uma nova instância de Visual Studio Code (sem uma pasta aberta), selecione o botão Criar projeto .NET.
Selecione o modelo de aplicativo .NET.NET Aspire Starter.

Se você ainda não tiver instalado os modelos de .NET.NET Aspire, execute o seguinte comando dotnet new install:

dotnet new install Aspire.ProjectTemplates

O comando da CLI .NET anterior garante que você tenha os modelos de .NET Aspire disponíveis. Para criar o aplicativo .NET.NET Aspire Starter a partir do modelo, execute o seguinte comando dotnet new:

dotnet new aspire-starter --use-redis-cache --output AspireSample

Para obter mais informações, consulte novodotnet . A CLI do .NET cria uma nova solução estruturada para usar .NET Aspire.

Adicionar o projeto Worker Service

Em seguida, adicione um projeto Worker Service à solução para recuperar e processar mensagens de e para Azure Service Bus.

No gerenciador de soluções, clique com o botão direito do mouse no nó de solução AspireSample no nível superior e selecione Adicionar>Novo projeto.
Pesquise e selecione o modelo de Worker Service e escolha Próximo.
Para o nome do projeto , insira AspireSample.WorkerService e selecione Próximo.
Na tela Informações adicionais:
- Verifique se .NET 9.0 está selecionado.
- Verifique se Inscrever-se em .NET.NET Aspire de orquestração está marcada e selecione Criar.

Visual Studio adiciona o projeto à sua solução e atualiza o arquivo Program.cs do projeto AspireSample.AppHost com uma nova linha de código:

builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");

Visual Studio ferramentas adicionaram essa linha de código para registrar seu novo projeto com o objeto IDistributedApplicationBuilder, que permite recursos de orquestração que você explorará mais tarde.

No do Gerenciador de Soluções no , selecione o botão ao lado do nome da solução para adicionar um novo projeto à solução:
Para filtrar os modelos de projeto, insira Worker na caixa de pesquisa e selecione o modelo Worker Service encontrado:
Escolha o modelo de Worker Service e insira o nome do projeto como AspireSample.WorkerService.
Selecione diretório padrão para criar o projeto no mesmo diretório que a solução.
Selecione Criar projeto para adicionar o projeto à solução.
Clique com o botão direito do mouse no projeto AspireSample.AppHost no Gerenciador de Soluções e selecione Adicionar Referência do Projeto:
Adicione a seguinte linha de código ao arquivo no projeto AspireSample.AppHost antes da chamada para :
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

No diretório raiz do aplicativo, use o comando dotnet new para criar um novo aplicativo Worker Service:
```
dotnet new worker --name AspireSample.WorkerService
```

Use o comando dotnet sln para adicionar o projeto à solução:

dotnet sln AspireSample.sln add AspireSample.WorkerService/AspireSample.WorkerService.csproj

Use o comando dotnet add para adicionar uma referência de projeto entre o .AppHost e o projeto .WorkerService.

dotnet add AspireSample.AppHost/AspireSample.AppHost.csproj reference AspireSample.WorkerService/AspireSample.WorkerService.csproj

Adicione a seguinte linha de código ao arquivo no projeto AspireSample.AppHost antes da chamada para :
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

A estrutura de solução concluída deve ser semelhante à seguinte, supondo que o diretório de nível superior seja denominado aspire-messaging:

└───📂 aspire-messaging
     ├───📂 AspireSample.WorkerService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.WorkerService.csproj
     │    ├─── Program.cs
     │    └─── Worker.cs
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Adicionar a integração .NET.NET Aspire à API

Adicione a integração .NET Aspire Azure Service Bus ao seu aplicativo AspireSample.ApiService:

Nodo Gerenciador de Soluções , clique duas vezes no arquivo AspireSample.ApiService.csproj para abrir seu arquivo XML.

Adicione o seguinte item de <PackageReference> ao elemento <ItemGroup>:

<ItemGroup>
    <PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                      Version="8.0.1" />
</ItemGroup>

Nodo Gerenciador de Soluções , clique com o botão direito do mouse no projeto AspireSample.ApiService e selecione Adicionar Pacote NuGet:
Insira Aspire.Azure. Messaging.ServiceBus na caixa de pesquisa e selecione o pacote na lista.
Selecione a versão (mais recente) para instalar o pacote.

dotnet add package Aspire.Azure.Messaging.ServiceBus

No arquivo Program.cs do projeto AspireSample.ApiService, adicione uma chamada ao método de extensão AddAzureServiceBusClient, substituindo a chamada existente para AddServiceDefaults:

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

Para obter mais informações, consulte AddAzureServiceBusClient.

Esse método realiza as seguintes tarefas:

Registra um ServiceBusClient no contêiner DI para se conectar ao Azure Service Bus.
Habilita automaticamente as verificações de integridade, o registro em log e a telemetria correspondentes para os respectivos serviços.

No arquivo appsettings.json do mesmo projeto, adicione as informações de conexão correspondentes:

sem uso de senha (recomendado)
cadeia de conexão

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
          SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

Nota

Substitua {your_namespace} nas URIs de serviço pelo nome do seu próprio namespace do Barramento de Serviço.

Criar o ponto de extremidade da API

A API deve fornecer um ponto de extremidade para receber dados e publicá-los no tópico do Barramento de Serviço e transmitir aos assinantes. Adicione o seguinte endpoint ao projeto AspireSample.ApiService para enviar uma mensagem ao tópico do Barramento de Serviço. Substitua todo o conteúdo do arquivo Program.cs pelo seguinte código C#:

using Azure.Messaging.ServiceBus;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

// Add services to the container.
builder.Services.AddProblemDetails();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

app.MapPost("/notify", static async (ServiceBusClient client, string message) =>
{
    var sender = client.CreateSender("notifications");

    // Create a batch
    using ServiceBusMessageBatch messageBatch =
        await sender.CreateMessageBatchAsync();

    if (messageBatch.TryAddMessage(
            new ServiceBusMessage($"Message {message}")) is false)
    {
        // If it's too large for the batch.
        throw new Exception(
            $"The message {message} is too large to fit in the batch.");
    }

    // Use the producer client to send the batch of
    // messages to the Service Bus topic.
    await sender.SendMessagesAsync(messageBatch);

    Console.WriteLine($"A message has been published to the topic.");
});

app.MapDefaultEndpoints();

app.Run();

Adicionar a integração .NET Aspire ao Worker Service

Adicione a integração .NET Aspire Azure Service Bus ao projeto AspireSample.WorkerService. Siga as mesmas etapas que você seguiu antes quando adicionou o pacote NuGet Aspire.Azure.Messaging.ServiceBus ao projeto AspireSample.ApiService. Depois que for adicionado, você pode configurar o serviço de trabalho para processar mensagens do tópico do Service Bus.

No arquivo Program.cs do projeto AspireSample.WorkerService, substitua o código existente com o seguinte:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

O método AddAzureServiceBusClient realiza as seguintes tarefas:

Registra um ServiceBusClient com o contêiner de DI para se conectar ao Azure Service Bus.
Habilita automaticamente as verificações de integridade, o registro em log e a telemetria correspondentes para os respectivos serviços.

No arquivo appsettings.json do projeto AspireSample.WorkerService, adicione as informações de conexão correspondentes:

Sem senha (recomendado)
cadeia de conexão

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
        SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

Nota

Certifique-se de substituir {your_namespace} nas URIs de Serviço pelo nome do seu namespace do Barramento de Serviço.

Processar a mensagem do assinante

Quando uma nova mensagem é colocada na fila de mensagens messages, o serviço de processamento deve recuperar, processar e excluir a mensagem. Atualize a classe Worker.cs para corresponder ao seguinte código:

using Azure.Messaging.ServiceBus;

namespace AspireSample.WorkerService;

public sealed class Worker(
    ILogger<Worker> logger,
    ServiceBusClient client) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var processor = client.CreateProcessor(
                "notifications",
                "mobile",
                new ServiceBusProcessorOptions());

            // Add handler to process messages
            processor.ProcessMessageAsync += MessageHandler;

            // Add handler to process any errors
            processor.ProcessErrorAsync += ErrorHandler;

            // Start processing
            await processor.StartProcessingAsync();

            logger.LogInformation("""
                Wait for a minute and then press any key to end the processing
                """);

            Console.ReadKey();

            // Stop processing
            logger.LogInformation("""

                Stopping the receiver...
                """);

            await processor.StopProcessingAsync();

            logger.LogInformation("Stopped receiving messages");
        }
    }

    async Task MessageHandler(ProcessMessageEventArgs args)
    {
        string body = args.Message.Body.ToString();

        logger.LogInformation("Received: {Body} from subscription.", body);

        // Complete the message. messages is deleted from the subscription.
        await args.CompleteMessageAsync(args.Message);
    }

    // Handle any errors when receiving messages
    Task ErrorHandler(ProcessErrorEventArgs args)
    {
        logger.LogError(args.Exception, "{Error}", args.Exception.Message);
        
        return Task.CompletedTask;
    }
}

Executar e testar o aplicativo localmente

O aplicativo de exemplo agora está pronto para teste. Verifique se os dados enviados à API são enviados para o tópico Azure Service Bus e consumidos pelo serviço de trabalho do assinante:

Inicie o projeto .NET.NET Aspire selecionando o botão de iniciar depuração ou pressionando F5 . O aplicativo de painel .NET.NET Aspire deve ser aberto no navegador.

Inicie o projeto de .NET.NET Aspire selecionando o botão Iniciar depuração ou pressionando F5. O aplicativo de painel .NET.NET Aspire deve ser aberto no navegador.

Inicie o projeto .NET.NET Aspire rodando dotnet run --project AspireSample.AppHost. O aplicativo de painel .NET.NET Aspire deve ser aberto no navegador.

Na página de recursos, na linha do apiservice, localize o link nos Endpoints que abre o endpoint weatherforecast. Observe o número da porta HTTPS.
No painel .NET.NET Aspire, navegue até os logs para o projeto aspiresample-workerservice.
Em uma janela de terminal, use o comando curl para enviar uma mensagem de teste à API:
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
Certifique-se de substituir {port} pelo número da porta fornecido anteriormente.
Volte para os logs de aspiresample-workerservice. Você deverá ver a mensagem de teste impressa nos logs de saída.

Parabéns! Você criou e configurou uma API de ASP.NET Core que se conecta a Azure Service Bus usando integrações Aspire.

Limpar recursos

Execute o seguinte comando Azure CLI para excluir o grupo de recursos quando você não precisar mais dos recursos de Azure que você criou. Excluir o grupo de recursos também exclui os recursos contidos nele.

az group delete --name <your-resource-group-name>

Para obter mais informações, consulte Liberar recursos no Azure.

Compartilhar via

Tutorial: Usar integrações de mensagens .NET Aspire no ASP.NET Core

Pré-requisitos

Configurar a conta de Azure Service Bus

autenticação Azure

Criar a solução de exemplo

Adicionar o projeto Worker Service

Adicionar a integração .NET.NET Aspire à API

Criar o ponto de extremidade da API

Adicionar a integração .NET Aspire ao Worker Service

Processar a mensagem do assinante

Executar e testar o aplicativo localmente

Limpar recursos

Recursos adicionais