Azure Servicebus Dotnet

作者 microsoft354361d83247MIT收录于 2026年10月8日更新于 2026年10月8日

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".

AI 生成的概览

使用 Azure.Messaging.ServiceBus .NET SDK 发送、接收和处理 Service Bus 消息的参考指南。

功能
该技能提供 Azure.Messaging.ServiceBus SDK 的 .NET 代码示例和指导,涵盖队列、主题、订阅、会话、死信处理、批处理和事务以及管理操作。它展示如何通过 Entra ID 或连接字符串配置身份验证,以及如何构建发送方、接收方和后台处理器。它还列出了关键类型、最佳实践和错误处理模式。
适用场景
适用于编写或审查与 Azure Service Bus 交互的 .NET 代码时,例如实现可靠消息传递、发布/订阅模式或后台处理。也适用于设置队列、主题和订阅,或处理死信消息。
运行要求
需要 .NET SDK 和 Azure.Messaging.ServiceBus NuGet 包,以及用于 Entra ID 身份验证的 Azure.Identity。需要 Azure Service Bus 命名空间以及连接字符串或凭据;需要访问 Azure 的网络连接。该技能仅包含说明和代码示例,不含脚本。

Azure.Messaging.ServiceBus (.NET)

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

Installation

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

Current Version: v7.20.1 (stable)

Environment Variables

bash
AZURE_SERVICEBUS_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net  # Required: Service Bus fully qualified namespaceAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in productionAZURE_SERVICEBUS_CONNECTION_STRING=Endpoint=sb://...  # Alternative to Entra ID auth

Authentication

Microsoft Entra Token Credential

csharp
using Azure.Identity;using Azure.Messaging.ServiceBus;
string fullyQualifiedNamespace = "<namespace>.servicebus.windows.net";// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes// var credential = new ManagedIdentityCredential();await using ServiceBusClient client = new(fullyQualifiedNamespace, credential);

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)

Core Workflows

1. Send Messages

csharp
await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());ServiceBusSender sender = client.CreateSender("my-queue");
// Single messageServiceBusMessage message = new("Hello world!");await sender.SendMessageAsync(message);
// Safe batching (recommended)using ServiceBusMessageBatch batch = await sender.CreateMessageBatchAsync();if (batch.TryAddMessage(new ServiceBusMessage("Message 1"))){    // Message added successfully}if (batch.TryAddMessage(new ServiceBusMessage("Message 2"))){    // Message added successfully}await sender.SendMessagesAsync(batch);

2. Receive Messages

csharp
ServiceBusReceiver receiver = client.CreateReceiver("my-queue");
// Single messageServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();string body = message.Body.ToString();Console.WriteLine(body);
// Complete the message (removes from queue)await receiver.CompleteMessageAsync(message);
// Batch receiveIReadOnlyList<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 queueawait receiver.CompleteMessageAsync(message);
// Abandon - releases lock, message can be received againawait receiver.AbandonMessageAsync(message);
// Defer - prevents normal receive, use ReceiveDeferredMessageAsyncawait receiver.DeferMessageAsync(message);
// Dead Letter - moves to dead letter subqueueawait 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 runsawait processor.StopProcessingAsync();

5. Sessions (Ordered Processing)

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

6. Dead Letter Queue

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

7. Topics and Subscriptions

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

8. Administration (CRUD)

csharp
var adminClient = new ServiceBusAdministrationClient(    fullyQualifiedNamespace,     new DefaultAzureCredential());
// Create queuevar options = new CreateQueueOptions("my-queue"){    MaxDeliveryCount = 10,    LockDuration = TimeSpan.FromSeconds(30),    RequiresSession = true,    DeadLetteringOnMessageExpiration = true};QueueProperties queue = await adminClient.CreateQueueAsync(options);
// Update queuequeue.LockDuration = TimeSpan.FromSeconds(60);await adminClient.UpdateQueueAsync(queue);
// Create topic and subscriptionawait adminClient.CreateTopicAsync(new CreateTopicOptions("my-topic"));await adminClient.CreateSubscriptionAsync(new CreateSubscriptionOptions("my-topic", "my-subscription"));
// Deleteawait 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

来源与署名

来源:microsoft/skills位于.github/plugins/azure-sdk-dotnet/skills/azure-servicebus-dotnet提交354361d

许可证: MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架