Introducción a los temas y las suscripciones de Azure Service Bus

Artículo
10/19/2021
16 minutos para leer

En este artículo de inicio rápido se muestra cómo enviar mensajes a un tema de Service Bus y recibir mensajes de una suscripción a ese tema mediante la biblioteca Azure.Messaging.ServiceBus de .NET.

En este inicio rápido, hará lo siguiente:

Creación de un espacio de nombres de Service Bus mediante Azure Portal
Creación de un tema de Service Bus mediante Azure Portal.
Creación de una suscripción de Service Bus a dicho tema mediante Azure Portal.
Escriba una aplicación de consola de .NET Core para enviar un conjunto de mensajes al tema.
Escriba una aplicación de consola de .NET Core para recibir esos mensajes de la suscripción.

Nota

En este inicio rápido se proporcionan instrucciones detalladas para un escenario sencillo de envío de un lote de mensajes a un tema de Service Bus y recepción de esos mensajes desde una suscripción del tema. Puede encontrar más ejemplos pregenerados de .NET para Azure Service Bus en el repositorio del SDK de Azure para .NET en GitHub.

Prerrequisitos

Si no está familiarizado con el servicio, consulte la información general sobre Service Bus antes de seguir este artículo de inicio rápido.

Suscripción de Azure. Para usar los servicios de Azure, entre los que se incluye Azure Service Bus, se necesita una suscripción. Si no se dispone de una cuenta de Azure, es posible registrarse para obtener una evaluación gratuita, o bien usar las ventajas que disfrutan los suscriptores MSDN al crear una cuenta.
Microsoft Visual Studio 2019. La biblioteca cliente de Azure Service Bus usa las nuevas características que se introdujeron en C# 8.0. Aunque puede seguir usando la biblioteca con versiones anteriores de C#, la nueva sintaxis no estará disponible. Para usar la sintaxis completa, se recomienda realizar la compilación con el SDK de .NET Core 3.0 o superior y la versión de lenguaje establecida en latest. Si usa Visual Studio, las versiones anteriores a Visual Studio 2019 no son compatibles con las herramientas necesarias para compilar proyectos de C# 8.0. Visual Studio 2019, incluida la edición gratuita Community, se puede descargar aquí.

Creación de un espacio de nombres en Azure Portal

Para empezar a usar entidades de mensajería de Service Bus en Azure, primero hay que crear un espacio de nombres con un nombre que sea único en Azure. Un espacio de nombres proporciona un contenedor con un ámbito para el desvío de recursos de Service Bus en la aplicación.

Para crear un espacio de nombres:

Inicie sesión en el Portal de Azure
En el panel de navegación izquierdo del portal, seleccione sucesivamente + Crear un recurso, Integración y Service Bus.
En la pestaña Datos básicos de la página Crear espacio de nombres, siga estos pasos:
1. En Suscripción, elija la suscripción de Azure en la que se va a crear el espacio de nombres.
2. En Grupo de recursos, elija un grupo de recursos existente en el que residirá el espacio de nombres o cree uno.
3. Escriba nombre para el espacio de nombres. El sistema realiza la comprobación automáticamente para ver si el nombre está disponible. Para obtener una lista de las reglas para asignar nombres a los espacios de nombres, consulte Creación de API REST de espacio de nombres.
4. En Ubicación, elija la región donde se debe hospedar el espacio de nombres.
5. En Plan de tarifa, seleccione el plan de tarifa (Básico, Estándar o Prémium) del espacio de nombres. Para este inicio rápido, seleccione Estándar.
  
  Si desea usar temas y suscripciones, elija Estándar o Premium. El plan de tarifas Básico no admite temas o suscripciones.
  
  Si ha seleccionado el plan de tarifa Prémium, especifique el número de unidades de mensajería. El plan Premium proporciona aislamiento de recursos en el nivel de CPU y memoria para que cada carga de trabajo se ejecute de forma aislada. Este contenedor de recursos se llama unidad de mensajería. A cada espacio de nombres prémium se le asigna al menos una unidad de mensajería. Puede seleccionar 1, 2 o 4 unidades de mensajería para cada espacio de nombres Premium de Service Bus. Para más información, consulte Mensajería prémium de Service Bus.
6. Seleccione Revisar + crear. El sistema crea ahora el espacio de nombres del servicio y lo habilita. Es posible que tenga que esperar algunos minutos mientras el sistema realiza el aprovisionamiento de los recursos para la cuenta.
7. En la página Revisar y crear, examine la configuración y seleccione Crear.
Seleccione Ir al recurso en la página de implementación.
Verá la página principal del espacio de nombres de Service Bus.

