注册 Azure Functions 绑定扩展Register Azure Functions binding extensions

从 Azure Functions 版本 2.x 开始,函数运行时默认情况下仅包括 HTTP 和计时器触发器。Starting with Azure Functions version 2.x, the functions runtime only includes HTTP and timer triggers by default. 其他触发器和绑定可作为单独的包提供。Other triggers and bindings are available as separate packages.

.NET 类库函数应用使用以 NuGet 包的形式安装在项目中的绑定。.NET class library functions apps use bindings that are installed in the project as NuGet packages. 扩展捆绑允许非 .NET 函数应用使用相同的绑定,而不必处理 .NET 基础结构。Extension bundles allows non-.NET functions apps to use the same bindings without having to deal with the .NET infrastructure.

下表指明了何时以及如何注册绑定。The following table indicates when and how you register bindings.

开发环境Development environment Registration
Functions 1.x 中注册in Functions 1.x
Registration
Functions 3.x/2.x 中注册in Functions 3.x/2.x
Azure 门户Azure portal 自动Automatic 自动*Automatic*
非 .NET 语言Non-.NET languages 自动Automatic 使用扩展捆绑(推荐)或显式安装扩展Use extension bundles (recommended) or explicitly install extensions
使用 Visual Studio 的 C# 类库C# class library using Visual Studio 使用 NuGet 工具Use NuGet tools 使用 NuGet 工具Use NuGet tools
使用 Visual Studio Code 的 C# 类库C# class library using Visual Studio Code 不适用N/A 使用 .NET Core CLIUse .NET Core CLI

* 门户使用扩展捆绑包。* Portal uses extension bundles.

非 .NET 语言中的访问扩展Access extensions in non-.NET languages

对于 Java、JavaScript、PowerShell 和自定义处理程序函数应用,建议使用扩展捆绑来访问绑定。For Java, JavaScript, PowerShell, and Custom Handler function apps, we recommended using extension bundles to access bindings. 如果无法使用扩展捆绑,则可以显式安装绑定扩展。In cases where extension bundles cannot be used, you can explicitly install binding extensions.

扩展捆绑包Extension bundles

使用扩展捆绑可将一组兼容的绑定扩展添加到函数应用。Extension bundles is a way to add a compatible set of binding extensions to your function app. 可以在应用的 host.json 文件中启用扩展捆绑。You enable extension bundles in the app's host.json file.

可以将扩展捆绑与 2.x 版和更高版本的 Functions 运行时一起使用。You can use extension bundles with version 2.x and later versions of the Functions runtime.

扩展捆绑已进行版本控制。Extension bundles are versioned. 每个版本都包含一组特定的绑定扩展,这些扩展经过验证,可协同工作。Each version contains a specific set of binding extensions that are verified to work together. 根据应用中所需的扩展,选择捆绑版本。Select a bundle version based on the extensions that you need in your app.

若要将扩展捆绑添加到函数应用,请将 extensionBundle 部分添加到 host.json。To add an extension bundle to your function app, add the extensionBundle section to host.json. 在许多情况下,Visual Studio Code 和 Azure Functions Core Tools 会为你自动添加它。In many cases, Visual Studio Code and Azure Functions Core Tools will automatically add it for you.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[1.*, 2.0.0)"
    }
}

extensionBundle 中提供了以下属性:The following properties are available in extensionBundle:

propertiesProperty 说明Description
idid Azure Functions 扩展捆绑的命名空间。The namespace for Azure Functions extension bundles.
版本version 要安装的捆绑包的版本。The version of the bundle to install. Functions 运行时始终选取由版本范围或间隔定义的可允许最高版本。The Functions runtime always picks the maximum permissible version defined by the version range or interval. 上述版本值允许从 1.0.0 到(但不包括)2.0.0 的所有捆绑包版本。The version value above allows all bundle versions from 1.0.0 up to but not including 2.0.0. 有关详细信息,请参阅用于指定版本范围的间隔表示法For more information, see the interval notation for specifying version ranges.

下表列出了默认 Microsoft.Azure.Functions.ExtensionBundle 捆绑的当前可用版本以及指向它们所包括的扩展的链接。The following table lists the currently available versions of the default Microsoft.Azure.Functions.ExtensionBundle bundle and links to the extensions they include.

捆绑版本Bundle version host.json 中的版本Version in host.json 已包含的扩展Included extensions
1.x1.x [1.*, 2.0.0) 请参阅用于生成捆绑的 extensions.jsonSee extensions.json used to generate the bundle
2.x2.x [2.*, 3.0.0) 请参阅用于生成捆绑的 extensions.jsonSee extensions.json used to generate the bundle

备注

虽然可以在 host.json 中指定自定义版本范围,但建议使用此表中的版本值。While you can a specify custom version range in host.json, we recommend you use a version value from this table.

显式安装扩展Explicitly install extensions

如果无法使用扩展捆绑包,则可在本地使用 Azure Functions Core Tools 来安装项目所需的特定扩展包。If you aren't able to use extension bundles, you can use Azure Functions Core Tools locally to install the specific extension packages required by your project.

重要

不能在使用扩展捆绑包的函数应用中显式安装扩展。You can't explicitly install extensions in a function app that is using extension bundles. 在显式安装扩展之前,请删除 host.json 中的 extensionBundle 部分。Remove the extensionBundle section in host.json before explicitly installing extensions.

以下各项介绍了你可能需要手动安装扩展的一些原因:The following items describe some reasons you might need to install extensions manually:

  • 需要访问捆绑包中不可用的扩展的特定版本。You need to access a specific version of an extension not available in a bundle.
  • 需要访问捆绑包中不可用的自定义扩展。You need to access a custom extension not available in a bundle.
  • 需要访问单个捆绑包中不可用的特定扩展组合。You need to access a specific combination of extensions not available in a single bundle.

