Azure Servicebus Dotnet

1---
2name: azure-servicebus-dotnet
3description: |
4  Azure Service Bus SDK for .NET. Enterprise messaging with queues, topics, subscriptions, and sessions. Use for reliable message delivery, pub/sub patterns, dead letter handling, and background processing. Triggers: "Service Bus", "ServiceBusClient", "ServiceBusSender", "ServiceBusReceiver", "ServiceBusProcessor", "message queue", "pub/sub .NET", "dead letter queue".
5package: Azure.Messaging.ServiceBus
6---
7 
8# Azure.Messaging.ServiceBus (.NET)
9 
10Enterprise messaging SDK for reliable message delivery with queues, topics, subscriptions, and sessions.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.Messaging.ServiceBus
16dotnet add package Azure.Identity
17```
18 
19**Current Version**: v7.20.1 (stable)
20 
21## Environment Variables
22 
23```bash
24AZURE_SERVICEBUS_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net
25# Or connection string (less secure)
26AZURE_SERVICEBUS_CONNECTION_STRING=Endpoint=sb://...
27```
28 
29## Authentication
30 
31### Microsoft Entra ID (Recommended)
32 
33```csharp
34using Azure.Identity;
35using Azure.Messaging.ServiceBus;
36 
37string fullyQualifiedNamespace = "<namespace>.servicebus.windows.net";
38await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());
39```
40 
41### Connection String
42 
43```csharp
44string connectionString = "<connection_string>";
45await using ServiceBusClient client = new(connectionString);
46```
47 
48### ASP.NET Core Dependency Injection
49 
50```csharp
51services.AddAzureClients(builder =>
52{
53    builder.AddServiceBusClientWithNamespace("<namespace>.servicebus.windows.net");
54    builder.UseCredential(new DefaultAzureCredential());
55});
56```
57 
58## Client Hierarchy
59 
60```
61ServiceBusClient
62├── CreateSender(queueOrTopicName)      → ServiceBusSender
63├── CreateReceiver(queueName)           → ServiceBusReceiver
64├── CreateReceiver(topicName, subName)  → ServiceBusReceiver
65├── AcceptNextSessionAsync(queueName)   → ServiceBusSessionReceiver
66├── CreateProcessor(queueName)          → ServiceBusProcessor
67└── CreateSessionProcessor(queueName)   → ServiceBusSessionProcessor
68 
69ServiceBusAdministrationClient (separate client for CRUD)
70```
71 
72## Core Workflows
73 
74### 1. Send Messages
75 
76```csharp
77await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());
78ServiceBusSender sender = client.CreateSender("my-queue");
79 
80// Single message
81ServiceBusMessage message = new("Hello world!");
82await sender.SendMessageAsync(message);
83 
84// Safe batching (recommended)
85using ServiceBusMessageBatch batch = await sender.CreateMessageBatchAsync();
86if (batch.TryAddMessage(new ServiceBusMessage("Message 1")))
87{
88    // Message added successfully
89}
90if (batch.TryAddMessage(new ServiceBusMessage("Message 2")))
91{
92    // Message added successfully
93}
94await sender.SendMessagesAsync(batch);
95```
96 
97### 2. Receive Messages
98 
99```csharp
100ServiceBusReceiver receiver = client.CreateReceiver("my-queue");
101 
102// Single message
103ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();
104string body = message.Body.ToString();
105Console.WriteLine(body);
106 
107// Complete the message (removes from queue)
108await receiver.CompleteMessageAsync(message);
109 
110// Batch receive
111IReadOnlyList<ServiceBusReceivedMessage> messages = await receiver.ReceiveMessagesAsync(maxMessages: 10);
112foreach (var msg in messages)
113{
114    Console.WriteLine(msg.Body.ToString());
115    await receiver.CompleteMessageAsync(msg);
116}
117```
118 
119### 3. Message Settlement
120 
121```csharp
122// Complete - removes message from queue
123await receiver.CompleteMessageAsync(message);
124 
125// Abandon - releases lock, message can be received again
126await receiver.AbandonMessageAsync(message);
127 
128// Defer - prevents normal receive, use ReceiveDeferredMessageAsync
129await receiver.DeferMessageAsync(message);
130 
131// Dead Letter - moves to dead letter subqueue
132await receiver.DeadLetterMessageAsync(message, "InvalidFormat", "Message body was not valid JSON");
133```
134 
135### 4. Background Processing with Processor
136 
137```csharp
138ServiceBusProcessor processor = client.CreateProcessor("my-queue", new ServiceBusProcessorOptions
139{
140    AutoCompleteMessages = false,
141    MaxConcurrentCalls = 2
142});
143 
144processor.ProcessMessageAsync += async (args) =>
145{
146    try
147    {
148        string body = args.Message.Body.ToString();
149        Console.WriteLine($"Received: {body}");
150        await args.CompleteMessageAsync(args.Message);
151    }
152    catch (Exception ex)
153    {
154        Console.WriteLine($"Error processing: {ex.Message}");
155        await args.AbandonMessageAsync(args.Message);
156    }
157};
158 
159processor.ProcessErrorAsync += (args) =>
160{
161    Console.WriteLine($"Error source: {args.ErrorSource}");
162    Console.WriteLine($"Entity: {args.EntityPath}");
163    Console.WriteLine($"Exception: {args.Exception}");
164    return Task.CompletedTask;
165};
166 
167await processor.StartProcessingAsync();
168// ... application runs
169await processor.StopProcessingAsync();
170```
171 
172### 5. Sessions (Ordered Processing)
173 
174```csharp
175// Send session message
176ServiceBusMessage message = new("Hello")
177{
178    SessionId = "order-123"
179};
180await sender.SendMessageAsync(message);
181 
182// Receive from next available session
183ServiceBusSessionReceiver receiver = await client.AcceptNextSessionAsync("my-queue");
184 
185// Or receive from specific session
186ServiceBusSessionReceiver receiver = await client.AcceptSessionAsync("my-queue", "order-123");
187 
188// Session state management
189await receiver.SetSessionStateAsync(new BinaryData("processing"));
190BinaryData state = await receiver.GetSessionStateAsync();
191 
192// Renew session lock
193await receiver.RenewSessionLockAsync();
194```
195 
196### 6. Dead Letter Queue
197 
198```csharp
199// Receive from dead letter queue
200ServiceBusReceiver dlqReceiver = client.CreateReceiver("my-queue", new ServiceBusReceiverOptions
201{
202    SubQueue = SubQueue.DeadLetter
203});
204 
205ServiceBusReceivedMessage dlqMessage = await dlqReceiver.ReceiveMessageAsync();
206 
207// Access dead letter metadata
208string reason = dlqMessage.DeadLetterReason;
209string description = dlqMessage.DeadLetterErrorDescription;
210Console.WriteLine($"Dead letter reason: {reason} - {description}");
211```
212 
213### 7. Topics and Subscriptions
214 
215```csharp
216// Send to topic
217ServiceBusSender topicSender = client.CreateSender("my-topic");
218await topicSender.SendMessageAsync(new ServiceBusMessage("Broadcast message"));
219 
220// Receive from subscription
221ServiceBusReceiver subReceiver = client.CreateReceiver("my-topic", "my-subscription");
222var message = await subReceiver.ReceiveMessageAsync();
223```
224 
225### 8. Administration (CRUD)
226 
227```csharp
228var adminClient = new ServiceBusAdministrationClient(
229    fullyQualifiedNamespace, 
230    new DefaultAzureCredential());
231 
232// Create queue
233var options = new CreateQueueOptions("my-queue")
234{
235    MaxDeliveryCount = 10,
236    LockDuration = TimeSpan.FromSeconds(30),
237    RequiresSession = true,
238    DeadLetteringOnMessageExpiration = true
239};
240QueueProperties queue = await adminClient.CreateQueueAsync(options);
241 
242// Update queue
243queue.LockDuration = TimeSpan.FromSeconds(60);
244await adminClient.UpdateQueueAsync(queue);
245 
246// Create topic and subscription
247await adminClient.CreateTopicAsync(new CreateTopicOptions("my-topic"));
248await adminClient.CreateSubscriptionAsync(new CreateSubscriptionOptions("my-topic", "my-subscription"));
249 
250// Delete
251await adminClient.DeleteQueueAsync("my-queue");
252```
253 
254### 9. Cross-Entity Transactions
255 
256```csharp
257var options = new ServiceBusClientOptions { EnableCrossEntityTransactions = true };
258await using var client = new ServiceBusClient(connectionString, options);
259 
260ServiceBusReceiver receiverA = client.CreateReceiver("queueA");
261ServiceBusSender senderB = client.CreateSender("queueB");
262 
263ServiceBusReceivedMessage receivedMessage = await receiverA.ReceiveMessageAsync();
264 
265using (var ts = new TransactionScope(TransactionScopeAsyncFlowOption.Enabled))
266{
267    await receiverA.CompleteMessageAsync(receivedMessage);
268    await senderB.SendMessageAsync(new ServiceBusMessage("Forwarded"));
269    ts.Complete();
270}
271```
272 
273## Key Types Reference
274 
275| Type | Purpose |
276|------|---------|
277| `ServiceBusClient` | Main entry point, manages connection |
278| `ServiceBusSender` | Sends messages to queues/topics |
279| `ServiceBusReceiver` | Receives messages from queues/subscriptions |
280| `ServiceBusSessionReceiver` | Receives session messages |
281| `ServiceBusProcessor` | Background message processing |
282| `ServiceBusSessionProcessor` | Background session processing |
283| `ServiceBusAdministrationClient` | CRUD for queues/topics/subscriptions |
284| `ServiceBusMessage` | Message to send |
285| `ServiceBusReceivedMessage` | Received message with metadata |
286| `ServiceBusMessageBatch` | Batch of messages |
287 
288## Best Practices
289 
2901. **Use singletons** — Clients, senders, receivers, and processors are thread-safe
2912. **Always dispose** — Use `await using` or call `DisposeAsync()`
2923. **Dispose order** — Close senders/receivers/processors first, then client
2934. **Use DefaultAzureCredential** — Prefer over connection strings for production
2945. **Use processors for background work** — Handles lock renewal automatically
2956. **Use safe batching** — `CreateMessageBatchAsync()` and `TryAddMessage()`
2967. **Handle transient errors** — Use `ServiceBusException.Reason`
2978. **Configure transport** — Use `AmqpWebSockets` if ports 5671/5672 are blocked
2989. **Set appropriate lock duration** — Default is 30 seconds
29910. **Use sessions for ordering** — FIFO within a session
300 
301## Error Handling
302 
303```csharp
304try
305{
306    await sender.SendMessageAsync(message);
307}
308catch (ServiceBusException ex) when (ex.Reason == ServiceBusFailureReason.ServiceBusy)
309{
310    // Retry with backoff
311}
312catch (ServiceBusException ex)
313{
314    Console.WriteLine($"Service Bus Error: {ex.Reason} - {ex.Message}");
315}
316```
317 
318## Related SDKs
319 
320| SDK | Purpose | Install |
321|-----|---------|---------|
322| `Azure.Messaging.ServiceBus` | Service Bus (this SDK) | `dotnet add package Azure.Messaging.ServiceBus` |
323| `Azure.Messaging.EventHubs` | Event streaming | `dotnet add package Azure.Messaging.EventHubs` |
324| `Azure.Messaging.EventGrid` | Event routing | `dotnet add package Azure.Messaging.EventGrid` |
325 
326## Reference Links
327 
328| Resource | URL |
329|----------|-----|
330| NuGet Package | https://www.nuget.org/packages/Azure.Messaging.ServiceBus |
331| API Reference | https://learn.microsoft.com/dotnet/api/azure.messaging.servicebus |
332| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/servicebus/Azure.Messaging.ServiceBus |
333| Troubleshooting | https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/servicebus/Azure.Messaging.ServiceBus/TROUBLESHOOTING.md |
334