Biblioteca cliente de Azure WebJobs Service Bus para .NET: versión 5.13.3

Artículo
10/20/2023

Esta extensión proporciona funcionalidad para acceder a Azure Service Bus desde una función de Azure.

Introducción

Instalar el paquete

Instale la extensión de Service Bus con NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus

Requisitos previos

Suscripción de Azure: Para usar los servicios de Azure, incluida Azure Service Bus, necesitará una suscripción. Si no tiene una cuenta de Azure existente, puede registrarse para obtener una evaluación gratuita o usar las ventajas de la suscripción de Visual Studio al crear una cuenta.
Espacio de nombres de Service Bus: Para interactuar con Azure Service Bus, también deberá tener un espacio de nombres disponible. Si no está familiarizado con la creación de recursos de Azure, puede seguir la guía paso a paso para crear un espacio de nombres de Service Bus mediante el Azure Portal. Allí también puede encontrar instrucciones detalladas para usar la CLI de Azure, Azure PowerShell o plantillas de Azure Resource Manager (ARM) para crear una entidad de Service Bus.

Para crear rápidamente los recursos de Service Bus necesarios en Azure y recibir una cadena de conexión para ellos, puede implementar nuestra plantilla de ejemplo haciendo clic en:

Autenticar el cliente

Para que la biblioteca cliente de Service Bus interactúe con una cola o tema, deberá comprender cómo conectarse y autorizarla. Los medios más fáciles para hacerlo es usar una cadena de conexión, que se crea automáticamente al crear un espacio de nombres de Service Bus. Si no está familiarizado con las directivas de acceso compartido en Azure, puede seguir la guía paso a paso para obtener una cadena de conexión de Service Bus.

La Connection propiedad de y ServiceBusTriggerAttribute se usa para especificar la propiedad de ServiceBusAttribute configuración que almacena el cadena de conexión. Si no se especifica, se espera que la propiedad AzureWebJobsServiceBus contenga el cadena de conexión.

Para el desarrollo local, use el local.settings.json archivo para almacenar el cadena de conexión:

{
  "Values": {
    "<connection_name>": "Endpoint=sb://<service_bus_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=<access key>"
  }
}

Cuando se implemente, use la configuración de la aplicación para establecer el cadena de conexión.

Habilitación basada en identidad

Si el entorno tiene habilitada la identidad administrada , puede usarla para autenticar la extensión de Service Bus. Antes de hacerlo, deberá asegurarse de que los permisos se han configurado como se describe en la guía para desarrolladores de Azure Functions. Para usar la autenticación basada en identidades, proporcione la <connection_name>__fullyQualifiedNamespace configuración.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>__fullyQualifiedNamespace": "<service_bus_namespace>.servicebus.windows.net"
  }
}

O bien, en el caso de la aplicación implementada, establezca la misma configuración en la configuración de la aplicación:

<connection_name>__fullyQualifiedNamespace=<service_bus_namespace>.servicebus.windows.net

Puede encontrar más detalles sobre cómo configurar una conexión basada en identidades aquí.

Conceptos clave

Desencadenador de Service Bus

El desencadenador de Service Bus permite ejecutar una función cuando se envía un mensaje a una cola o tema de Service Bus.

Siga el tutorial del desencadenador de Azure Service Bus para más información sobre los desencadenadores de Service Bus.

Enlace de salida de Service Bus

El enlace de salida de Service Bus permite que una función envíe mensajes de Service Bus.

Siga el enlace de salida de Azure Service Bus para obtener más información sobre los enlaces de Service Bus.

Ejemplos

Envío de mensajes individuales

Puede enviar mensajes individuales a una cola o tema aplicando el ServiceBus atributo al valor devuelto de la función. El valor devuelto puede ser de tipo string, byte[]o ServiceBusMessage.

[FunctionName("BindingToReturnValue")]
[return: ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
public static string BindToReturnValue([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
    // This value would get stored in Service Bus message body.
    // The string would be UTF8 encoded.
    return $"C# Timer trigger function executed at: {DateTime.Now}";
}

También puede usar un out parámetro de tipo string, byte[]o ServiceBusMessage.

[FunctionName("BindingToOutputParameter")]
public static void Run(
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] out ServiceBusMessage message)
{
    message = new ServiceBusMessage($"C# Timer trigger function executed at: {DateTime.Now}");
}

Envío de varios mensajes

Para enviar varios mensajes desde una única invocación de función de Azure, puede aplicar el ServiceBus atributo al IAsyncCollector<string> parámetro o IAsyncCollector<ServiceBusReceivedMessage> .

[FunctionName("BindingToCollector")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] IAsyncCollector<ServiceBusMessage> collector)
{
    // IAsyncCollector allows sending multiple messages in a single function invocation
    await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")));
    await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}")));
}

Uso del enlace a modelos fuertemente tipados

Para usar clases de modelo fuertemente tipadas con el enlace serviceBus, aplique el ServiceBus atributo al parámetro del modelo. Si lo hace, intentará deserializar en ServiceBusMessage.Bodyel modelo fuertemente tipado.

