Microsoft.Azure.WebJobs.Extensions.ServiceBus
5.16.4
Prefix Reserved
dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.16.4
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.ServiceBus -Version 5.16.4
<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.ServiceBus" Version="5.16.4" />
paket add Microsoft.Azure.WebJobs.Extensions.ServiceBus --version 5.16.4
#r "nuget: Microsoft.Azure.WebJobs.Extensions.ServiceBus, 5.16.4"
// Install Microsoft.Azure.WebJobs.Extensions.ServiceBus as a Cake Addin #addin nuget:?package=Microsoft.Azure.WebJobs.Extensions.ServiceBus&version=5.16.4 // Install Microsoft.Azure.WebJobs.Extensions.ServiceBus as a Cake Tool #tool nuget:?package=Microsoft.Azure.WebJobs.Extensions.ServiceBus&version=5.16.4
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
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:
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.
Identity-based authentication
If your environment has managed identity enabled you can use it to authenticate the Service Bus extension. Before doing so, you will need to ensure that permissions have been configured as described in the Azure Functions developer guide.
To use identity-based authentication provide the <connection_name>__fullyQualifiedNamespace
configuration setting.
{
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"<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
More details about configuring an identity-based connection can be found here.
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.Body
into 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);
}
}
}
Session triggers
To receive messages from a session enabled queue or topic, you can set the IsSessionsEnabled
property on the ServiceBusTrigger
attribute. When working with sessions, you can bind to the SessionMessageActions
to get access to the message settlement methods in addition to session-specific functionality.
[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>"));
}
Binding to ReceiveActions
It's possible to receive additional messages from within your function invocation. This may be useful if you need more control over how many messages to process within a function invocation based on some characteristics of the initial message delivered to your function via the binding parameter. Any additional messages that you receive will be subject to the same AutoCompleteMessages
and MaxAutoLockRenewalDuration
configuration as the initial message delivered to your function. It is also possible to peek messages. Peeked messages are not subject to the AutoCompleteMessages
and MaxAutoLockRenewalDuration
configuration as these messages are not locked and therefore cannot be completed.
[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);
}
}
Binding to ServiceBusClient
There may be times when you want to bind to the same ServiceBusClient
that the trigger is using. This can be useful if you need to dynamically create a sender based on the message that is received.
[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));
}
Troubleshooting
If your function triggers an unhandled exception and you haven't already settled the message, the extension will attempt to abandon the message so that it becomes available for receiving again immediately.
Please refer to Monitor Azure Functions for more 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.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Messaging.ServiceBus (>= 7.18.1)
- Microsoft.Azure.WebJobs (>= 3.0.37)
- Microsoft.Extensions.Azure (>= 1.7.4)
-
net6.0
- Azure.Messaging.ServiceBus (>= 7.18.1)
- Google.Protobuf (>= 3.24.3)
- Microsoft.Azure.WebJobs (>= 3.0.37)
- Microsoft.Azure.WebJobs.Extensions.Rpc (>= 3.0.37)
- Microsoft.Extensions.Azure (>= 1.7.4)
NuGet packages (23)
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 provides a developer-focused, modern platform for creating distributed applications without complexity. |
|
NServiceBus.AzureFunctions.InProcess.ServiceBus
NServiceBus.AzureFunctions.InProcess.ServiceBus |
|
Microsoft.Azure.Workflows.WebJobs.Extension
Extensions for running workflows in Azure Functions |
|
UnitTestEx
UnitTestEx Test Extensions. |
|
Energinet.DataHub.Core.Messaging
[Release Notes](https://github.com/Energinet-DataHub/geh-core/blob/master/source/Messaging/documents/release-notes/release-notes.md) [Documentation](https://github.com/Energinet-DataHub/geh-core/blob/master/source/Messaging/documents/documentation.md) |
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
|
|
mspnp/cloud-design-patterns
Sample implementations for cloud design patterns found in the Azure Architecture Center.
|
|
Azure/azure-webjobs-sdk
Azure WebJobs SDK
|
|
WolfgangOfner/MicroserviceDemo
This is a demo with two ASP .NET 6 microservices using RabbitMQ and Docker
|
|
Chinchilla-Software-Com/CQRS
A lightweight enterprise Function as a Service (FaaS) framework to write function based serverless and micro-service applications in hybrid multi-datacentre, on-premise and Azure environments.
|
Version | Downloads | Last updated |
---|---|---|
5.16.4 | 135,584 | 8/8/2024 |
5.16.3 | 30,215 | 8/2/2024 |
5.16.2 | 23,694 | 7/25/2024 |
5.16.1 | 544,072 | 6/13/2024 |
5.16.0 | 176,652 | 5/30/2024 |
5.15.1 | 587,797 | 4/17/2024 |
5.14.0 | 305,017 | 3/14/2024 |
5.13.6 | 87,287 | 3/5/2024 |
5.13.5 | 1,985,089 | 12/4/2023 |
5.13.4 | 997,882 | 11/9/2023 |
5.13.3 | 697,313 | 10/20/2023 |
5.13.2 | 62,595 | 10/18/2023 |
5.13.1 | 333,652 | 10/17/2023 |
5.13.0 | 72,343 | 10/11/2023 |
5.12.0 | 1,240,864 | 8/14/2023 |
5.11.0 | 1,491,345 | 6/6/2023 |
5.10.0 | 345,550 | 5/10/2023 |
5.9.0 | 1,558,427 | 2/23/2023 |
5.8.1 | 2,923,207 | 11/10/2022 |
5.8.0 | 1,039,269 | 10/11/2022 |
5.7.0 | 3,097,338 | 8/12/2022 |
5.6.0 | 369,002 | 7/28/2022 |
5.5.1 | 1,190,445 | 6/8/2022 |
5.5.0 | 635,142 | 5/17/2022 |
5.4.0 | 598,089 | 5/11/2022 |
5.3.0 | 1,396,798 | 3/9/2022 |
5.2.0 | 1,891,690 | 12/9/2021 |
5.1.0 | 522,474 | 11/11/2021 |
5.0.0 | 341,737 | 10/26/2021 |
5.0.0-beta.6 | 88,764 | 9/8/2021 |
5.0.0-beta.5 | 132,135 | 7/9/2021 |
5.0.0-beta.4 | 33,530 | 6/22/2021 |
5.0.0-beta.3 | 34,944 | 5/19/2021 |
5.0.0-beta.2 | 25,047 | 4/9/2021 |
5.0.0-beta.1 | 35,013 | 3/24/2021 |
4.3.1 | 484,318 | 6/3/2022 |
4.3.0 | 4,350,653 | 4/28/2021 |
4.2.2 | 483,282 | 4/14/2021 |
4.2.1 | 3,220,684 | 1/25/2021 |
4.2.0 | 1,940,540 | 9/23/2020 |
4.1.2 | 1,886,945 | 6/1/2020 |
4.1.1 | 1,225,982 | 3/3/2020 |
4.1.0 | 2,262,932 | 1/3/2020 |
4.0.0 | 376,319 | 11/19/2019 |
3.2.0 | 311,334 | 10/29/2019 |
3.1.1 | 423,776 | 10/1/2019 |
3.1.0 | 267,092 | 9/19/2019 |
3.1.0-beta4 | 19,198 | 8/5/2019 |
3.1.0-beta3 | 26,970 | 6/5/2019 |
3.1.0-beta2 | 7,444 | 5/10/2019 |
3.1.0-beta1 | 3,474 | 5/2/2019 |
3.0.6 | 900,531 | 6/26/2019 |
3.0.5 | 359,891 | 5/3/2019 |
3.0.4 | 218,937 | 3/29/2019 |
3.0.3 | 959,128 | 1/25/2019 |
3.0.2 | 232,387 | 12/5/2018 |
3.0.1 | 253,562 | 10/17/2018 |
3.0.0 | 478,234 | 9/19/2018 |
3.0.0-rc1 | 6,013 | 9/14/2018 |