Azure Functions 扩展捆绑包

本文介绍了扩展捆绑如何使函数代码能够使用 Azure Functions 支持的所有触发器和绑定。 此外，还可以了解使用扩展捆绑包时应用的支持级别和策略。

本文仅适用于使用 non-.NET 语言的 Azure Functions 开发人员。 若要了解如何将绑定扩展直接添加到 C# 函数应用，请参阅 注册 Azure Functions 绑定扩展。

Overview

使用扩展捆绑包可将一组预定义的兼容绑定扩展添加到函数应用。 捆绑包包含 Functions 当前支持的所有绑定扩展。 扩展捆绑已进行版本控制。 每个版本都包含一组特定的绑定扩展版本，这些扩展版本经过验证可以协同工作。

应尽可能在应用中使用最新的捆绑包版本。

从 non-.NET 模板创建 Azure Functions 项目时，扩展捆绑包已在应用 host.json 文件中启用。

定义扩展包引用

在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 扩展捆绑包的最新可用次要版本上。

extensionBundle 中提供了以下属性：

捆绑包版本

下表列出了所有 Microsoft.Azure.Functions.ExtensionBundle 版本和当前支持状态：

^* 弃用的捆绑包版本可以包括已弃用的绑定扩展版本。 为了获得最佳可支持性和可靠性，应 升级到捆绑版本 4.x。

默认情况下，扩展捆绑包是通过版本范围定义的，这可以保证使用最新的次要捆绑包版本。 选择表中的版本链接以查看定义该主版本的最新捆绑包的 extensions.json 文件。

扩展捆绑包的注意事项

使用扩展捆绑包时，请记住以下注意事项：

• 如果可能，应设置 version 上表中的范围值 host.json，例如 [4.0.0, 5.0.0)，而不是定义自定义范围。
• 使用最新版本范围获取最佳的应用性能和对最新功能的访问权限。
• 如果无法使用扩展捆绑包（这种情况不太可能发生），则必须显式安装扩展。
• 更新已部署的应用使用的扩展时，Functions 会从 cdn.functions.azure.com 终结点下载新的扩展版本。 为了成功进行扩展更新，函数应用必须能够访问 cdn.functions.azure.com 终结点。

升级扩展捆绑包

请务必将软件包版本保持最新，以便应用可以使用新功能、安全补丁和性能优化。

若要将应用升级到最新的捆绑包，请在应用项目的根目录中编辑 host.json 文件。 将值 extensionBundle.version 设置为 [4.0.0,5.0.0)，host.json 文件中应如下所示：

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

升级应用使用的扩展捆绑包版本时，请记住以下注意事项：

• 始终可以在 存储库的此发布页上找到最新的 4.x 捆绑包的内容。
• 查看应用使用的扩展的参考文档，以查找版本之间的重大变更。 有关默认捆绑包中包含的扩展版本的列表，请参阅此表中链接的 extension.json 项目文件。 可以查看捆绑软件仓库中的捆绑包版本页面，了解具体的捆绑包版本标签。
• 请始终在升级捆绑包版本后在本地验证应用，以确保与更新的扩展兼容。 可以使用 Visual Studio 或 Visual Studio Code 中的 Azure Functions Core Tools 或 F5 中的 func start 命令在本地运行函数应用。
• 根据对 host.json 文件中捆绑包版本的更改触发扩展更新的方式取决于应用环境：
  • 本地项目：当 Core Tools 启动时，无论是从 func start 命令启动还是在开发工具中调试，扩展都会本地更新。
  • 函数应用：当您将更新的 host.json 文件部署到 Azure 的函数应用时，扩展将被更新。

扩展捆绑包支持策略

当扩展包中包含的某个绑定扩展发生重大变更更新时，可能会发布扩展包的主要版本。 这些扩展重大更改需要对捆绑包进行更新，以保持与底层 Azure SDK 的兼容。 升级捆绑包可确保应用程序继续获得新功能、性能改进和完整的产品支持。

扩展包的支持周期遵循以下不同阶段：

可以在 Azure Functions 扩展捆绑包存储库中查看扩展捆绑包版本及其包含的扩展。 还可以查看所有 Functions 扩展清单的 Azure SDK 发布页。 可以在 NuGet.org 上查找单个 .NET 包。

使用预览扩展捆绑包

选择使用非 GA 扩展捆绑包时，请记住以下注意事项：

• 预览版捆绑包可以包括仍在开发中但尚未准备好用于生产的功能。 它们用于在非生产环境中进行评估和测试。
• 预览版之间发生中断性变更，无需事先通知。 它们可以包括对以下内容的更改：
  • 触发器和绑定定义。
  • 预览中包含的扩展。
  • 性能特性和稳定性。
• 安全更新可能需要升级版本。
• 必须在非生产环境中完全测试预览捆绑包，并避免在生产环境中使用预览捆绑包。 在生产环境中必须使用预览捆绑包时，请采取以下额外预防措施：
  • 将捆绑包固定到经过良好测试的特定捆绑包版本而不是范围。 固定可防止在非生产环境中验证更新之前自动升级捆绑包版本。
  • 在完全支持的捆绑包版本中提供该功能后，将应用移动到使用 GA 捆绑包版本。
• 若要随时了解捆绑更新，包括从预览版迁移到正式版，应：
  • 请在扩展包的发布页上监控预览捆绑包版本的发布。
  • 监视扩展特定的参考文档。
  • 查看正在使用的特定预览版扩展的 NuGet 包版本。
  • 跟踪每个预览扩展 NuGet.org 上发布的更改日志中的重大更新或更改。

相关内容

• 若要了解有关绑定扩展的详细信息，请参阅 注册 Azure Functions 绑定扩展。