Azure WebJobs Service Bus-Clientbibliothek für .NET – Version 5.13.3

  • Artikel

Diese Erweiterung bietet Funktionen für den Zugriff auf Azure Service Bus über eine Azure-Funktion.

Erste Schritte

Installieren des Pakets

Installieren Sie die Service Bus-Erweiterung mit NuGet:

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

Voraussetzungen

  • Azure-Abonnement: Für die Verwendung von Azure-Diensten, einschließlich Azure Service Bus, benötigen Sie ein Abonnement. Wenn Sie nicht über ein vorhandenes Azure-Konto verfügen, können Sie sich für eine kostenlose Testversion registrieren oder ihre Visual Studio-Abonnementvorteile beim Erstellen eines Kontos nutzen.

  • Service Bus-Namespace: Um mit Azure Service Bus zu interagieren, müssen Sie auch einen Namespace zur Verfügung haben. Wenn Sie mit dem Erstellen von Azure-Ressourcen nicht vertraut sind, sollten Sie die schrittweise Anleitung zum Erstellen eines Service Bus-Namespaces mithilfe des Azure-Portal befolgen. Dort finden Sie auch ausführliche Anweisungen zur Verwendung der Azure CLI-, Azure PowerShell- oder Arm-Vorlagen (Azure Resource Manager) zum Erstellen einer Service Bus-Entität.

Um schnell die erforderlichen Service Bus-Ressourcen in Azure zu erstellen und eine Verbindungszeichenfolge für sie zu erhalten, können Sie unsere Beispielvorlage bereitstellen, indem Sie auf klicken:

Bereitstellen in Azure

Authentifizieren des Clients

Damit die Service Bus-Clientbibliothek mit einer Warteschlange oder einem Thema interagieren kann, muss sie verstehen, wie eine Verbindung hergestellt und autorisiert werden kann. Die einfachste Möglichkeit hierfür ist die Verwendung einer Verbindungszeichenfolge, die beim Erstellen eines Service Bus-Namespaces automatisch erstellt wird. Wenn Sie mit Shared Access-Richtlinien in Azure nicht vertraut sind, sollten Sie die schrittweise Anleitung befolgen, um eine Service Bus-Verbindungszeichenfolge zu erhalten.

Die Connection -Eigenschaft von ServiceBusAttribute und ServiceBusTriggerAttribute wird verwendet, um die Konfigurationseigenschaft anzugeben, in der die Verbindungszeichenfolge gespeichert wird. Wenn nicht angegeben, wird erwartet, dass die -Eigenschaft AzureWebJobsServiceBus den Verbindungszeichenfolge enthält.

Verwenden Sie für die lokale Entwicklung die local.settings.json Datei, um die Verbindungszeichenfolge zu speichern:

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

Verwenden Sie bei der Bereitstellung die Anwendungseinstellungen, um die Verbindungszeichenfolge festzulegen.

Identitätsbasierte Authentifizierung

Wenn Für Ihre Umgebung eine verwaltete Identität aktiviert ist, können Sie sie verwenden, um die Service Bus-Erweiterung zu authentifizieren. Zuvor müssen Sie sicherstellen, dass Berechtigungen wie im Azure Functions Entwicklerhandbuch beschrieben konfiguriert wurden. Um die identitätsbasierte Authentifizierung zu verwenden, geben Sie die <connection_name>__fullyQualifiedNamespace Konfigurationseinstellung an.

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

Oder legen Sie im Fall der bereitgestellten App die gleiche Einstellung in den Anwendungseinstellungen fest:

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

Weitere Informationen zum Konfigurieren einer identitätsbasierten Verbindung finden Sie hier.

Wichtige Begriffe

Service Bus-Trigger

Der Service Bus-Trigger ermöglicht die Ausführung einer Funktion, wenn eine Nachricht an eine Service Bus-Warteschlange oder ein Service Bus-Thema gesendet wird.

Folgen Sie dem Tutorial Azure Service Bus Trigger, um mehr über Service Bus-Trigger zu erfahren.

Service Bus-Ausgabebindung

Die Service Bus-Ausgabebindung ermöglicht es einer Funktion, Service Bus-Nachrichten zu senden.

Folgen Sie der Azure Service Bus Ausgabebindung, um mehr über Service Bus-Bindungen zu erfahren.

Beispiele

Senden einzelner Nachrichten

