<< All versions

Skill v1.0.1

currentAutomated scan100/100
sickn33/agentic-awesome-skills/azure-servicebus-dotnet

+4 new

──Details
PublishedOctober 29, 2026 at 10:17 PM
Content Hashsha256:22d08ad3d9e79832...
Git SHA753c5f7bb646
Bump Typepatch
Compare with v1.0.0
──Files
Files (1 file, 11.5 KB)
SKILL.md11.5 KBactive
SKILL.md · 344 lines · 11.5 KB

name: azure-servicebus-dotnet description: Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. risk: critical source: community date_added: '2026-02-27' metadata: version: "1.0.1"


Azure.Messaging.ServiceBus (.NET)

Enterprise messaging SDK for reliable message delivery with queues, topics, subscriptions, and sessions.

Installation

bash
dotnet add package Azure.Messaging.ServiceBus
dotnet add package Azure.Identity

Example SDK baseline: v7.20.1; verify the installed package and compatible API before adapting snippets.

Environment Variables

bash
AZURE_SERVICEBUS_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net
# Or connection string (less secure)
AZURE_SERVICEBUS_CONNECTION_STRING=Endpoint=sb://...

Authentication

Microsoft Entra ID (Recommended)

csharp
using Azure.Identity;
using Azure.Messaging.ServiceBus;
string fullyQualifiedNamespace = "<namespace>.servicebus.windows.net";
await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());

Connection String

csharp
string connectionString = "<connection_string>";
await using ServiceBusClient client = new(connectionString);

ASP.NET Core Dependency Injection

csharp
services.AddAzureClients(builder =>
{
builder.AddServiceBusClientWithNamespace("<namespace>.servicebus.windows.net");
builder.UseCredential(new DefaultAzureCredential());
});

Client Hierarchy

ServiceBusClient
├── CreateSender(queueOrTopicName) → ServiceBusSender
├── CreateReceiver(queueName) → ServiceBusReceiver
├── CreateReceiver(topicName, subName) → ServiceBusReceiver
├── AcceptNextSessionAsync(queueName) → ServiceBusSessionReceiver
├── CreateProcessor(queueName) → ServiceBusProcessor
└── CreateSessionProcessor(queueName) → ServiceBusSessionProcessor
ServiceBusAdministrationClient (separate client for CRUD)

Use separate snippets independently and import Azure.Messaging.ServiceBus.Administration for CRUD and System.Transactions for TransactionScope. Confirm namespace/entity and least-privilege sender/receiver/admin roles. Receive can return null; DLQ and transaction examples also need that guard. Completing removes a message: perform the durable business operation first, make it idempotent for redelivery and reconcile uncertain sends/settlements. Abandoning every exception can create poison-message loops. Do not log message bodies or raw exceptions containing sensitive payloads. Session-enabled queues require session receivers; the basic receive example is for a different non-session queue. Processors need async disposal and bounded lock-renewal/shutdown policies.

Core Workflows

1. Send Messages

csharp
await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());
ServiceBusSender sender = client.CreateSender("my-queue");
// Single message
ServiceBusMessage message = new("Hello world!");
await sender.SendMessageAsync(message);
// Safe batching (recommended)
using ServiceBusMessageBatch batch = await sender.CreateMessageBatchAsync();
if (!batch.TryAddMessage(new ServiceBusMessage("Message 1")))
throw new InvalidOperationException("Message 1 exceeds the batch capacity");
if (!batch.TryAddMessage(new ServiceBusMessage("Message 2")))
throw new InvalidOperationException("Message 2 exceeds remaining batch capacity; flush and retry in a new batch");
await sender.SendMessagesAsync(batch);

2. Receive Messages

csharp
ServiceBusReceiver receiver = client.CreateReceiver("my-queue");
// Single message
ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();
if (message is null) return; // A timed receive can return no message
string body = message.Body.ToString();
Console.WriteLine(body);
// Complete the message (removes from queue)
await receiver.CompleteMessageAsync(message);
// Batch receive
IReadOnlyList<ServiceBusReceivedMessage> messages = await receiver.ReceiveMessagesAsync(maxMessages: 10);
foreach (var msg in messages)
{
Console.WriteLine(msg.Body.ToString());
await receiver.CompleteMessageAsync(msg);
}

3. Message Settlement

csharp
// Complete - removes message from queue
await receiver.CompleteMessageAsync(message);
// Abandon - releases lock, message can be received again
await receiver.AbandonMessageAsync(message);
// Defer - prevents normal receive, use ReceiveDeferredMessageAsync
await receiver.DeferMessageAsync(message);
// Dead Letter - moves to dead letter subqueue
await receiver.DeadLetterMessageAsync(message, "InvalidFormat", "Message body was not valid JSON");

4. Background Processing with Processor

csharp
ServiceBusProcessor processor = client.CreateProcessor("my-queue", new ServiceBusProcessorOptions
{
AutoCompleteMessages = false,
MaxConcurrentCalls = 2
});
processor.ProcessMessageAsync += async (args) =>
{
try
{
string body = args.Message.Body.ToString();
Console.WriteLine($"Received: {body}");
await args.CompleteMessageAsync(args.Message);
}
catch (Exception ex)
{
Console.WriteLine($"Error processing: {ex.Message}");
await args.AbandonMessageAsync(args.Message);
}
};
processor.ProcessErrorAsync += (args) =>
{
Console.WriteLine($"Error source: {args.ErrorSource}");
Console.WriteLine($"Entity: {args.EntityPath}");
Console.WriteLine($"Exception: {args.Exception}");
return Task.CompletedTask;
};
await processor.StartProcessingAsync();
// ... application runs
await processor.StopProcessingAsync();

5. Sessions (Ordered Processing)

csharp
// Send session message
ServiceBusMessage message = new("Hello")
{
SessionId = "order-123"
};
await sender.SendMessageAsync(message);
// Receive from next available session
ServiceBusSessionReceiver receiver = await client.AcceptNextSessionAsync("my-queue");
// Or receive from specific session
ServiceBusSessionReceiver receiver = await client.AcceptSessionAsync("my-queue", "order-123");
// Session state management
await receiver.SetSessionStateAsync(new BinaryData("processing"));
BinaryData state = await receiver.GetSessionStateAsync();
// Renew session lock
await receiver.RenewSessionLockAsync();

6. Dead Letter Queue

csharp
// Receive from dead letter queue
ServiceBusReceiver dlqReceiver = client.CreateReceiver("my-queue", new ServiceBusReceiverOptions
{
SubQueue = SubQueue.DeadLetter
});
ServiceBusReceivedMessage dlqMessage = await dlqReceiver.ReceiveMessageAsync();
// Access dead letter metadata
string reason = dlqMessage.DeadLetterReason;
string description = dlqMessage.DeadLetterErrorDescription;
Console.WriteLine($"Dead letter reason: {reason} - {description}");

7. Topics and Subscriptions

csharp
// Send to topic
ServiceBusSender topicSender = client.CreateSender("my-topic");
await topicSender.SendMessageAsync(new ServiceBusMessage("Broadcast message"));
// Receive from subscription
ServiceBusReceiver subReceiver = client.CreateReceiver("my-topic", "my-subscription");
var message = await subReceiver.ReceiveMessageAsync();

8. Administration (CRUD)

csharp
var adminClient = new ServiceBusAdministrationClient(
fullyQualifiedNamespace,
new DefaultAzureCredential());
// Create queue
var options = new CreateQueueOptions("my-queue")
{
MaxDeliveryCount = 10,
LockDuration = TimeSpan.FromSeconds(30),
RequiresSession = true,
DeadLetteringOnMessageExpiration = true
};
QueueProperties queue = await adminClient.CreateQueueAsync(options);
// Update queue
queue.LockDuration = TimeSpan.FromSeconds(60);
await adminClient.UpdateQueueAsync(queue);
// Create topic and subscription
await adminClient.CreateTopicAsync(new CreateTopicOptions("my-topic"));
await adminClient.CreateSubscriptionAsync(new CreateSubscriptionOptions("my-topic", "my-subscription"));
// Delete
await adminClient.DeleteQueueAsync("my-queue");

9. Cross-Entity Transactions

csharp
var options = new ServiceBusClientOptions { EnableCrossEntityTransactions = true };
await using var client = new ServiceBusClient(connectionString, options);
ServiceBusReceiver receiverA = client.CreateReceiver("queueA");
ServiceBusSender senderB = client.CreateSender("queueB");
ServiceBusReceivedMessage receivedMessage = await receiverA.ReceiveMessageAsync();
using (var ts = new TransactionScope(TransactionScopeAsyncFlowOption.Enabled))
{
await receiverA.CompleteMessageAsync(receivedMessage);
await senderB.SendMessageAsync(new ServiceBusMessage("Forwarded"));
ts.Complete();
}

Key Types Reference

TypePurpose
ServiceBusClientMain entry point, manages connection
ServiceBusSenderSends messages to queues/topics
ServiceBusReceiverReceives messages from queues/subscriptions
ServiceBusSessionReceiverReceives session messages
ServiceBusProcessorBackground message processing
ServiceBusSessionProcessorBackground session processing
ServiceBusAdministrationClientCRUD for queues/topics/subscriptions
ServiceBusMessageMessage to send
ServiceBusReceivedMessageReceived message with metadata
ServiceBusMessageBatchBatch of messages

Best Practices

  1. Use singletons — Clients, senders, receivers, and processors are thread-safe
  2. Always dispose — Use await using or call DisposeAsync()
  3. Dispose order — Close senders/receivers/processors first, then client
  4. Use DefaultAzureCredential — Prefer over connection strings for production
  5. Use processors for background work — Handles lock renewal automatically
  6. Use safe batching — CreateMessageBatchAsync() and TryAddMessage()
  7. Handle transient errors — Use ServiceBusException.Reason
  8. Configure transport — Use AmqpWebSockets if ports 5671/5672 are blocked
  9. Set appropriate lock duration — Default is 30 seconds
  10. Use sessions for ordering — FIFO within a session

Error Handling

csharp
try
{
await sender.SendMessageAsync(message);
}
catch (ServiceBusException ex) when (ex.Reason == ServiceBusFailureReason.ServiceBusy)
{
// Retry with backoff
}
catch (ServiceBusException ex)
{
Console.WriteLine($"Service Bus Error: {ex.Reason} - {ex.Message}");
}

Related SDKs

SDKPurposeInstall
Azure.Messaging.ServiceBusService Bus (this SDK)dotnet add package Azure.Messaging.ServiceBus
Azure.Messaging.EventHubsEvent streamingdotnet add package Azure.Messaging.EventHubs
Azure.Messaging.EventGridEvent routingdotnet add package Azure.Messaging.EventGrid

Reference Links

ResourceURL
NuGet Packagehttps://www.nuget.org/packages/Azure.Messaging.ServiceBus
API Referencehttps://learn.microsoft.com/dotnet/api/azure.messaging.servicebus
GitHub Sourcehttps://github.com/Azure/azure-sdk-for-net/tree/main/sdk/servicebus/Azure.Messaging.ServiceBus
Troubleshootinghttps://github.com/Azure/azure-sdk-for-net/blob/main/sdk/servicebus/Azure.Messaging.ServiceBus/TROUBLESHOOTING.md

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
← v1.0.0All versions