备注

若要使用 Core Tools 手动安装扩展,必须安装 .NET Core 2.x SDKTo manually install extensions by using Core Tools, you must have the .NET Core 2.x SDK installed. Azure Functions Core Tools 使用 .NET Core SDK 从 NuGet 安装扩展。The .NET Core SDK is used by Azure Functions Core Tools to install extensions from NuGet. 不需要了解 .NET 即可使用 Azure Functions 扩展。You don't need to know .NET to use Azure Functions extensions.

当你显式安装扩展时,系统会将名为 extensions.csproj 的 .NET 项目文件添加到项目的根目录。When you explicitly install extensions, a .NET project file named extensions.csproj is added to the root of your project. 此文件定义函数所需的 NuGet 包集。This file defines the set of NuGet packages required by your functions. 尽管你可以使用此文件中的 NuGet 包引用,但 Core Tools 允许你在不需手动编辑文件的情况下安装扩展。While you can work with the NuGet package references in this file, Core Tools lets you install extensions without having to manually edit the file.

可以通过多种方法使用 Core Tools 在本地项目中安装所需的扩展。There are several ways to use Core Tools to install the required extensions in your local project.

安装所有扩展Install all extensions

使用以下命令自动添加本地项目中的绑定所使用的所有扩展包:Use the following command to automatically add all extension packages used by the bindings in your local project:

func extensions install

该命令读取 function.json 文件以了解所需的程序包,安装这些包并重新生成扩展项目 (extensions.csproj)。The command reads the function.json file to see which packages you need, installs them, and rebuilds the extensions project (extensions.csproj). 它在当前版本中添加任何新绑定,但不更新现有绑定。It adds any new bindings at the current version but does not update existing bindings. 使用 --force 选项可在安装新版本时将现有绑定更新为最新版本。Use the --force option to update existing bindings to the latest version when installing new ones.

如果函数应用使用 Core Tools 无法识别的绑定,则必须手动安装特定扩展。If your function app uses bindings that Core Tools does not recognize, you must manually install the specific extension.

安装特定扩展Install a specific extension

使用以下命令安装特定版本的特定扩展包(在本例中为存储扩展):Use the following command to install a specific extension package at a specific version, in this case the Storage extension:

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 4.0.2

安装来自 NuGet 的 .NET 语言的扩展Install extensions from NuGet in .NET languages

对于基于 C# 类库的函数项目,应直接安装扩展。For a C# class library-based functions project, you should install extensions directly. 扩展捆绑包专用于不基于 C# 类库的项目。Extension bundles is designed specifically for projects that aren't C# class library-based.

使用 Visual Studio 的 C# 类库C# class library with Visual Studio

Visual Studio 中,可以使用 Install-Package 命令从包管理器控制台安装包,如以下示例所示:In Visual Studio, you can install packages from the Package Manager Console using the Install-Package command, as shown in the following example:

Install-Package Microsoft.Azure.WebJobs.Extensions.ServiceBus -Version <TARGET_VERSION>

用于给定绑定的包的名称在该绑定的参考文章中提供。The name of the package used for a given binding is provided in the reference article for that binding. 有关示例,请参阅服务总线绑定参考文章的“包”部分For an example, see the Packages section of the Service Bus binding reference article.

将示例中的 <TARGET_VERSION> 替换为特定包版本,例如 3.0.0-beta5Replace <TARGET_VERSION> in the example with a specific version of the package, such as 3.0.0-beta5. NuGet.org 上的单个包页上列出了有效版本。与 Functions 运行时 1.x 或 2.x 对应的主版本在绑定的参考文章中指定。Valid versions are listed on the individual package pages at NuGet.org. The major versions that correspond to Functions runtime 1.x or 2.x are specified in the reference article for the binding.

如果使用 Install-Package 来引用绑定,则无需使用扩展捆绑If you use Install-Package to reference a binding, you don't need to use extension bundles. 此方法特定于在 Visual Studio 中生成的类库。This approach is specific for class libraries built in Visual Studio.

使用 Visual Studio Code 的 C# 类库C# class library with Visual Studio Code

Visual Studio Code 中,请使用 .NET Core CLI 中的 dotnet add package 命令通过命令提示符安装 C# 类库项目的包。In Visual Studio Code, install packages for a C# class library project from the command prompt using the dotnet add package command in the .NET Core CLI. 以下示例演示如何添加绑定:The following example demonstrates how you add a binding:

dotnet add package Microsoft.Azure.WebJobs.Extensions.<BINDING_TYPE_NAME> --version <TARGET_VERSION>

.NET Core CLI 只能用于 Azure Functions 2.x 开发。The .NET Core CLI can only be used for Azure Functions 2.x development.

<BINDING_TYPE_NAME> 替换为包含所需绑定的包的名称。Replace <BINDING_TYPE_NAME> with the name of the package that contains the binding you need. 可以在支持的绑定列表中找到所需的绑定参考文章。You can find the desired binding reference article in the list of supported bindings.

将示例中的 <TARGET_VERSION> 替换为特定包版本,例如 3.0.0-beta5Replace <TARGET_VERSION> in the example with a specific version of the package, such as 3.0.0-beta5. NuGet.org 上的单个包页上列出了有效版本。与 Functions 运行时 1.x 或 2.x 对应的主版本在绑定的参考文章中指定。Valid versions are listed on the individual package pages at NuGet.org. The major versions that correspond to Functions runtime 1.x or 2.x are specified in the reference article for the binding.

后续步骤Next steps