[FunctionName("TriggerSingleModel")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] Dog dog,
    ILogger logger)
{
    logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}

Envío de varios mensajes mediante ServiceBusSender

También puede enlazar directamente ServiceBusSender para tener el mayor control sobre el envío de mensajes.

[FunctionName("BindingToSender")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] ServiceBusSender sender)
{
    await sender.SendMessagesAsync(new[]
    {
        new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")),
        new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}"))
    });
}

Desencadenadores por mensaje

Para ejecutar una función cada vez que se envía un mensaje a una cola o suscripción de Service Bus, aplique el ServiceBusTrigger atributo a un stringparámetro , byte[]o ServiceBusReceivedMessage .

[FunctionName("TriggerSingle")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] string messageBodyAsString,
    ILogger logger)
{
    logger.LogInformation($"C# function triggered to process a message: {messageBodyAsString}");
}

Desencadenadores de Batch

Para ejecutar una función para un lote de mensajes recibidos, aplique el ServiceBusTrigger atributo a un string[]parámetro o ServiceBusReceivedMessage[] .

[FunctionName("TriggerBatch")]
public static void Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] ServiceBusReceivedMessage[] messages,
    ILogger logger)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        logger.LogInformation($"C# function triggered to process a message: {message.Body}");
        logger.LogInformation($"EnqueuedTime={message.EnqueuedTime}");
    }
}

Liquidación de mensajes

Puede configurar los mensajes para que se completen automáticamente después de que la función se ejecute mediante .ServiceBusOptions Si desea tener más control sobre la liquidación de mensajes, puede enlazar con los MessageActions desencadenadores por mensaje y por lotes.

[FunctionName("BindingToMessageActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")]
    ServiceBusReceivedMessage[] messages,
    ServiceBusMessageActions messageActions)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        if (message.MessageId == "1")
        {
            await messageActions.DeadLetterMessageAsync(message);
        }
        else
        {
            await messageActions.CompleteMessageAsync(message);
        }
    }
}

Desencadenadores de sesión

Para recibir mensajes de una cola o tema habilitados para la sesión, puede establecer la IsSessionsEnabled propiedad en el ServiceBusTrigger atributo . Al trabajar con sesiones, puede enlazar a SessionMessageActions para obtener acceso a los métodos de liquidación de mensajes además de la funcionalidad específica de la sesión.

[FunctionName("BindingToSessionMessageActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
    ServiceBusReceivedMessage[] messages,
    ServiceBusSessionMessageActions sessionActions)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        if (message.MessageId == "1")
        {
            await sessionActions.DeadLetterMessageAsync(message);
        }
        else
        {
            await sessionActions.CompleteMessageAsync(message);
        }
    }

    // We can also perform session-specific operations using the actions, such as setting state that is specific to this session.
    await sessionActions.SetSessionStateAsync(new BinaryData("<session state>"));
}

Enlace a ReceiveActions

Es posible recibir mensajes adicionales desde dentro de la invocación de función. Esto puede ser útil si necesita más control sobre cuántos mensajes procesar dentro de una invocación de función en función de algunas características del mensaje inicial entregado a la función a través del parámetro de enlace. Los mensajes adicionales que reciba estarán sujetos a la misma AutoCompleteMessages configuración y MaxAutoLockRenewalDuration que el mensaje inicial entregado a la función. También es posible ver los mensajes. Los mensajes inspeccionados no están sujetos a la AutoCompleteMessages configuración y MaxAutoLockRenewalDuration , ya que estos mensajes no están bloqueados y, por lo tanto, no se pueden completar.

[FunctionName("BindingToReceiveActions")]
public static async Task Run(
    [ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions,
    ServiceBusReceiveActions receiveActions)
{
    if (message.MessageId == "1")
    {
        await messageActions.DeadLetterMessageAsync(message);
    }
    else
    {
        await messageActions.CompleteMessageAsync(message);

        // attempt to receive additional messages in this session
        var receivedMessages = await receiveActions.ReceiveMessagesAsync(maxMessages: 10);

        // you can also use the receive actions to peek messages
        var peekedMessages = await receiveActions.PeekMessagesAsync(maxMessages: 10);
    }
}

Enlace a ServiceBusClient

Puede haber ocasiones en las que quiera enlazar con el mismo ServiceBusClient que está usando el desencadenador. Esto puede ser útil si necesita crear dinámicamente un remitente en función del mensaje que se recibe.

[FunctionName("BindingToClient")]
public static async Task Run(
    [ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
    ServiceBusReceivedMessage message,
    ServiceBusClient client)
{
    ServiceBusSender sender = client.CreateSender(message.To);
    await sender.SendMessageAsync(new ServiceBusMessage(message));
}

Solución de problemas

Si la función desencadena una excepción no controlada y aún no ha resuelto el mensaje, la extensión intentará abandonar el mensaje para que esté disponible para recibirse de nuevo inmediatamente.

Consulte Monitor Azure Functions para obtener más instrucciones de solución de problemas.

Pasos siguientes

Lea la introducción a Azure Functions o cree una guía de funciones de Azure.

Contribuciones

Consulte nuestra CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de