Obtención de la cadena de conexión

La creación un espacio de nombres genera automáticamente una directiva de firma de acceso compartido (SAS) inicial con claves principal y secundaria, y cadenas de conexión principal y secundaria en el que ambas conceden control total sobre todos los aspectos del espacio de nombres. Para obtener información acerca de cómo crear reglas adicionales con derechos más restringidos para remitentes y destinatarios normales, consulte Autenticación y autorización de Service Bus.

Para copiar la cadena de conexión principal del espacio de nombres, siga estos pasos:

En la página Espacio de nombres de Service Bus, seleccione Directivas de acceso compartido en el menú de la izquierda.
En la página Directivas de acceso compartido, seleccione RootManageSharedAccessKey.
En la ventana Directiva: RootManageSharedAccessKey, haga clic en el botón Copiar que hay junto a Cadena de conexión principal para copiar la cadena de conexión en el portapapeles para su uso posterior. Pegue este valor en el Bloc de notas o cualquier otra ubicación temporal.

Puede usar esta página para copiar la clave principal, la clave secundaria y la cadena de conexión secundaria.

Creación de un tema mediante Azure Portal

En la página Espacio de nombres de Service Bus, seleccione Temas en el menú izquierdo.
En la barra de herramientas, seleccione + Tema.
Escriba un nombre para el tema. Deje las restantes opciones con sus valores predeterminados.
Seleccione Crear.

Creación de una suscripción al tema

Seleccione el tema que creó en la sección anterior.
En la página Tema de Service Bus, seleccione Suscripción en la barra de herramientas.
En la página Crear suscripción, siga estos pasos:
1. Escriba S1 como nombre de la suscripción.
2. Escriba 3 en Max delivery count (Número máximo de entregas).
3. Luego, seleccione Create (Crear) para guardar la suscripción.

Importante

Anote la cadena de conexión al espacio de nombres, el nombre del tema y el nombre de la suscripción. Los usará más adelante en este tutorial.

Envío de mensajes al tema

En esta sección se muestra cómo crear una aplicación de consola de .NET Core para mensajes a un tema de Service Bus.

Creación de una aplicación de consola

Inicie Visual Studio 2019.
Seleccione Crear un proyecto.
En el cuadro de diálogo Crear un nuevo proyecto, siga estos pasos: Si no ve este cuadro de diálogo, seleccione Archivo en el menú, seleccione Nuevo y, después, seleccione Proyecto.
1. Seleccione C# como lenguaje de programación.
2. Seleccione Consola como tipo de aplicación.
3. Seleccione Aplicación de consola en la lista de resultados.
4. Después, seleccione Siguiente.
Escriba TopicSender como nombre del proyecto, ServiceBusTopicQuickStart como nombre de la solución y, a continuación, seleccione Siguiente.
En la página Información adicional, seleccione Crear para crear la solución y el proyecto.

Agregar el paquete NuGet de Service Bus

Seleccione Herramientas > Administrador de paquetes NuGet > Consola del Administrador de paquetes en el menú.
Ejecute el siguiente comando para instalar el paquete NuGet Azure.Messaging.ServiceBus:
```
Install-Package Azure.Messaging.ServiceBus
```

Incorporación de código para enviar mensajes al tema

En Program.cs, agregue las siguientes instrucciones using en la parte superior de la definición del espacio de nombres, antes de la declaración de clase.
```
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
```

Dentro de la clase Program, declare las siguientes propiedades, justo antes del método Main. Reemplace <NAMESPACE CONNECTION STRING> por la cadena de conexión del espacio de nombres de Service Bus. Y reemplace <TOPIC NAME> por el nombre del tema de Service Bus.

// connection string to your Service Bus namespace
static string connectionString = "<NAMESPACE CONNECTION STRING>";

// name of your Service Bus topic
static string topicName = "<TOPIC NAME>";

// the client that owns the connection and can be used to create senders and receivers
static ServiceBusClient client;

// the sender used to publish messages to the topic
static ServiceBusSender sender;

// number of messages to be sent to the topic
private const int numOfMessages = 3;

Reemplace el código del archivo Program.cs por el código siguiente. Estos son los pasos importantes del código.

