Microsoft.Azure.WebJobs.Extensions.ServiceBus 5.0.0-beta.4 The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Microsoft Azure WebJobs SDK ServiceBus Extension

This is a prerelease version of Microsoft.Azure.WebJobs.Extensions.ServiceBus.
There is a newer prerelease version of this package available.
See the version list below for details.
Install-Package Microsoft.Azure.WebJobs.Extensions.ServiceBus -Version 5.0.0-beta.4
dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.0.0-beta.4
<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.ServiceBus" Version="5.0.0-beta.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.0.0-beta.4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Microsoft.Azure.WebJobs.Extensions.ServiceBus, 5.0.0-beta.4"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Microsoft.Azure.WebJobs.Extensions.ServiceBus as a Cake Addin
#addin nuget:?package=Microsoft.Azure.WebJobs.Extensions.ServiceBus&version=5.0.0-beta.4&prerelease

// Install Microsoft.Azure.WebJobs.Extensions.ServiceBus as a Cake Tool
#tool nuget:?package=Microsoft.Azure.WebJobs.Extensions.ServiceBus&version=5.0.0-beta.4&prerelease
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Azure WebJobs Service Bus client library for .NET

This extension provides functionality for accessing Azure Service Bus from an Azure Function.

Getting started

Install the package

Install the Service Bus extension with NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.0.0-beta.1

Prerequisites

  • Azure Subscription: To use Azure services, including Azure Service Bus, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a free trial or use your Visual Studio Subscription benefits when you create an account.

  • Service Bus namespace: To interact with Azure Service Bus, you'll also need to have a namespace available. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for creating a Service Bus namespace using the Azure portal. There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create a Service bus entity.

To quickly create the needed Service Bus resources in Azure and to receive a connection string for them, you can deploy our sample template by clicking:

Deploy to Azure

Authenticate the Client

For the Service Bus client library to interact with a queue or topic, it will need to understand how to connect and authorize with it. The easiest means for doing so is to use a connection string, which is created automatically when creating a Service Bus namespace. If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to get a Service Bus connection string.

The Connection property of ServiceBusAttribute and ServiceBusTriggerAttribute is used to specify the configuration property that stores the connection string. If not specified, the property AzureWebJobsServiceBus is expected to contain the connection string.

For local development, use the local.settings.json file to store the connection string:

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

When deployed, use the application settings to set the connection string.

Managed identity authentication

If your environment has managed identity enabled you can use it to authenticate the Service Bus extension. To use managed identity provide the <connection_name>__fullyQualifiedNamespace configuration setting.

{
  "Values": {
    "<connection_name>__fullyQualifiedNamespace": "<service_bus_namespace>.servicebus.windows.net"
  }
}

Or in the case of deployed app set the same setting in application settings:

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

Key concepts

Service Bus Trigger

The Service Bus Trigger allows a function to be executed when a message is sent to a Service Bus queue or topic.

Please follow the Azure Service Bus trigger tutorial to learn more about Service Bus triggers.

Service Bus Output Binding

The Service Bus Output Binding allows a function to send Service Bus messages.

Please follow the Azure Service Bus output binding to learn more about Service Bus bindings.

Examples

Sending individual messages

You can send individual messages to a queue or topic by applying the ServiceBus attribute to the function return value. The return value can be of type string, byte[], or 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}";
}

You can also use an out parameter of type string, byte[], or 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}");
}

Sending multiple messages

To send multiple messages from a single Azure Function invocation you can apply the ServiceBus attribute to the IAsyncCollector<string> or IAsyncCollector<ServiceBusReceivedMessage> parameter.

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

Using binding to strongly-typed models

To use strongly-typed model classes with the ServiceBus binding apply the ServiceBus attribute to the model parameter. Doing so will attempt to deserialize the ServiceBusMessage.Bodyinto the strongly-typed model.

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

Sending multiple messages using ServiceBusSender

You can also bind to the ServiceBusSender directly to have the most control over message sending.

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

Per-message triggers

To run a function every time a message is sent to a Service Bus queue or subscription apply the ServiceBusTrigger attribute to a string, byte[], or ServiceBusReceivedMessage parameter.

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

Batch triggers

To run a function for a batch of received messages apply the ServiceBusTrigger attribute to a string[], or ServiceBusReceivedMessage[] parameter.

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

Message settlement

You can configure messages to be automatically completed after your function executes using the ServiceBusOptions. If you want more control over message settlement, you can bind to the MessageActions with both per-message and batch triggers.

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

Troubleshooting

Please refer to Monitor Azure Functions for troubleshooting guidance.

Next steps

Read the introduction to Azure Functions or creating an Azure Function guide.

Contributing

See our CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. 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. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Azure WebJobs Service Bus client library for .NET

This extension provides functionality for accessing Azure Service Bus from an Azure Function.

Getting started

Install the package

Install the Service Bus extension with NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.0.0-beta.1

Prerequisites

  • Azure Subscription: To use Azure services, including Azure Service Bus, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a free trial or use your Visual Studio Subscription benefits when you create an account.

  • Service Bus namespace: To interact with Azure Service Bus, you'll also need to have a namespace available. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for creating a Service Bus namespace using the Azure portal. There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create a Service bus entity.

To quickly create the needed Service Bus resources in Azure and to receive a connection string for them, you can deploy our sample template by clicking:

Deploy to Azure

Authenticate the Client

For the Service Bus client library to interact with a queue or topic, it will need to understand how to connect and authorize with it. The easiest means for doing so is to use a connection string, which is created automatically when creating a Service Bus namespace. If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to get a Service Bus connection string.

