integración de .NET AspireAzure Service Bus

Artículo
02/27/2025

incluye: integración de hospedaje de e integración de Client

Azure Service Bus es un broker de mensajes empresarial totalmente administrado con colas de mensajes y tópicos de publicación y suscripción. La integración de .NET AspireAzure Service Bus permite conectarse a instancias de Azure Service Bus desde aplicaciones de .NET.

Integración de hospedaje

La integración de hospedaje de .NET.NET AspireAzure Service Bus modela los distintos recursos de Service Bus como los siguientes tipos:

AzureServiceBusResource: Representa un recurso de Azure Service Bus.
AzureServiceBusEmulatorResource: representa un recurso del emulador de Azure Service Bus.

Para acceder a estos tipos y API para expresarlos, agregue el paquete NuGet 📦Aspire.Hosting.Azure.ServiceBus en el proyecto host de la aplicación.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

<PackageReference Include="Aspire.Hosting.Azure.ServiceBus"
                  Version="*" />

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en aplicaciones .NET.

Agregar Azure Service Bus recurso

En el proyecto anfitrión de la aplicación, utilice AddAzureServiceBus para agregar y devolver un recurso constructor de Azure Service Bus.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");

// After adding all resources, run the app...

Al agregar un AzureServiceBusResource al host de la aplicación, expone otras API útiles para agregar colas y temas. En otras palabras, debe agregar un AzureServiceBusResource antes de agregar cualquier otro recurso de Service Bus.

Importante

Al llamar a AddAzureServiceBus, llama implícitamente a AddAzureProvisioning, lo que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, vea Configuración.

Aprovisionamiento generado de Bicep

Si eres nuevo en Bicep, es un lenguaje específico del dominio para definir recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar tu aplicación, el Bicep generado se muestra junto al archivo de manifiesto. Al agregar un recurso Azure Service Bus, se genera la siguiente Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param sku string = 'Standard'

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: take('servicebus-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'service-bus'
  }
}

resource service_bus_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(service_bus.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: service_bus
}

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

Bicep anterior es un módulo que aprovisiona un espacio de nombres Azure Service Bus con los valores predeterminados siguientes:

sku: El SKU del espacio de nombres de Service Bus. El valor predeterminado es Estándar.
location: la ubicación del espacio de nombres de Service Bus. El valor predeterminado es la ubicación del grupo de recursos.

Además del espacio de nombres de Service Bus, Azure también aprovisiona un rol integrado de control de acceso basado en rol (Azure RBAC) de Azure Service Bus Propietario de datos. El rol se asigna al grupo de recursos del espacio de nombres de Service Bus. Para obtener más información, consulte Azure Service Bus Propietario de Datos.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo habilita la personalización del Bicep generado, proporcionando una API fluida para configurar los recursos de Azure utilizando la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar la SKU, la ubicación y mucho más. En el ejemplo siguiente se muestra cómo personalizar el recurso de Azure Service Bus:

builder.AddAzureServiceBus("service-bus")
    .ConfigureInfrastructure(infra =>
    {
        var serviceBusNamespace = infra.GetProvisionableResources()
                                       .OfType<ServiceBusNamespace>()
                                       .Single();

        serviceBusNamespace.Sku = new ServiceBusSku
        {
            Tier = ServiceBusSkuTier.Premium
        };
        serviceBusNamespace.Tags.Add("ExampleKey", "Example value");
    });

El código anterior:

Encadena una llamada a API ConfigureInfrastructure:
- El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
- Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
- Se recupera el único ServiceBusNamespace.
- El ServiceBusNamespace.Sku creado con un ServiceBusSkuTier.Premium
- Se agrega una etiqueta al espacio de nombres de Service Bus con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso de Azure Service Bus. Para obtener más información, consulte Azure.Provisioning.ServiceBus. Para obtener más información, vea Azure. Personalización del aprovisionamiento.

Conexión a un espacio de nombres de Azure Service Bus existente

Es posible que tenga un espacio de nombres Azure Service Bus existente al que desea conectarse. En lugar de representar un nuevo recurso de Azure Service Bus, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a un espacio de nombres de Azure Service Bus existente, llame al método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddConnectionString("messaging");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(serviceBus);