Sie können einzelne Nachrichten an eine Warteschlange oder ein Thema senden, indem Sie das ServiceBus Attribut auf den Funktionsrückgabewert anwenden. Der Rückgabewert kann vom Typ string, byte[]oder ServiceBusMessagesein.

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

Sie können auch einen out Parameter vom Typ string, byte[]oder ServiceBusMessageverwenden.

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

Senden mehrerer Nachrichten

Um mehrere Nachrichten von einem einzelnen Azure-Funktionsaufruf zu senden, können Sie das ServiceBus -Attribut auf den - oder IAsyncCollector<ServiceBusReceivedMessage> -IAsyncCollector<string>Parameter anwenden.

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

Verwenden der Bindung an stark typisierte Modelle

Um stark typisierte Modellklassen mit der ServiceBus-Bindung zu verwenden, wenden Sie das ServiceBus Attribut auf den Modellparameter an. Dadurch wird versucht, die ServiceBusMessage.Bodyin das stark typisierte Modell deserialisieren.

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

Senden mehrerer Nachrichten mithilfe von ServiceBusSender

Sie können auch direkt an das ServiceBusSender binden, um die meiste Kontrolle über das Senden von Nachrichten zu haben.

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

Trigger pro Nachricht

Wenn Sie eine Funktion jedes Mal ausführen möchten, wenn eine Nachricht an eine Service Bus-Warteschlange oder ein Service Bus-Abonnement gesendet wird, wenden Sie das ServiceBusTrigger Attribut auf einen , byte[]- oder ServiceBusReceivedMessage -Parameter anstring.

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

Batchtrigger

Um eine Funktion für einen Batch empfangener Nachrichten auszuführen, wenden Sie das ServiceBusTrigger Attribut auf einen string[]- oder ServiceBusReceivedMessage[] -Parameter an.

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

Nachrichtenabrechnung

Sie können Nachrichten so konfigurieren, dass sie automatisch abgeschlossen werden, nachdem Ihre Funktion ausgeführt wurde, indem Sie verwenden ServiceBusOptions. Wenn Sie mehr Kontrolle über die Nachrichtenabwicklung haben möchten, können Sie sowohl mit pro Nachricht als auch mit Batchtriggern an die MessageActions binden.

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

Sitzungstrigger

Um Nachrichten von einer sitzungsfähigen Warteschlange oder einem Thema zu empfangen, können Sie die IsSessionsEnabled -Eigenschaft für das ServiceBusTrigger Attribut festlegen. Wenn Sie mit Sitzungen arbeiten, können Sie an das SessionMessageActions binden, um zusätzlich zur sitzungsspezifischen Funktionalität Zugriff auf die Methoden zur Nachrichtenabrechnung zu erhalten.

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

Bindung an ReceiveActions

Es ist möglich, zusätzliche Nachrichten aus ihrem Funktionsaufruf zu empfangen. Dies kann nützlich sein, wenn Sie mehr Kontrolle darüber benötigen, wie viele Nachrichten innerhalb eines Funktionsaufrufs verarbeitet werden sollen, basierend auf einigen Merkmalen der anfänglichen Nachricht, die über den Bindungsparameter an Ihre Funktion übermittelt wurde. Alle zusätzlichen Nachrichten, die Sie erhalten, unterliegen der gleichen AutoCompleteMessages Konfiguration wie MaxAutoLockRenewalDuration die anfängliche Nachricht, die an Ihre Funktion übermittelt wird. Es ist auch möglich, Nachrichten anzuzeigen. Angezeigte Nachrichten unterliegen nicht der AutoCompleteMessages Konfiguration und MaxAutoLockRenewalDuration , da diese Nachrichten nicht gesperrt sind und daher nicht abgeschlossen werden können.

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

Bindung an ServiceBusClient

Es kann vorkommen, dass Sie an dieselbe ServiceBusClient Bindung binden möchten, die der Trigger verwendet. Dies kann nützlich sein, wenn Sie einen Absender basierend auf der empfangenen Nachricht dynamisch erstellen müssen.

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

Problembehandlung

Wenn Ihre Funktion eine nicht behandelte Ausnahme auslöst und Sie die Nachricht noch nicht abgeschlossen haben, versucht die Erweiterung, die Nachricht zu beenden, sodass sie sofort wieder für den Empfang verfügbar wird.

Weitere Anleitungen zur Problembehandlung finden Sie unter Überwachen Azure Functions.

Nächste Schritte

Lesen Sie die Einführung in Azure Functions oder erstellen sie eine Azure Function-Anleitung.

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie in unserem CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe