Tutorial: Uso de integraciones de mensajería de .NET Aspire en ASP.NET Core

Las aplicaciones nativas de nube suelen requerir soluciones de mensajería escalables que proporcionan funcionalidades como colas de mensajería y temas y suscripciones. Las integraciones de .NET Aspire simplifican el proceso de conexión a varios proveedores de mensajería, como Azure Service Bus. En este tutorial, creará una aplicación de ASP.NET Core que usa integraciones de .NET Aspire para conectarse a Azure Service Bus para crear un sistema de notificaciones. Los mensajes enviados se enviarán a un tema de Service Bus para ser consumidos por los suscriptores. Aprenderá a:

Prerrequisitos

Para trabajar con .NET.NET Aspire, necesita lo siguiente instalado localmente:

• .NET 8.0 o .NET 9.0
• Un entorno de ejecución de contenedor compatible con OCI, como:
  • Docker de escritorio o Podman. Para obtener más información, consulte container runtime.
• Un entorno para desarrolladores integrado (IDE) o un editor de código, como:
  • Visual Studio 2022 versión 17.9 o posterior (opcional)
  • Visual Studio Code (opcional)
    • C# Dev Kit: extensión (opcional)
  • JetBrains Rider con .NET.NET Aspire plugin (opcional)

Para obtener más información, consulte configuración y herramientas de .NET.NET Aspirey sdk de .NET.NET Aspire.

Además de los requisitos previos anteriores, también debe instalar la CLI de Azure. Para instalar la CLI de Azure, siga las instrucciones de la guía de instalación de la CLI de Azure.

Configuración de la cuenta de Azure Service Bus

Para este tutorial, necesitará acceso a un espacio de nombres de Azure Service Bus con un tema y una suscripción ya configurados. Use una de las siguientes opciones para configurar los recursos necesarios:

• Azure portal: Crear una cuenta de Service Bus con un tema y una suscripción.

Alternativamente:

• Azure CLI: ejecute los siguientes comandos en la CLI de Azure o CloudShell para configurar los recursos Azure Service Bus necesarios:

  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

  Reemplace los marcadores de posición your-resource-group-name y your-namespace-name por sus propios valores. Los nombres de espacio de nombres de Service Bus deben ser globalmente únicos en Azure.

autenticación de Azure

Este inicio rápido se puede completar mediante la autenticación sin contraseña o una cadena de conexión. Las conexiones sin contraseña usan Azure Active Directory y el control de acceso basado en rol (RBAC) para conectarse a un espacio de nombres de Service Bus. No es necesario preocuparse por tener una cadena de conexión codificada de forma rígida en el código, un archivo de configuración o en un almacenamiento seguro, como Azure Key Vault.

También puede usar una cadena de conexión para conectarse a un espacio de nombres de Service Bus, pero se recomienda el enfoque sin contraseña para aplicaciones y entornos de producción reales. Para obtener más información, lea sobre de autenticación y autorización o visite la página de información general de sin contraseña.

Creación de la solución de ejemplo

Para crear una nueva aplicación de inicio de .NET Aspire, puede usar Visual Studio, Visual Studio Codeo la CLI de .NET.

dotnet new install Aspire.ProjectTemplates

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

Añadir el proyecto Worker Service

A continuación, agregue un proyecto de Worker Service a la solución para recuperar y procesar mensajes hacia y desde Azure Service Bus.

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

La estructura de solución completada debe ser similar a la siguiente, suponiendo que el directorio de nivel superior se denomina 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

Incorporación de la integración de .NET.NET Aspire a la API

Agregue la integración de .NET Aspire Azure Service Bus a su aplicación AspireSample.ApiService.

dotnet add package Aspire.Azure.Messaging.ServiceBus

En el archivo Program.cs del proyecto AspireSample.ApiService, agregue una llamada al método de extensión AddAzureServiceBusClient, reemplazando la llamada existente a AddServiceDefaults.

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

Para obtener más información, consulte AddAzureServiceBusClient.

Este método realiza las siguientes tareas:

• Registra un ServiceBusClient con el contenedor de DI para la conexión con Azure Service Bus.
• Habilita automáticamente las comprobaciones de estado, el registro y la telemetría correspondientes para los servicios respectivos.

En el archivo appsettings.json del mismo proyecto, agregue la información de conexión correspondiente:

{
  // 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"
  }
}

Creación del punto de conexión de API

La API debe proporcionar un punto de conexión para recibir datos y publicarlos en el tema de Service Bus y difundirlos a los suscriptores. Agregue el siguiente punto de conexión al proyecto de AspireSample.ApiService para enviar un mensaje al tema de Service Bus. Reemplace todo el contenido del archivo Program.cs por el siguiente código de 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();

Agregue la integración de .NET Aspire al Worker Service

Agregue la integración de .NET Aspire Azure Service Bus al proyecto de AspireSample.WorkerService. Siga los mismos pasos que siguió antes al agregar el paquete NuGet Aspire.Azure. Messaging.ServiceBus al proyecto AspireSample.ApiService. Una vez agregado, puede configurar el servicio de trabajo para procesar mensajes del tema de Service Bus.

En el archivo Program.cs del proyecto de AspireSample.WorkerService, reemplace el código existente con lo siguiente:

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

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

El método AddAzureServiceBusClient realiza las siguientes tareas:

• Registra un ServiceBusClient con el contenedor DI para conectarse a Azure Service Bus.
• Habilita automáticamente las comprobaciones de estado, el registro y la telemetría correspondientes para los servicios respectivos.

En el archivo appsettings.json del proyecto de AspireSample.WorkerService, agregue la información de conexión correspondiente:

{
  // 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"
  }
}

Procesar el mensaje del suscriptor

Cuando se coloca un nuevo mensaje en la cola de messages, el servicio de trabajo debe recuperar, procesar y eliminar el mensaje. Actualice la clase Worker.cs para que coincida con el código siguiente:

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;
    }
}

Ejecución y prueba local de la aplicación

La aplicación de ejemplo ya está lista para las pruebas. Compruebe que los datos enviados a la API se envían al tema de Azure Service Bus y los consume el servicio de trabajo del suscriptor:

2. En la página de recursos, en la fila de apiservice , busque el enlace en los puntos de conexión que abre el endpoint weatherforecast. Anote el número de puerto HTTPS.

3. En el panel de .NET.NET Aspire, vaya a los registros del proyecto de aspiresample-workerservice.

4. En una ventana de terminal, use el comando curl para enviar un mensaje de prueba a la API:

   curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
   

   Asegúrese de reemplazar {port} por el número de puerto anterior.

5. Vuelva a los registros de aspiresample-workerservice. Debería ver el mensaje de prueba impreso en los registros de salida.

¡Felicidades! Ha creado y configurado una API de ASP.NET Core que se conecta a Azure Service Bus mediante integraciones de Aspire.

Limpieza de recursos

Ejecute el siguiente comando Azure CLI para eliminar el grupo de recursos cuando ya no necesite los recursos de Azure que creó. Al eliminar el grupo de recursos también se eliminan los recursos contenidos en él.

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

Para obtener más información, consulte Limpieza de recursos en Azure.