// After adding all resources, run the app...

Nota

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en secretos de usuario, en la sección ConnectionStrings. El host de la aplicación inserta esta cadena de conexión como una variable de entorno en todos los recursos dependientes, por ejemplo:

{
    "ConnectionStrings": {
        "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key_value};"
    }
}

El recurso dependiente puede acceder a la cadena de conexión insertada llamando al método GetConnectionString y pasando el nombre de conexión como parámetro, en este caso "messaging". La API de GetConnectionString es una abreviación de IConfiguration.GetSection("ConnectionStrings")[name].

Agregar la cola Azure Service Bus

Para agregar una cola Azure Service Bus, llame al método AddServiceBusQueue en el IResourceBuilder<AzureServiceBusResource>.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusQueue("queue");

// After adding all resources, run the app...

Al llamar a AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String), configura los recursos de Service Bus para que tengan una cola denominada queue. La cola se crea en el espacio de nombres de Service Bus representado por el identificador AzureServiceBusResource que agregó anteriormente. Para obtener más información, vea Colas, temas y suscripciones en Azure Service Bus.

Agregar Azure Service Bus tema y suscripción

Para agregar un tema de Azure Service Bus, llame al método AddServiceBusTopic en el IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusTopic("topic");

// After adding all resources, run the app...

Al llamar a AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String), configura los recursos de Service Bus para que tengan un tema denominado topic. El tema se crea en el espacio de nombres del Service Bus representado por el AzureServiceBusResource que agregó anteriormente.

Para agregar una suscripción al tema, llame al método AddServiceBusSubscription en el IResourceBuilder<AzureServiceBusTopicResource> y configúrelo mediante el método WithProperties:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
var topic = serviceBus.AddServiceBusTopic("topic");
topic.AddServiceBusSubscription("sub1")
     .WithProperties(subscription =>
     {
         subscription.MaxDeliveryCount = 10;
         subscription.Rules.Add(
             new AzureServiceBusRule("app-prop-filter-1")
             {
                 CorrelationFilter = new()
                 {
                     ContentType = "application/text",
                     CorrelationId = "id1",
                     Subject = "subject1",
                     MessageId = "msgid1",
                     ReplyTo = "someQueue",
                     ReplyToSessionId = "sessionId",
                     SessionId = "session1",
                     SendTo = "xyz"
                 }
             });
     });

// After adding all resources, run the app...

El código anterior no solo agrega un tema y crea y configura una suscripción denominada sub1 para el tema. La suscripción tiene un recuento máximo de entregas de 10 y una regla denominada app-prop-filter-1. La regla es un filtro de correlación que filtra los mensajes en función de las propiedades ContentType, CorrelationId, Subject, MessageId, ReplyTo, ReplyToSessionId, SessionIdy SendTo.

Para obtener más información, vea Colas, temas y suscripciones en Azure Service Bus.

Adición de un recurso del emulador de Azure Service Bus

Para añadir un recurso de emulador de Azure Service Bus, realiza una llamada a la API de RunAsEmulator desde un <IResourceBuilder<AzureServiceBusResource>>.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsEmulator();

// After adding all resources, run the app...

Al llamar a RunAsEmulator, configura los recursos de Service Bus para que se ejecuten localmente mediante un emulador. En este caso, el emulador es Azure Service Bus Emulator. El emulador de Azure Service Bus proporciona un entorno local gratuito para probar las aplicaciones de Azure Service Bus y es un complemento perfecto para la integración de hospedaje .NET AspireAzure. El emulador no está instalado, sino que es accesible para .NET.NET Aspire como contenedor. Al agregar un contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de mcr.microsoft.com/azure-messaging/servicebus-emulator (y la imagen de mcr.microsoft.com/azure-sql-edge complementaria), crea e inicia el contenedor cuando se inicia el host de la aplicación. Para obtener más información, consulte Ciclo de vida de los recursos de contenedores.

Configuración del contenedor del emulador de Service Bus

Hay varias configuraciones disponibles para los recursos del contenedor, por ejemplo, puede configurar los puertos del contenedor o proporcionar una configuración holística JSON que invalida todo.

Configuración del puerto de host del contenedor del emulador de Service Bus

De forma predeterminada, el contenedor del emulador de Service Bus cuando lo configura .NET.NET Aspire, expone los siguientes puntos de conexión:

Punto final	Imagen	Puerto de contenedor	Puerto de acogida
`emulator`	`mcr.microsoft.com/azure-messaging/servicebus-emulator`	5672	dinámico
`tcp`	`mcr.microsoft.com/azure-sql-edge`	1433	dinámico

El puerto en el que está escuchando es dinámico de forma predeterminada. Cuando se inicia el contenedor, el puerto se asigna a un puerto aleatorio en el equipo host. Para configurar el puerto de punto de conexión, encadene llamadas en el generador de recursos de contenedor proporcionado por el método RunAsEmulator y, a continuación, el WithHostPort(IResourceBuilder<AzureServiceBusEmulatorResource>, Nullable<Int32>) como se muestra en el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(7777);
                         });

// After adding all resources, run the app...

El código anterior configura el punto de conexión existente emulator del emulador de Service Bus para escuchar en el puerto 7777. El puerto del contenedor del emulador de Service Bus se asigna al puerto host, como se muestra en la tabla siguiente:

Nombre del punto de conexión	Asignación de puertos (`container:host`)
`emulator`	`5672:7777`

Configurar la configuración del contenedor del emulador de Service Bus JSON

El contenedor del emulador de Service Bus se ejecuta con un archivo de config.json predeterminado. Puede invalidar este archivo por completo o actualizar la configuración de JSON con una representación JsonNode de la configuración.

Para proporcionar un archivo de configuración de JSON personalizado, llame al método WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfigurationFile(
                                 path: "./messaging/custom-config.json");
                         });

El código anterior configura el contenedor del emulador de Service Bus para usar un archivo de configuración de JSON personalizado ubicado en ./messaging/custom-config.json. Para invalidar propiedades específicas en la configuración predeterminada, llame al método WithConfiguration(IResourceBuilder<AzureServiceBusEmulatorResource>, Action<JsonNode>):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfiguration(
                                 (JsonNode configuration) =>
                                 {
                                     var userConfig = configuration["UserConfig"];
                                     var ns = userConfig["Namespaces"][0];
                                     var firstQueue = ns["Queues"][0];
                                     var properties = firstQueue["Properties"];
                                     
                                     properties["MaxDeliveryCount"] = 5;
                                     properties["RequiresDuplicateDetection"] = true;
                                     properties["DefaultMessageTimeToLive"] = "PT2H";
                                 });
                         });

// After adding all resources, run the app...

El código anterior recupera el nodo UserConfig de la configuración predeterminada. A continuación, actualiza las propiedades de la primera cola para establecer el MaxDeliveryCount en 5, RequiresDuplicateDetection en truey DefaultMessageTimeToLive en 2 hours.

Comprobaciones de estado de la integración de hospedaje

La integración de alojamiento Azure Service Bus agrega automáticamente una comprobación de estado para el recurso de Service Bus. La comprobación de estado verifica que el Service Bus está en funcionamiento y que se puede establecer una conexión con él.

La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.AzureServiceBus.

integración de Client

Para empezar a trabajar con la integración del cliente .NET AspireAzure Service Bus, instale el paquete NuGet 📦Aspire.Azure.Messaging.ServiceBus en el proyecto consumidor del cliente, es decir, el proyecto de la aplicación que utiliza el cliente de Service Bus. La integración del cliente de Service Bus registra una instancia de ServiceBusClient que puede usar para interactuar con Service Bus.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Agregar cliente de Service Bus

En el archivo Program.cs de su proyecto que usa el cliente, invoque el método de extensión AddAzureServiceBusClient en cualquier IHostApplicationBuilder para registrar un ServiceBusClient a utilizar mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddAzureServiceBusClient(connectionName: "messaging");

Consejo (if the meaning of "Tip" is advice or suggestion)

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de Service Bus en el proyecto host de la aplicación. Es decir, cuando se llama a AddAzureServiceBus y se proporciona un nombre de messaging ese mismo nombre se debe usar al llamar a AddAzureServiceBusClient. Para obtener más información, consulte Agregar Azure Service Bus recurso.

