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

在 Azure Functions 版本 2.x 中,绑定以独立于函数运行时的包的形式提供。In Azure Functions version 2.x, bindings are available as separate packages from the functions runtime. 虽然 .NET 函数通过 NuGet 包访问绑定,但扩展捆绑包允许其他函数通过配置设置访问所有绑定。While .NET functions access bindings through NuGet packages, extension bundles allow other functions access to all bindings through a configuration setting.

请考虑以下与绑定扩展相关的项:Consider the following items related to binding extensions:

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

开发环境Development environment 注册Registration
Functions 1.x 中注册in Functions 1.x
注册Registration
Functions 2.x 中注册in Functions 2.x
Azure 门户Azure portal 自动Automatic 自动Automatic
非 .NET 语言或本地 Azure Core Tools 开发Non-.NET languages or local Azure Core Tools development 自动Automatic 使用 Azure Functions Core Tools 和扩展捆绑包Use Azure Functions Core Tools and extension bundles
使用 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

用于本地开发的扩展捆绑Extension bundles for local development

扩展捆绑是适用于版本 2.x 运行时的一种本地开发技术,可让你将一组兼容的 Functions 绑定扩展添加到函数应用项目。Extension bundles is a local development technology for the version 2.x runtime that lets you add a compatible set of Functions binding extensions to your function app project. 部署到 Azure 时,这些扩展包将包含在部署包中。These extension packages are then included in the deployment package when you deploy to Azure. 捆绑使得 Microsoft 发布的所有绑定都可以通过 host.json 文件中的设置使用。Bundles makes all bindings published by Microsoft available through a setting in the host.json file. 捆绑中定义的扩展包彼此兼容,这有助于避免包之间发生冲突。Extension packages defined in a bundle are compatible with each other, which helps you avoid conflicts between packages. 进行本地开发时,请确保使用最新版本的 Azure Functions Core ToolsWhen developing locally, make sure you are using the latest version of Azure Functions Core Tools.

对于使用 Azure Functions Core Tools 或 Visual Studio Code 进行的所有本地开发,请使用扩展捆绑。Use extension bundles for all local development using Azure Functions Core Tools or Visual Studio Code.

如果不使用扩展捆绑,则必须先在本地计算机上安装 .NET Core 2.x SDK,然后才能安装任何绑定扩展。If you don't use extension bundles, you must install the .NET Core 2.x SDK on your local computer before you install any binding extensions. 捆绑为本地开发消除了这一要求。Bundles removes this requirement for local development.

若要使用扩展捆绑,请更新 host json文件以包含 extensionBundle 的以下条目:To use extension bundles, update the host.json file to include the following entry for extensionBundle:

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

以下属性可在 extensionBundle 中使用:The following properties are available in extensionBundle:

属性Property 说明Description
id 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(不含 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.

捆绑中的包发生变化时,捆绑版本将会递增。Bundle versions increment as packages in the bundle change. 当捆绑中的包递增一个主要版本号时,主要版本将发生变化,这通常与 Functions 运行时的主要版本更改行为相一致。Major version changes occur when packages in the bundle increment by a major version, which usually coincides with a change in the major version of the Functions runtime.

默认捆绑安装的当前扩展集将在此 extensions.json 文件中枚举。The current set of extensions installed by the default bundle are enumerated in this extensions.json file.

使用 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 do not 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

Note

我们建议使用扩展捆绑来让 Functions 自动安装一组兼容的绑定扩展包。We recommend using extension bundles to have Functions automatically install a compatible set of binding extension packages.

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 provided in the reference article for your desired binding. 可以在支持的绑定列表中找到所需的绑定参考文章。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