Crea un objeto ServiceBusClient mediante la cadena de conexión al espacio de nombres.
Invoca al método CreateSender en el objeto ServiceBusClient para crear un objeto ServiceBusSender para el tema específico de Service Bus.
Crea un objeto ServiceBusMessageBatch mediante ServiceBusSender.CreateMessageBatchAsync.
Agrega mensajes al lote mediante ServiceBusMessageBatch.TryAddMessage.
Envía el lote de mensajes al tema de Service Bus mediante el método ServiceBusSender.SendMessagesAsync.

static async Task Main()
{
    // The Service Bus client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when messages are being published or read
    // regularly.
    //
    // Create the clients that we'll use for sending and processing messages.
    client = new ServiceBusClient(connectionString);
    sender = client.CreateSender(topicName);

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

    for (int i = 1; i <= numOfMessages; i++)
    {
        // try adding a message to the batch
        if (!messageBatch.TryAddMessage(new ServiceBusMessage($"Message {i}")))
        {
            // if it is too large for the batch
            throw new Exception($"The message {i} is too large to fit in the batch.");
        }
    }

    try
    {
        // Use the producer client to send the batch of messages to the Service Bus topic
        await sender.SendMessagesAsync(messageBatch);
        Console.WriteLine($"A batch of {numOfMessages} messages has been published to the topic.");
    }
    finally
    {
        // Calling DisposeAsync on client types is required to ensure that network
        // resources and other unmanaged objects are properly cleaned up.
        await sender.DisposeAsync();
        await client.DisposeAsync();
    }

    Console.WriteLine("Press any key to end the application");
    Console.ReadKey();
}

Este es el aspecto que debería tener el archivo Program.cs:

Para más información, consulte los comentarios del código.

using System;
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;

namespace TopicSender
{
    class Program
    {
        // connection string to your Service Bus namespace
        static string connectionString = "<NAMESPACE CONNECTION STRING>";

        // name of your Service Bus topic
        static string topicName = "<TOPIC NAME>";

        // the client that owns the connection and can be used to create senders and receivers
        static ServiceBusClient client;

        // the sender used to publish messages to the topic
        static ServiceBusSender sender;

        // number of messages to be sent to the topic
        private const int numOfMessages = 3;

        static async Task Main()
        {
            // The Service Bus client types are safe to cache and use as a singleton for the lifetime
            // of the application, which is best practice when messages are being published or read
            // regularly.
            //
            // Create the clients that we'll use for sending and processing messages.
            client = new ServiceBusClient(connectionString);
            sender = client.CreateSender(topicName);

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

            for (int i = 1; i <= numOfMessages; i++)
            {
                // try adding a message to the batch
                if (!messageBatch.TryAddMessage(new ServiceBusMessage($"Message {i}")))
                {
                    // if it is too large for the batch
                    throw new Exception($"The message {i} is too large to fit in the batch.");
                }
            }

            try
            {
                // Use the producer client to send the batch of messages to the Service Bus topic
                await sender.SendMessagesAsync(messageBatch);
                Console.WriteLine($"A batch of {numOfMessages} messages has been published to the topic.");
            }
            finally
            {
                // Calling DisposeAsync on client types is required to ensure that network
                // resources and other unmanaged objects are properly cleaned up.
                await sender.DisposeAsync();
                await client.DisposeAsync();
            }

            Console.WriteLine("Press any key to end the application");
            Console.ReadKey();
        }
    }
}

Reemplace <NAMESPACE CONNECTION STRING> por la cadena de conexión del espacio de nombres de Service Bus. Y reemplace <TOPIC NAME> por el nombre del tema de Service Bus.
Compile el proyecto y asegúrese de que no hay errores.
Ejecute el programa y espere el mensaje de confirmación.
```
A batch of 3 messages has been published to the topic
```
En Azure Portal, haga lo siguiente:
1. Vaya al espacio de nombres de Service Bus.
2. En la página Información general, en el panel inferior central, cambie a la pestaña Temas y seleccione el tema de Service Bus. En el ejemplo siguiente, es mytopic.
3. En la página Tema de Service Bus, en el gráfico Mensajes de la sección Métricas inferior, puede ver que hay tres mensajes entrantes para la cola. Si no ve el valor, espere unos minutos y actualice la página para ver el gráfico actualizado.
4. Seleccione la suscripción en el panel inferior. En el ejemplo siguiente, es S1. En la página Suscripción de Service Bus, verá el Recuento de mensajes activos como 3. La suscripción ha recibido los tres mensajes que ha enviado al tema, pero ningún receptor los ha recogido todavía.

