---

name: azure-servicebus-dotnet description: Azure Service Bus .NET SDK。企业级消息传递，支持队列、主题、订阅和会话。 risk: unknown source: community date_added: '2026-02-27'

Azure.Messaging.ServiceBus (.NET)

企业级消息传递 SDK，支持通过队列、主题、订阅和会话实现可靠的消息投递。

安装

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

当前版本：v7.20.1（稳定版）

环境变量

AZURE_SERVICEBUS_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net
# 或使用连接字符串（安全性较低）
AZURE_SERVICEBUS_CONNECTION_STRING=Endpoint=sb://...

身份验证

Microsoft Entra ID（推荐）

using Azure.Identity;
using Azure.Messaging.ServiceBus;

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

连接字符串

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

ASP.NET Core 依赖注入

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

客户端层级结构

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

ServiceBusAdministrationClient（独立客户端，用于 CRUD 操作）

核心工作流

1. 发送消息

await using ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential());
ServiceBusSender sender = client.CreateSender("my-queue");

// 单条消息
ServiceBusMessage message = new("Hello world!");
await sender.SendMessageAsync(message);

// 安全批量发送（推荐）
using ServiceBusMessageBatch batch = await sender.CreateMessageBatchAsync();
if (batch.TryAddMessage(new ServiceBusMessage("Message 1")))
{
    // 消息添加成功
}
if (batch.TryAddMessage(new ServiceBusMessage("Message 2")))
{
    // 消息添加成功
}
await sender.SendMessagesAsync(batch);

2. 接收消息

ServiceBusReceiver receiver = client.CreateReceiver("my-queue");

// 单条消息
ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();
string body = message.Body.ToString();
Console.WriteLine(body);

// 完成消息（从队列中移除）
await receiver.CompleteMessageAsync(message);

// 批量接收
IReadOnlyList<ServiceBusReceivedMessage> messages = await receiver.ReceiveMessagesAsync(maxMessages: 10);
foreach (var msg in messages)
{
    Console.WriteLine(msg.Body.ToString());
    await receiver.CompleteMessageAsync(msg);
}

3. 消息处置

// 完成 - 从队列中移除消息
await receiver.CompleteMessageAsync(message);

// 放弃 - 释放锁定，消息可被重新接收
await receiver.AbandonMessageAsync(message);

// 延迟 - 阻止正常接收，需使用 ReceiveDeferredMessageAsync 获取
await receiver.DeferMessageAsync(message);

// 死信 - 移至死信子队列
await receiver.DeadLetterMessageAsync(message, "InvalidFormat", "Message body was not valid JSON");

4. 使用处理器进行后台处理

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();
// ... 应用运行中
await processor.StopProcessingAsync();

5. 会话（有序处理）

// 发送会话消息
ServiceBusMessage message = new("Hello")
{
    SessionId = "order-123"
};
await sender.SendMessageAsync(message);

// 从下一个可用会话接收
ServiceBusSessionReceiver receiver = await client.AcceptNextSessionAsync("my-queue");

// 或从指定会话接收
ServiceBusSessionReceiver receiver = await client.AcceptSessionAsync("my-queue", "order-123");