The Connection property of ServiceBusAttribute and ServiceBusTriggerAttribute is used to specify the configuration property that stores the connection string. If not specified, the property AzureWebJobsServiceBus is expected to contain the connection string.

For local development, use the local.settings.json file to store the connection string:

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

When deployed, use the application settings to set the connection string.

Managed identity authentication

If your environment has managed identity enabled you can use it to authenticate the Service Bus extension. To use managed identity provide the <connection_name>__fullyQualifiedNamespace configuration setting.

{
  "Values": {
    "<connection_name>__fullyQualifiedNamespace": "<service_bus_namespace>.servicebus.windows.net"
  }
}

Or in the case of deployed app set the same setting in application settings:

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

Key concepts

Service Bus Trigger

The Service Bus Trigger allows a function to be executed when a message is sent to a Service Bus queue or topic.

Please follow the Azure Service Bus trigger tutorial to learn more about Service Bus triggers.

Service Bus Output Binding

The Service Bus Output Binding allows a function to send Service Bus messages.

Please follow the Azure Service Bus output binding to learn more about Service Bus bindings.

Examples

Sending individual messages

You can send individual messages to a queue or topic by applying the ServiceBus attribute to the function return value. The return value can be of type string, byte[], or 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}";
}

You can also use an out parameter of type string, byte[], or 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}");
}

Sending multiple messages

To send multiple messages from a single Azure Function invocation you can apply the ServiceBus attribute to the IAsyncCollector<string> or IAsyncCollector<ServiceBusReceivedMessage> parameter.

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

Using binding to strongly-typed models

To use strongly-typed model classes with the ServiceBus binding apply the ServiceBus attribute to the model parameter. Doing so will attempt to deserialize the ServiceBusMessage.Bodyinto the strongly-typed model.

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

Sending multiple messages using ServiceBusSender

You can also bind to the ServiceBusSender directly to have the most control over message sending.

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

Per-message triggers

To run a function every time a message is sent to a Service Bus queue or subscription apply the ServiceBusTrigger attribute to a string, byte[], or ServiceBusReceivedMessage parameter.

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

Batch triggers

To run a function for a batch of received messages apply the ServiceBusTrigger attribute to a string[], or ServiceBusReceivedMessage[] parameter.

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

Message settlement

You can configure messages to be automatically completed after your function executes using the ServiceBusOptions. If you want more control over message settlement, you can bind to the MessageActions with both per-message and batch triggers.

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

Troubleshooting

Please refer to Monitor Azure Functions for troubleshooting guidance.

Next steps

Read the introduction to Azure Functions or creating an Azure Function guide.

Contributing

See our CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. 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. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release Notes

https://github.com/Azure/azure-sdk-for-net/blob/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.0.0-beta.4/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/CHANGELOG.md

NuGet packages (11)

Showing the top 5 NuGet packages that depend on Microsoft.Azure.WebJobs.Extensions.ServiceBus:

Package Downloads
MassTransit.WebJobs.ServiceBus
MassTransit Azure WebJobs Service Bus support; MassTransit is a message-based distributed application framework for .NET http://masstransit-project.com
CommentEverythingServiceBusConnectorNETCore
Connector for Microsoft Service Bus (Read and write to Topics and Queues). Makes reading and writing easier via batching and standardized methods.
NServiceBus.AzureFunctions.ServiceBus
NServiceBus.AzureFunctions.ServiceBus
NServiceBus.AzureFunctions.InProcess.ServiceBus
NServiceBus.AzureFunctions.InProcess.ServiceBus
Microsoft.Azure.Workflows.WebJobs.Extension
Extensions for running workflows in Azure Functions

GitHub repositories (14)

Showing the top 5 popular GitHub repositories that depend on Microsoft.Azure.WebJobs.Extensions.ServiceBus:

Repository Stars
MassTransit/MassTransit
Distributed Application Framework for .NET
Azure-Samples/cognitive-services-speech-sdk
Sample code for the Microsoft Cognitive Services Speech SDK
Azure/azure-webjobs-sdk
Azure WebJobs SDK
mspnp/cloud-design-patterns
Prescriptive Architecture Guidance for Cloud Applications
WolfgangOfner/MicroserviceDemo
This is a demo with two ASP .NET 5 microservices using RabbitMQ and Docker

Version History

Version Downloads Last updated
5.0.0-beta.6 655 9/8/2021
5.0.0-beta.5 8,857 7/9/2021
5.0.0-beta.4 6,580 6/22/2021
5.0.0-beta.3 11,482 5/19/2021
5.0.0-beta.2 10,735 4/9/2021
5.0.0-beta.1 9,388 3/24/2021
4.3.0 469,334 4/28/2021
4.2.2 87,677 4/14/2021
4.2.1 639,705 1/25/2021
4.2.0 952,038 9/23/2020
4.1.2 1,155,528 6/1/2020
4.1.1 899,242 3/3/2020
4.1.0 1,196,591 1/3/2020
4.0.0 265,477 11/19/2019
3.2.0 203,738 10/29/2019
3.1.1 313,924 10/1/2019
3.1.0 208,584 9/19/2019
3.1.0-beta4 11,956 8/5/2019
3.1.0-beta3 24,334 6/5/2019
3.1.0-beta2 4,692 5/10/2019
3.1.0-beta1 1,253 5/2/2019
3.0.6 717,652 6/26/2019
3.0.5 301,319 5/3/2019
3.0.4 166,438 3/29/2019
3.0.3 744,633 1/25/2019
3.0.2 187,015 12/5/2018
3.0.1 204,027 10/17/2018
3.0.0 376,521 9/19/2018
3.0.0-rc1 3,702 9/14/2018