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 從公開儲存庫中收錄這些內容。

檢舉或申請下架