Register Azure Functions binding extensions

Starting with Azure Functions version 2.x, bindings are available as separate packages from the functions runtime. 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
in Functions 1.x
Registration
in Functions 3.x/2.x
Azure portal Automatic Automatic*
Non-.NET languages or local Azure Core Tools development Automatic Use Azure Functions Core Tools and extension bundles
C# class library using Visual Studio Use NuGet tools Use NuGet tools
C# class library using Visual Studio Code N/A Use .NET Core CLI

* Portal uses extension bundles.

Extension bundles

Extension bundles is way to add a compatible set of Functions binding extensions to your function app. When using bundles, a predefined set of extensions are added when you build your app. Extension packages defined in a bundle are verified to be compatible with each other, which helps you avoid conflicts between packages. Extension bundles allows you to avoid having to publish .NET project code with a non-.NET functions project. You enable extension bundles in the app's host.json file.

You can use extension bundles with version 2.x and later versions of the Functions runtime.

Use extension bundles for local development using Azure Functions Core Tools, Visual Studio Code, and when you build remotely. When developing locally, make sure you are using the latest version of Azure Functions Core Tools. Extension bundles are also used when developing functions in the Azure portal.

If you don't use extension bundles, you must install the .NET Core 2.x SDK on your local computer before you explicitly install any binding extensions. An extensions.csproj file, which explicitly defines the required extensions, is added to your project. Extension bundles removes these requirements for local development.

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)"
    }
}

The following properties are available in extensionBundle:

Property Description
id The namespace for Microsoft Azure Functions extension bundles.
version The version of the bundle to install. The Functions runtime always picks the maximum permissible version defined by the version range or interval. 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. Major version changes in the bundle usually coincide with a change in the major version of the Functions runtime.

The current set of extensions installed by the default bundle is enumerated in this extensions.json file.

Explicitly install extensions

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.

Note

To manually install extensions by using Core Tools, you must have the .NET Core 2.x SDK installed.

When you explicitly install extensions, a .NET project file named extensions.csproj is added to the root of your project. This file defines the set of NuGet packages required by your functions. 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.

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

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. Use the --force option to update existing bindings to the latest version when installing new ones.

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 packages

For a C# class library-based functions project, you should install Extension bundles is designed specifically for projects that aren't class

C# class library with Visual Studio

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.

Replace <TARGET_VERSION> in the example with a specific version of the package, such as 3.0.0-beta5. 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.

If you use Install-Package to reference a binding, you don't need to use extension bundles. This approach is specific for class libraries built in Visual Studio.

C# class library with Visual Studio Code

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>

The .NET Core CLI can only be used for Azure Functions 2.x development.

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.

Replace <TARGET_VERSION> in the example with a specific version of the package, such as 3.0.0-beta5. 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