你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Functions 的 Azure 服务总线绑定

2025-05-20

Azure Functions 通过触发器和绑定与 Azure 服务总线集成。与服务总线集成后，你可以构建响应和发送队列或主题消息的函数。

操作	类型
创建服务总线队列或主题消息时运行函数	触发器
发送 Azure 服务总线消息	输出绑定

安装扩展

你安装的扩展 NuGet 包取决于你在函数应用中使用的 C# 模式：

独立工作模型
进程模型

函数在独立的 C# 工作进程中执行。若要了解详细信息，请参阅有关在独立工作进程中运行 C# Azure Functions 的指南。

通过安装此 NuGet 包将该扩展添加到你的项目。

扩展的功能因扩展版本而异：

此版本引入了使用标识而不是机密进行连接的功能。有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

此版本允许绑定到 Azure.Messaging.ServiceBus 中的类型。

此版本支持通过 .NET Aspire 集成配置触发器和绑定。

通过安装 NuGet 包版本 5.x 将该扩展添加到你的项目。

安装捆绑包

服务总线绑定是在 host.json 项目文件中指定的扩展捆绑包的一部分。如果尚未安装捆绑包，你可能需要修改此捆绑包才能更改绑定的版本。若要了解详细信息，请参阅扩展捆绑包。

此版本引入了使用标识而不是机密进行连接的功能。有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

可以通过在 host.json 文件中添加或替换以下代码，从扩展捆绑包 v3 添加该扩展的这一版本：

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

若要了解详细信息，请参阅更新扩展。

绑定类型

.NET 支持的绑定类型取决于扩展版本和 C# 执行模式，可以是以下类型之一：

独立工作模型
进程内类库

独立工作进程类库的已编译 C# 函数在独立于运行时的进程中运行。

请选择一个版本来查看模式和版本的绑定类型详细信息。

服务总线扩展支持下表所示的参数类型。

绑定方案	参数类型
服务总线触发器（单个消息）	ServiceBusReceivedMessage `string` `byte[]` JSON 可序列化类型¹
服务总线触发器（消息批次）	`ServiceBusReceivedMessage[]` `string[]`
服务总线触发器高级方案²	ServiceBusClient ServiceBusMessageActions ServiceBusSessionMessageActions ServiceBusReceiveActions
服务总线输出（消息）	ServiceBusMessage `string` `byte[]` JSON 可序列化类型¹
服务总线输出（多个消息）	`ICollector<T>` 或 `IAsyncCollector<T>`，其中 `T` 是单消息类型之一 ServiceBusSender

¹ 包含 JSON 数据的消息可以反序列化为已知的普通旧 CLR 对象 (POCO) 类型。

² 高级方案包括消息结算、会话和事务。除了常规触发器参数之外，这些类型还可用作单独的参数。

早期版本的扩展公开了现已弃用的 Microsoft.Azure.ServiceBus 命名空间中的类型。 Azure.Messaging.ServiceBus 中的较新类型专用于扩展 5.x+。

2026 年 9 月 30 日，我们将停用 Azure 服务总线 SDK 库 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus，这些库不符合 Azure SDK 准则。我们还将结束对 SBMP 协议的支持，因此在 2026 年 9 月 30 日之后，你将无法再使用此协议。请在该日期之前迁移到最新的 Azure SDK 库，新库提供了关键安全更新和改进功能。

尽管 2026 年 9 月 30 日之后仍然可以使用较旧的库，但它们将不再获得 Microsoft 的官方支持和更新。有关详细信息，请参阅支持停用公告。

此版本的扩展支持下表所示的参数类型。

服务总线扩展支持下表所示的参数类型。

绑定方案	参数类型
服务总线触发器（单个消息）	[Microsoft.Azure.ServiceBus.Message] `string` `byte[]` JSON 可序列化类型¹
服务总线触发器（消息批次）	`ServiceBusReceivedMessage[]` `string[]`
服务总线触发器高级方案²	IMessageReceiver MessageReceiver IMessageSession
服务总线输出（消息）	消息 `string` `byte[]` JSON 可序列化类型¹
服务总线输出（多个消息）	`ICollector<T>` 或 `IAsyncCollector<T>`，其中 `T` 是单消息类型之一 MessageSender

