注册 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

扩展捆绑是一种部署技术,可让你将一组兼容的 Functions 绑定扩展添加到函数应用。Extension bundles is a deployment technology that lets you add a compatible set of Functions binding extensions to your function app. 生成应用时,会添加一组预定义的扩展。A predefined set of extensions are added when you build your app. 捆绑中定义的扩展包彼此兼容,这有助于避免包之间发生冲突。Extension packages defined in a bundle are compatible with each other, which helps you avoid conflicts between packages. 可以在应用的 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. 进行本地开发时,请确保使用最新版本的 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 local development using Azure Functions Core Tools, Visual Studio Code, and when you build remotely.

如果不使用扩展捆绑,则必须先在本地计算机上安装 .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. 扩展捆绑消除了本地开发的这一要求。Extension 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:

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.

随着捆绑包中的包的变化,捆绑包版本递增。Bundle versions increment as packages in the bundle change. 当捆绑包中的包的主版本递增时,会发生主版本更改。Major version changes occur when packages in the bundle increment by a major version. 捆绑包的主版本更改通常与 Functions 运行时主版本的更改同时发生。Major version changes in the bundle usually coincide with a change in the major version of the Functions runtime.

默认捆绑包安装的当前扩展集在此 extensions.json 文件中进行枚举。The current set of extensions installed by the default bundle is 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 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