本文介绍了扩展捆绑如何使函数代码能够使用 Azure Functions 支持的所有触发器和绑定。 此外,还可以了解使用扩展捆绑包时应用的支持级别和策略。
本文仅适用于使用 non-.NET 语言的 Azure Functions 开发人员。 若要了解如何将绑定扩展直接添加到 C# 函数应用,请参阅 注册 Azure Functions 绑定扩展。
概述
扩展捆绑包将预定义的兼容绑定扩展集添加到函数应用。 扩展捆绑已进行版本控制。 每个版本都包含一组特定的绑定扩展,这些扩展经过验证,可协同工作。 根据应用中所需的扩展版本选择捆绑版本。
从 non-.NET 模板创建 Azure Functions 项目时,扩展捆绑包已在应用 host.json
文件中启用。
定义扩展包引用
你可以在host.json
项目文件中通过添加extensionBundle
节来定义扩展捆绑包引用,如以下示例所示:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[3.3.0, 4.0.0)"
}
}
extensionBundle
中提供了以下属性:
资产 | DESCRIPTION |
---|---|
id | Azure Functions 扩展捆绑的命名空间。 |
版本 | 要安装的捆绑包的版本。 Functions 运行时始终选取由版本范围或间隔定义的可允许最高版本。 上述版本值允许从 3.3.0 到(但不包括)4.0.0 的所有捆绑包版本。 有关详细信息,请参阅用于指定版本范围的间隔表示法。 |
支持的扩展捆绑包
下表列出了所有 Microsoft.Azure.Functions.ExtensionBundle
捆绑版本和当前 支持状态:
捆绑版本 | host.json 中的版本 | 支持状态* |
---|---|---|
4.x | [4.0.0, 5.0.0) |
活跃 |
3.x | [3.3.0, 4.0.0) |
Deprecated |
2.x | [2.*, 3.0.0) |
Deprecated |
1.x | [1.*, 2.0.0) |
Deprecated |
* 弃用的组件包版本可以使用已弃用的绑定扩展程序版本。 为了获得最佳可支持性和可靠性,应 升级到捆绑版本 4.x。
默认扩展捆绑包通过版本范围定义。
extensions.json
若要查看生成主扩展的当前捆绑包版本的定义文件,请选择表中的链接。
扩展捆绑包的注意事项
使用扩展捆绑包时,请记住以下注意事项:
- 如果可能,应在
version
上表中选择一个范围值host.json
,例如[4.0.0, 5.0.0)
,而不是定义一个自定义范围。 - 使用最新版本范围获取最佳的应用性能和对最新功能的访问权限。
- 在不太可能使用扩展捆绑包的情况下,需要改为 显式安装扩展。
升级扩展捆绑包
请务必将版本号更新至最新版本,以便应用可以继续支持新功能、安全补丁和性能优化。
若要将应用升级到最新的捆绑包,请在应用项目的根目录中编辑 host.json 文件。 将值 extensionBundle.version
设置为 [4.x,5.0.0)
,host.json 文件中应如下所示:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.0.0, 5.0.0)"
}
}
升级应用使用的扩展捆绑包版本时,请记住以下注意事项:
- 始终可以在 存储库的此发布页上找到最新的 4.x 捆绑包的内容。
- 查看应用程序所使用扩展的参考文档,以查找版本之间的任何兼容性变更。 可以查看捆绑包存储库中的 捆绑包版本页 ,了解特定的捆绑包版本标记。
- 请始终在升级捆绑包版本后在本地验证应用,以确保与更新的扩展兼容。 可以使用 Visual Studio 或 Visual Studio Code 中的 Azure Functions Core Tools 或 F5 中的 func start 命令在本地运行函数应用。
- 根据对 host.json 文件中捆绑包版本的更改触发扩展更新的方式取决于应用环境:
- 本地项目:当 Core Tools 启动时(从
func start
命令启动或在开发工具中调试时),会本地更新扩展。 - 函数应用:将更新的 host.json 文件部署到 Azure 中的函数应用时,将更新扩展。
- 本地项目:当 Core Tools 启动时(从
预览扩展捆绑包
特定绑定扩展的预发行版在预览扩展捆绑包中维护: Microsoft.Azure.Functions.ExtensionBundle.Preview
可以使用此预览版本扩展捆绑包,在现有扩展中利用预览版的扩展和新行为,抢先于正式发布(GA)之前进行体验。
选择使用非 GA 扩展捆绑包时,请记住以下注意事项:
- 预览版捆绑包可以包括仍在开发中但尚未准备好用于生产的功能。 它们用于在非生产环境中进行评估和测试。
- 预览版之间可能发生重大更改,不会事先通知。 它们可以包括对以下内容的更改:
- 触发器和绑定定义。
- 预览中包含的扩展。
- 性能特性和稳定性。
- 安全更新可能需要升级版本。
- 必须在非生产环境中完全测试预览捆绑包,并避免在生产环境中使用预览捆绑包。 在生产环境中必须使用预览捆绑包时,请采取以下额外预防措施:
- 将捆绑包固定到经过良好测试的特定捆绑包版本而不是范围。 固定可防止在非生产环境中验证更新之前自动升级捆绑包版本。
- 在完全支持的捆绑包版本中提供该功能后,将应用移动到使用 GA 捆绑包版本。
- 若要随时了解捆绑更新,包括从预览版迁移到正式版,应:
- 查看扩展捆绑包发布页上的预览捆绑包版本。
- 监控扩展专用参考文档。
- 查看正在使用的特定预览版扩展的 NuGet 包版本。
- 跟踪每个预览扩展 NuGet.org 上发布的更改日志中的重大更新或更改。
支持策略
当基础捆绑包扩展的依赖项发生中断性变更或更新时,可能会出现扩展捆绑包的主要版本发布。 这些重大更改(通常在 Azure SDK 中引入)需要对捆绑包进行更新才能保持兼容。
GA 扩展捆绑的支持周期包含以下不同的阶段:
阶段 | DESCRIPTION |
---|---|
活跃 | 最新版本的扩展捆绑包被视为活动版本。 推荐这个版本用于您的函数应用。 |
通知 | Microsoft在停用扩展捆绑包或绑定扩展版本之前提供高级通知。 收到此类通知时,应开始计划将函数应用升级到受支持的扩展捆绑包的最新版本。 此升级有助于确保应用继续访问新功能、性能改进和支持。 |
弃用 | 当主扩展的新捆绑包版本正式发布时,以前的版本将进入 12 个月的弃用阶段。 这个重叠期为您在旧版本弃用之前计划、测试和升级应用提供了时间。 |
停用 | 扩展捆绑包停用后,引用特定版本的函数应用不符合新功能、安全修补程序和性能优化的条件。 仍可以创建和部署使用已停用版本的函数应用,并允许在平台上运行。 但是,必须先将函数应用升级到受支持的捆绑包版本,然后才能获得支持。 |
可以在 Azure Functions 扩展捆绑包的 GitHub 存储库中查看扩展捆绑包版本及其包含的扩展。 可以在 NuGet.org 上查找单个 .NET 包。
相关内容
- 若要了解有关绑定扩展的详细信息,请参阅 注册 Azure Functions 绑定扩展。