Azure Functions 的 Azure 服务总线绑定

2025-10-09

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

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

安装扩展

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

独立工作模型
进程内模型

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

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

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

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

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

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

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

安装捆绑包

若要能够在应用中使用此绑定扩展，请确保项目的根目录中 host.json 文件包含以下 extensionBundle 引用：

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

在此示例中，version[4.0.0, 5.0.0)值指示 Functions 主机使用至少4.0.0小于但小于5.0.0的捆绑包版本，其中包括所有可能的 4.x 版本。此表示法有效地在 v4.x 扩展捆绑包的最新可用次要版本上维护应用。

如果可能，应使用最新的扩展捆绑包主版本，并允许运行时自动维护最新的次要版本。可以在扩展捆绑包发布页上查看最新捆绑包的内容。

如果应用要求使用以前的扩展版本，则可能需要改为指定以前的捆绑包版本。可以查看捆绑包版本，找到包含此扩展版本的捆绑包，该版本可供应用使用。有关详细信息，请参阅 Azure Functions 扩展捆绑包。结束区域

绑定类型

.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 日之后仍可使用，但它们将不再获得 Azure 的官方支持和更新。有关详细信息，请参阅支持停用公告。

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

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

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

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

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

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

服务总线触发器

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

类型	DESCRIPTION
`string`	字符串格式的消息。当消息为简单文本时使用。
`byte[]`	消息的字节数。
JSON 可序列化类型	当事件包含 JSON 数据时，Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
ServiceBusReceivedMessage	（预览版¹）消息对象。

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

类型	DESCRIPTION
`T[]`，其中 `T` 是单消息类型之一	批处理中的事件数组。每个条目表示一个事件。

独立进程模型尚不支持服务总线触发器的消息解决方案。

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

服务总线输出绑定

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

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

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

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

对于其他输出方案，请直接创建和使用 Azure.Messaging.ServiceBus 中的类型。

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

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

资产	违约	DESCRIPTION
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` 表示的时间跨度值。

通过