¹ 包含 JSON 数据的消息可以反序列化为已知的普通旧 CLR 对象 (POCO) 类型。

² 高级方案包括消息结算、会话和事务。除了常规触发器参数之外，这些类型还可用作单独的参数。

独立工作进程支持下表所示的参数类型。

服务总线触发器

如果希望函数处理单条消息，服务总线触发器可以绑定到以下类型：

类型	说明
`string`	字符串格式的消息。当消息为简单文本时使用。
`byte[]`	消息的字节数。
JSON 可序列化类型	当事件包含 JSON 数据时，Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
ServiceBusReceivedMessage¹	消息对象。绑定到`ServiceBusReceivedMessage`时，还可以选择包含 ServiceBusMessageActions^{1,2 类型的}参数来执行消息解决作。

如果希望函数处理一批消息，服务总线触发器可以绑定到以下类型：

类型	说明
`T[]`，其中 `T` 是单消息类型之一	批处理中的事件数组。每个条目表示一个事件。绑定到`ServiceBusReceivedMessage[]`时，还可以选择包含 ServiceBusMessageActions^{1,2 类型的}参数来执行消息解决作。

¹ 要使用这些类型，需要引用 Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 或更高版本以及 SDK 类型绑定的常见依赖项。

² 使用时，将ServiceBusMessageActions的属性设置为 AutoCompleteMessages。这可以防止运行时在成功调用函数后尝试完成消息。

服务总线输出绑定

如果希望函数写入单个消息，服务总线输出绑定可以绑定到以下类型：

类型	说明
`string`	字符串格式的消息。当消息为简单文本时使用。
`byte[]`	消息的字节数。
JSON 可序列化类型	表示消息的对象。函数尝试将普通旧 CLR 对象 (POCO) 类型序列化为 JSON 数据。

如果希望函数写入多个消息，服务总线输出绑定可以绑定到以下类型：

类型	说明
`T[]`，其中 `T` 是单消息类型之一	包含多个消息的数组。每个条目表示一个消息。

对于其他输出方案，请直接在 Azure.Messaging.ServiceBus 中创建和使用 ServiceBusClient 和其他类型的服务总线。有关使用依赖项注入从 Azure SDK 创建客户端类型的示例，请参阅 “注册 Azure 客户端 ”。

SDK 绑定类型

Azure 服务总线的 SDK 类型为预览版。按照适用于服务总线的 Python SDK 绑定示例开始使用 Python 中的服务总线的 SDK 类型。

重要

使用 SDK 类型绑定需要 Python v2 编程模型。

捆绑	参数类型	示例
ServiceBus 触发器	ServiceBusReceivedMessage	`ServiceBusReceivedMessage`

host.json 设置

本部分介绍可用于此绑定的配置设置，具体取决于运行时和扩展版本。

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

clientRetryOptions 设置仅适用于与服务总线服务的交互。它们不影响函数执行的重试。有关详细信息，请参阅重试。

