Bibliothèque de client Azure WebJobs Service Bus pour .NET - version 5.13.3

Article
10/20/2023

Cette extension fournit des fonctionnalités permettant d’accéder à Azure Service Bus à partir d’une fonction Azure.

Prise en main

Installer le package

Installez l’extension Service Bus avec NuGet :

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

Prérequis

Abonnement Azure : Pour utiliser les services Azure, y compris Azure Service Bus, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.
Espace de noms Service Bus : Pour interagir avec Azure Service Bus, vous devez également disposer d’un espace de noms. Si vous n’êtes pas familiarisé avec la création de ressources Azure, vous pouvez suivre le guide pas à pas pour créer un espace de noms Service Bus à l’aide du Portail Azure. Vous y trouverez également des instructions détaillées sur l’utilisation des modèles Azure CLI, Azure PowerShell ou Azure Resource Manager (ARM) pour créer une entité Service bus.

Pour créer rapidement les ressources Service Bus nécessaires dans Azure et recevoir une chaîne de connexion pour celles-ci, vous pouvez déployer notre exemple de modèle en cliquant sur :

Authentifier le client

Pour que la bibliothèque cliente Service Bus interagisse avec une file d’attente ou une rubrique, elle doit comprendre comment s’y connecter et y autoriser. Le moyen le plus simple consiste à utiliser une chaîne de connexion, qui est créée automatiquement lors de la création d’un espace de noms Service Bus. Si vous n’êtes pas familiarisé avec les stratégies d’accès partagé dans Azure, vous pouvez suivre le guide pas à pas pour obtenir un chaîne de connexion Service Bus.

La Connection propriété de ServiceBusAttribute et ServiceBusTriggerAttribute est utilisée pour spécifier la propriété de configuration qui stocke les chaîne de connexion. Si elle n’est pas spécifiée, la propriété AzureWebJobsServiceBus doit contenir le chaîne de connexion.

Pour le développement local, utilisez le local.settings.json fichier pour stocker les chaîne de connexion :

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

Une fois le déploiement effectué, utilisez les paramètres de l’application pour définir le chaîne de connexion.

Authentification basée sur l’identité

Si l’identité managée est activée dans votre environnement, vous pouvez l’utiliser pour authentifier l’extension Service Bus. Avant de procéder, vous devez vous assurer que les autorisations ont été configurées comme décrit dans le guide du développeur Azure Functions. Pour utiliser l’authentification basée sur l’identité, fournissez le paramètre de <connection_name>__fullyQualifiedNamespace configuration.

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

Ou, dans le cas d’une application déployée, définissez le même paramètre dans les paramètres de l’application :

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

Vous trouverez plus d’informations sur la configuration d’une connexion basée sur l’identité ici.

Concepts clés

Déclencheur Service Bus

Le déclencheur Service Bus permet d’exécuter une fonction lorsqu’un message est envoyé à une file d’attente ou à une rubrique Service Bus.

Suivez le tutoriel déclencheur Azure Service Bus pour en savoir plus sur les déclencheurs Service Bus.

Liaison de sortie Service Bus

La liaison de sortie Service Bus permet à une fonction d’envoyer des messages Service Bus.

Suivez la liaison de sortie Azure Service Bus pour en savoir plus sur les liaisons Service Bus.

Exemples

Envoi de messages individuels

Vous pouvez envoyer des messages individuels à une file d’attente ou à une rubrique en appliquant l’attribut ServiceBus à la valeur de retour de la fonction. La valeur de retour peut être de type string, byte[]ou 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}";
}

Vous pouvez également utiliser un out paramètre de type string, byte[]ou 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}");
}

Envoi de plusieurs messages

Pour envoyer plusieurs messages à partir d’un appel de fonction Azure unique, vous pouvez appliquer l’attribut ServiceBus au IAsyncCollector<string> paramètre ou 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}")));
}

Utilisation de la liaison à des modèles fortement typés

Pour utiliser des classes de modèle fortement typées avec la liaison ServiceBus, appliquez l’attribut ServiceBus au paramètre de modèle. Cela tentera de désérialiser le ServiceBusMessage.Bodydans le modèle fortement typé.

[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!");
}

Envoi de plusieurs messages à l’aide de ServiceBusSender

Vous pouvez également vous lier directement à pour ServiceBusSender avoir le meilleur contrôle sur l’envoi de messages.

[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}"))
    });
}

Déclencheurs par message

Pour exécuter une fonction chaque fois qu’un message est envoyé à une file d’attente ou à un abonnement Service Bus, appliquez l’attribut ServiceBusTrigger à un stringparamètre , byte[]ou 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}");
}

Déclencheurs de lot

Pour exécuter une fonction pour un lot de messages reçus, appliquez l’attribut ServiceBusTrigger à un string[]paramètre ou 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}");
    }
}

Règlement des messages

Vous pouvez configurer les messages pour qu’ils soient automatiquement terminés après l’exécution de votre fonction à l’aide de ServiceBusOptions. Si vous souhaitez plus de contrôle sur le règlement des messages, vous pouvez établir une liaison avec les MessageActions déclencheurs par message et par lot.

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

Déclencheurs de session

Pour recevoir des messages d’une file d’attente ou d’une rubrique activée pour la session, vous pouvez définir la IsSessionsEnabled propriété sur l’attribut ServiceBusTrigger . Lorsque vous utilisez des sessions, vous pouvez vous lier à pour SessionMessageActions accéder aux méthodes de règlement des messages en plus des fonctionnalités spécifiques à la session.

[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>"));
}

Liaison à ReceiveActions

Il est possible de recevoir des messages supplémentaires à partir de l’appel de votre fonction. Cela peut être utile si vous avez besoin de plus de contrôle sur le nombre de messages à traiter dans un appel de fonction en fonction de certaines caractéristiques du message initial remis à votre fonction via le paramètre de liaison. Tous les messages supplémentaires que vous recevez seront soumis à la même AutoCompleteMessagesMaxAutoLockRenewalDuration configuration que le message initial remis à votre fonction. Il est également possible de consulter des messages. Les messages d’aperçu ne sont pas soumis à la AutoCompleteMessages configuration et MaxAutoLockRenewalDuration , car ces messages ne sont pas verrouillés et ne peuvent donc pas être terminés.

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

Liaison à ServiceBusClient

Il peut arriver que vous souhaitiez lier au même ServiceBusClient que celui utilisé par le déclencheur. Cela peut être utile si vous devez créer dynamiquement un expéditeur en fonction du message reçu.

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

Dépannage

Si votre fonction déclenche une exception non prise en charge et que vous n’avez pas encore réglé le message, l’extension tente d’abandonner le message afin qu’il soit disponible pour la réception immédiate.

Pour plus d’informations sur la résolution des problèmes, reportez-vous à Monitor Azure Functions.

Étapes suivantes

Lisez l’introduction à Azure Functions ou à la création d’un guide de fonction Azure.

Contribution

Consultez notre CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions

Partager via