Recepción de mensajes de una suscripción

En esta sección, creará una aplicación de consola de .NET Core que recibe mensajes de la suscripción al tema de Service Bus.

Creación de un proyecto para el destinatario

En la ventana del Explorador de soluciones, haga clic con el botón derecho en la solución ServiceBusTopicQuickStart, haga clic en Agregar y seleccione Nuevo proyecto.
Seleccione Aplicación de consola y seleccione Siguiente.
Escriba SubscriptionReceiver como Nombre del proyecto y seleccione Siguiente.
En la página Información adicional, seleccione Crear.
En la ventana Explorador de soluciones, haga clic con el botón derecho en SubscriptionReceiver y seleccione Establecer como proyecto de inicio.

Agregar el paquete NuGet de Service Bus

Seleccione Herramientas > Administrador de paquetes NuGet > Consola del Administrador de paquetes en el menú.
En la ventana Consola del Administrador de paquetes, confirme que SubscriptionReceiver esté seleccionado para el Proyecto predeterminado. Si no es así, use la lista desplegable para seleccionar SubscriptionReceiver.
Ejecute el siguiente comando para instalar el paquete NuGet Azure.Messaging.ServiceBus:
```
Install-Package Azure.Messaging.ServiceBus
```

Adición de código para recibir mensajes de la suscripción

En Program.cs, agregue las siguientes instrucciones using en la parte superior de la definición del espacio de nombres, antes de la declaración de clase.
```
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
```

Dentro de la clase Program, declare las siguientes propiedades, justo antes del método Main. Reemplace los marcadores de posición por los valores correctos:

<NAMESPACE CONNECTION STRING> por la cadena de conexión del espacio de nombres de Service Bus.
<TOPIC NAME> por el nombre del tema de Service Bus.
<SERVICE BUS - TOPIC SUBSCRIPTION NAME> por el nombre de la suscripción al tema.

// connection string to your Service Bus namespace
static string connectionString = "<NAMESPACE CONNECTION STRING>";

// name of the Service Bus topic
static string topicName = "<SERVICE BUS TOPIC NAME>";

// name of the subscription to the topic
static string subscriptionName = "<SERVICE BUS - TOPIC SUBSCRIPTION NAME>";

// the client that owns the connection and can be used to create senders and receivers
static ServiceBusClient client;

// the processor that reads and processes messages from the subscription
static ServiceBusProcessor processor;

Agregue los métodos siguientes a la clase Program para controlar los mensajes y los errores recibidos.