属性	默认	说明
模式	`Exponential`	用于计算重试延迟的方法。默认指数模式将根据一个回退策略来重试带延迟的尝试，该策略规定每次尝试都会增加重试前的等待时间。 `Fixed` 模式会按固定间隔重试，每个延迟的持续时间一致。
tryTimeout	`00:01:00`	每次尝试等待操作的最大持续时间。
延迟	`00:00:00.80`	要在两次重试之间应用的延迟或回退因子。
maxDelay	`00:01:00`	允许出现在两次重试之间的最大延迟
maxRetries	`3`	将关联的操作视为失败之前的最大重试次数。
prefetchCount	`0`	获取或设置消息接收方可以同时请求的消息数。
运输类型	amqpTcp	用于与服务总线通信的协议和传输。可用选项：`amqpTcp`、`amqpWebSockets`
webProxy	不适用	用于通过 Web 套接字与服务总线进行通信的代理。代理不能与 `amqpTcp` 传输一起使用。
autoCompleteMessages	`true`	确定是否在成功执行函数后自动完成消息。
maxAutoLockRenewalDuration	`00:05:00`	自动续订消息锁的最长持续时间。此设置仅适用于一次接收一条消息的函数。
maxConcurrentCalls	`16`	对于每个缩放实例，应该对回调发起的最大并发调用数。默认情况下，Functions 运行时同时处理多条消息。仅当`isSessionsEnabled`上的属性或特性设置为 `false` 时，才应使用此设置。此设置仅适用于一次接收一条消息的函数。
maxConcurrentSessions	`8`	每个缩放实例可以并发处理的最大会话数。仅当`isSessionsEnabled`上的属性或特性设置为 `true` 时，才应使用此设置。此设置仅适用于一次接收一条消息的函数。
maxMessageBatchSize	`1000`	将传递给每个函数调用的消息的最大数量。此设置仅适用于接收一批消息的函数。
minMessageBatchSize¹	`1`	批中所需的最小消息数。仅当函数接收多个消息时，最小值才适用，且必须小于 `maxMessageBatchSize`。不严格保证最小大小。如果在 `maxBatchWaitTime` 内无法准备好整批，则将调度部分批。
maxBatchWaitTime¹	`00:00:30`	在调用函数之前触发器应等待填充批的最大时间间隔。仅当 `minMessageBatchSize` 大于 1 时才考虑等待时间，否则忽略。如果在达到等待时间前可用消息数少于 `minMessageBatchSize`，则会使用部分批调用函数。允许的最长等待时间为实体消息锁定持续时间的 50%，这意味着允许的等待时间最大值为 2 分 30 秒。否则，可能会出现锁定异常。注意：此间隔不能严格保证调用函数的确切时间。由于计时器精度原因，可能存在很小的误差。
sessionIdleTimeout	不适用	当前活动会话等待某个消息被接收的最长时间。在此时间过后，会话将被关闭，函数将尝试处理另一个会话。
enableCrossEntityTransactions	`false`	是否启用在服务总线命名空间上跨多个实体的事务。

¹ 使用 minMessageBatchSize 和 maxBatchWaitTime 需要 v5.10.0 或更高版本的 Microsoft.Azure.WebJobs.Extensions.ServiceBus 包。

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": true,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:05:00"
            },
            "sessionHandlerOptions": {
                "autoComplete": false,
                "messageWaitTimeout": "00:00:30",
                "maxAutoRenewDuration": "00:55:00",
                "maxConcurrentSessions": 16
            },
            "batchOptions": {
                "maxMessageCount": 1000,
                "operationTimeout": "00:01:00",
                "autoComplete": true
            }
        }
    }
}

如果将isSessionsEnabled上的 isSessionsEnabled 属性或特性设置为 true，将采用 sessionHandlerOptions。如果将isSessionsEnabled上的 isSessionsEnabled 属性或特性设置为 false，将采用 messageHandlerOptions。

属性	默认	说明
prefetchCount	`0`	获取或设置消息接收方可以同时请求的消息数。
maxAutoRenewDuration	`00:05:00`	自动续订消息锁的最长持续时间。
autoComplete	`true`	触发器在处理后自动调用 complete，还是函数代码手动调用 complete。仅在 C# 中支持将其设置为 `false`。如果设置为 `true`，则触发器会在函数执行成功完成时自动完成该消息、会话或批，否则会放弃该消息。如果设置为 `false`，你负责调用 ServiceBusReceiver 方法来完成、放弃消息、会话或批，或将它们放入死信队列。如果引发了异常（并且未调用任何 `ServiceBusReceiver` 方法），则锁仍然存在。锁到期后，消息会重新排队，同时 `DeliveryCount` 会递增，并且锁会自动续订。在非 C# 函数中，函数中的异常会导致运行时在后台调用 `abandonAsync`。如果未发生异常，则在后台调用 `completeAsync`。
maxConcurrentCalls	`16`	对于每个缩放实例，消息泵应对回调发起的最大并发调用数。默认情况下，Functions 运行时同时处理多条消息。
maxConcurrentSessions	`2000`	每个缩放实例可以并发处理的最大会话数。
maxMessageCount	`1000`	触发时发送到函数的最大消息数。
operationTimeout	`00:01:00`	以 `hh:mm:ss` 表示的时间跨度值。

通过