A continuación, puede recuperar la instancia ServiceBusClient usando la inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(ServiceBusClient client)
{
    // Use client...
}

Para obtener más información sobre la inyección de dependencias, consulte .NET inyección de dependencias.

Adición de un cliente de Service Bus con clave

Puede haber situaciones en las que quiera registrar varias instancias de ServiceBusClient con nombres de conexión diferentes. Para registrar clientes de Service Bus con claves, llame al método AddKeyedAzureServiceBusClient:

builder.AddKeyedAzureServiceBusClient(name: "mainBus");
builder.AddKeyedAzureServiceBusClient(name: "loggingBus");

Importante

Cuando se usan servicios con claves, se espera que el recurso de Service Bus configure dos buses con nombre, uno para el mainBus y otro para el loggingBus.

A continuación, puede recuperar las instancias de ServiceBusClient usando inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient,
    [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient)
{
    // Use clients...
}

Para obtener más información sobre los servicios con clave, consulte .NET Inserción de Dependencias: Servicios con Clave.

Configuración

La integración de .NET AspireAzure Service Bus proporciona varias opciones para configurar la conexión en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar al método AddAzureServiceBusClient:

builder.AddAzureServiceBusClient("messaging");

A continuación, se obtiene la cadena de conexión de la sección de configuración ConnectionStrings.

{
  "ConnectionStrings": {
    "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};"
  }
}

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte la documentación de ConnectionString.

Uso de proveedores de configuración

La integración de .NET AspireyAzure Service Bus es compatible con Microsoft.Extensions.Configuration. Carga el AzureMessagingServiceBusSettings desde la configuración usando la clave Aspire:Azure:Messaging:ServiceBus. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};",
          "DisableTracing": false
        }
      }
    }
  }
}

Para el esquema completo de integración del cliente de Service Bus JSON, consulte Aspire.Azure. Messaging.ServiceBus/ConfigurationSchema.json.

Utilice delegados en línea

También puede pasar el delegado Action<AzureMessagingServiceBusSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar el seguimiento desde el código:

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.DisableTracing = true);

También puede configurar el Azure.Messaging.ServiceBus.ServiceBusClientOptions mediante el parámetro opcional Action<ServiceBusClientOptions> configureClientOptions del método AddAzureServiceBusClient. Por ejemplo, para establecer el sufijo del encabezado de agente de usuario ServiceBusClientOptions.Identifier para todas las solicitudes emitidas por este cliente:

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => clientOptions.Identifier = "myapp");

Client comprobaciones de salud de integración

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan el monitoreo de salud para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de .NET AspireAzure Service Bus:

Agrega la comprobación de estado cuando AzureMessagingServiceBusSettings.DisableTracing es false, que intenta conectarse a Service Bus.
Se integra con el endpoint HTTP de /health, el cual especifica que todas las comprobaciones de estado registradas deben superarse para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente el registro, la trazabilidad y las métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección configuración.

Registro

La integración de .NET AspireAzure Service Bus usa las siguientes categorías de registro:

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Además de obtener diagnósticos de solicitudes con errores Azure Service Bus, puede configurar umbrales de latencia para determinar qué diagnósticos de solicitudes exitosas se registrarán Azure Service Bus. Los valores predeterminados son 100 ms para las operaciones de punto y 500 ms para las operaciones que no son de punto.

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => {
            clientOptions.ServiceBusClientTelemetryOptions = new()
            {
                ServiceBusThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Rastreo

La integración de .NET AspireAzure Service Bus emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

Azure Service Bus seguimientos se encuentra actualmente en versión preliminar, por lo que debe activar el interruptor experimental para asegurarse de que se emiten trazas.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Para obtener más información, consulte Azure Service Bus: Seguimiento distribuido y correlación a través de la mensajería de Service Bus.

Métricas

La integración de .NET AspireAzure Service Bus actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure.

Consulte también

Azure Service Bus
resumen de las integraciones de .NET.NET Aspire
resumen de las integraciones de .NET AspireAzure
.NET Aspire GitHub del repositorio

Compartir a través de