// handle received messages
static async Task MessageHandler(ProcessMessageEventArgs args)
{
    string body = args.Message.Body.ToString();
    Console.WriteLine($"Received: {body} from subscription: {subscriptionName}");

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

// handle any errors when receiving messages
static Task ErrorHandler(ProcessErrorEventArgs args)
{
    Console.WriteLine(args.Exception.ToString());
    return Task.CompletedTask;
}

Reemplace el código del archivo Program.cs por el código siguiente. Estos son los pasos importantes del código:

Crea un objeto ServiceBusClient mediante la cadena de conexión al espacio de nombres.
Invoca al método CreateProcessor en el objeto ServiceBusClient para crear un objeto ServiceBusProcessor para la cola de Service Bus especificada.
Especifica los controladores para los eventos ProcessMessageAsync y ProcessErrorAsync del objeto ServiceBusProcessor.
Inicia el procesamiento de mensajes; para ello, invoca el método StartProcessingAsync en el objeto ServiceBusProcessor.
Cuando el usuario presiona una tecla para finalizar el procesamiento, invoca el método StopProcessingAsync en el objeto ServiceBusProcessor.

Para más información, consulte los comentarios del código.

static async Task Main()
{
    // The Service Bus client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when messages are being published or read
    // regularly.
    //
    // Create the clients that we'll use for sending and processing messages.
    client = new ServiceBusClient(connectionString);

    // create a processor that we can use to process the messages
    processor = client.CreateProcessor(topicName, subscriptionName, new ServiceBusProcessorOptions());

    try
    {
        // add handler to process messages
        processor.ProcessMessageAsync += MessageHandler;

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

        // start processing 
        await processor.StartProcessingAsync();

        Console.WriteLine("Wait for a minute and then press any key to end the processing");
        Console.ReadKey();

        // stop processing 
        Console.WriteLine("\nStopping the receiver...");
        await processor.StopProcessingAsync();
        Console.WriteLine("Stopped receiving messages");
    }
    finally
    {
        // Calling DisposeAsync on client types is required to ensure that network
        // resources and other unmanaged objects are properly cleaned up.
        await processor.DisposeAsync();
        await client.DisposeAsync();
    }
}

Este es el aspecto que debería tener Program.cs:

using System;
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;

namespace SubscriptionReceiver
{
    class Program
    {
        // connection string to your Service Bus namespace
        static string connectionString = "<NAMESPACE CONNECTION STRING>";

        // name of the Service Bus topic
        static string topicName = "<SERVICE BUS TOPIC NAME>";

        // name of the subscription to the topic
        static string subscriptionName = "<SERVICE BUS - TOPIC SUBSCRIPTION NAME>";

        // the client that owns the connection and can be used to create senders and receivers
        static ServiceBusClient client;

        // the processor that reads and processes messages from the subscription
        static ServiceBusProcessor processor;

        // handle received messages
        static async Task MessageHandler(ProcessMessageEventArgs args)
        {
            string body = args.Message.Body.ToString();
            Console.WriteLine($"Received: {body} from subscription: {subscriptionName}");

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

        // handle any errors when receiving messages
        static Task ErrorHandler(ProcessErrorEventArgs args)
        {
            Console.WriteLine(args.Exception.ToString());
            return Task.CompletedTask;
        }

        static async Task Main()
        {
            // The Service Bus client types are safe to cache and use as a singleton for the lifetime
            // of the application, which is best practice when messages are being published or read
            // regularly.
            //
            // Create the clients that we'll use for sending and processing messages.
            client = new ServiceBusClient(connectionString);

            // create a processor that we can use to process the messages
            processor = client.CreateProcessor(topicName, subscriptionName, new ServiceBusProcessorOptions());

            try
            {
                // add handler to process messages
                processor.ProcessMessageAsync += MessageHandler;

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

                // start processing 
                await processor.StartProcessingAsync();

                Console.WriteLine("Wait for a minute and then press any key to end the processing");
                Console.ReadKey();

                // stop processing 
                Console.WriteLine("\nStopping the receiver...");
                await processor.StopProcessingAsync();
                Console.WriteLine("Stopped receiving messages");
            }
            finally
            {
                // Calling DisposeAsync on client types is required to ensure that network
                // resources and other unmanaged objects are properly cleaned up.
                await processor.DisposeAsync();
                await client.DisposeAsync();
            }
        }
    }
}

Reemplace los marcadores de posición por los valores correctos:
- <NAMESPACE CONNECTION STRING> por la cadena de conexión del espacio de nombres de Service Bus.
- <TOPIC NAME> por el nombre del tema de Service Bus.
- <SERVICE BUS - TOPIC SUBSCRIPTION NAME> por el nombre de la suscripción al tema.
Compile el proyecto y asegúrese de que no hay errores.

Ejecute la aplicación del destinatario. Debería ver los mensajes recibidos. Presione cualquier tecla para detener el receptor y la aplicación.

Wait for a minute and then press any key to end the processing
Received: Message 1 from subscription: S1
Received: Message 2 from subscription: S1
Received: Message 3 from subscription: S1

Stopping the receiver...
Stopped receiving messages

Vuelva a consultar el portal.
- En la página Tema de Service Bus, en el gráfico Mensajes, podrá ver tres mensajes entrantes y tres mensajes salientes. Si no ve estos números, espere unos minutos y actualice la página para ver el gráfico actualizado.
- En la página Service Bus Subscription (Suscripción de Service Bus), verá el Recuento de mensajes activos como cero. Esto se debe a que un receptor ha recibido mensajes de esta suscripción y ha completado los mensajes.

Pasos siguientes

Consulte la documentación y los ejemplos siguientes:

Introducción a los temas y las suscripciones de Azure Service Bus

Valore su experiencia

Prerrequisitos

Creación de un espacio de nombres en Azure Portal

Obtención de la cadena de conexión

Creación de un tema mediante Azure Portal

Creación de una suscripción al tema

Envío de mensajes al tema

Creación de una aplicación de consola

Agregar el paquete NuGet de Service Bus

Incorporación de código para enviar mensajes al tema

Recepción de mensajes de una suscripción

Creación de un proyecto para el destinatario

Agregar el paquete NuGet de Service Bus

Adición de código para recibir mensajes de la suscripción

Pasos siguientes