Azure Functions extension bundles

This article explains how extension bundles enable your function code to use all of the triggers and bindings that Azure Functions supports. You also learn about the support levels and policies for your apps when you use extension bundles.

This article applies only to Azure Functions developers who use non-.NET languages. To learn how to add binding extensions directly to your C# function apps, see Register Azure Functions binding extensions.

Overview

Extension bundles add a predefined set of compatible binding extensions to your function app. 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 versions of the extensions that you need in your app.

When you create an Azure Functions project from a non-.NET template, extension bundles are already enabled in the app's host.json file.

Define an extension bundle reference

You define an extension bundle reference in the host.json project file by adding an extensionBundle section, as in this example:

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

The following properties are available in extensionBundle:

Property Description
id The namespace for 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 3.3.0 up to but not including 4.0.0. For more information, see the interval notation for specifying version ranges.

Supported extension bundles

This table lists all Microsoft.Azure.Functions.ExtensionBundle bundle versions and the current support state:

Bundle version Version in host.json Support state*
4.x [4.0.0, 5.0.0) Active
3.x [3.3.0, 4.0.0) Deprecated
2.x [2.*, 3.0.0) Deprecated
1.x [1.*, 2.0.0) Deprecated

* Deprecated bundle versions can use deprecated binding extension versions. For optimal supportability and reliability, you should upgrade to bundle version 4.x.

The default extension bundles are defined via version ranges. To see the extensions.json definition file that generates the current bundle version for a major extension, select the link in the table.

Considerations for extension bundles

Keep these considerations in mind when you work with extension bundles:

  • When possible, you should set a version range value in host.json from the preceding table, such as [4.0.0, 5.0.0), instead of defining a custom range.
  • Use the latest version range to obtain optimal app performance and access to the latest features.
  • In the unlikely event that you can't use an extension bundle, you must instead explicitly install extensions.

Upgrade extension bundles

It's important to keep your bundle version up-to-date so that your apps can continue to be eligible for new features, security patches, and performance optimizations.

To upgrade your app to the most recent bundle, edit the host.json file in the root of your app project. Set the value of extensionBundle.version to [4.x,5.0.0), which should look like this in your host.json file:

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

Keep these considerations in mind when upgrading the extension bundle version used by your app:

  • The contents of the latest 4.x bundle can always be found at this release page in the repo.
  • Review the reference documentation for any extensions used by your app to look for any breaking changes between versions. You can review the bundle releases page in the bundles repo for specific bundle version tags.
  • Always verify your app locally after upgrading the bundle version to ensure compatibility with the updated extensions. You can use the func start command in Azure Functions Core Tools or F5 in Visual Studio or Visual Studio Code to run your function app locally.
  • The way that you trigger extensions to be updated based on changes to the bundle version in the host.json file depends on your app environment:
    • Local project: extensions are updated locally when Core Tools starts, either from the func start command or when debugging in your development tools.
    • Function app: extensions are updated when you deploy the updated host.json file to your function app in Azure.

Preview extension bundles

Prerelease versions of specific binding extensions are maintained in a preview extension bundle: Microsoft.Azure.Functions.ExtensionBundle.Preview. You can use this preview extension bundle to take advantage of preview extensions and new behaviors in existing extensions before they reach general availability (GA).

Keep these considerations in mind when you choose to use a non-GA extension bundle:

  • Preview bundles can include features that are still under development and not yet ready for production use. They're intended for evaluation and testing in nonproduction environments.
  • Breaking changes occur between preview versions without prior notice. They can include changes to:
    • Trigger and binding definitions.
    • Extensions included in the preview.
    • Performance characteristics and stability.
  • Security updates might require you to upgrade versions.
  • You must completely test preview bundles in nonproduction environments and avoid using preview bundles in production. When you must use a preview bundle in production, take these extra precautions:
    • Pin your bundle to a specific, well-tested bundle version instead of to a range. Pinning prevents automatic upgrading of your bundle version before you have a chance to verify the update in a nonproduction environment.
    • Move your app to using a GA bundle version as soon as the functionality becomes available in a fully supported bundle release.
  • To stay informed about bundle updates, including moving from preview to GA, you should:

Support policy

Major version releases of extension bundles can occur when there are breaking changes or updates in the dependencies of the underlying binding extensions. These breaking changes, often introduced in Azure SDKs, require updates to the bundle to remain compatible.

The support cycle of a GA extension bundle follows these distinct phases:

Phase Description
Active The most recent major version of extension bundles is considered the active version. We recommend this version for your function apps.
Notification Microsoft provides advanced notice before retiring an extension bundle or a binding extension version. When you receive such a notification, you should begin planning to upgrade your function apps to the latest version of a supported extension bundle. This upgrade helps ensure that your apps continue to access new features, performance improvements, and support.
Deprecation When a new bundle version for a major extension becomes generally available, the previous version enters a 12-month deprecation phase. This overlap period gives you time to plan, test, and upgrade your apps before the previous version is retired.
Retirement  After the retirement of an extension bundle, function apps that reference that specific version aren't eligible for new features, security patches, and performance optimizations. Function apps that use retired versions can still be created and deployed and are permitted to run on the platform. However, you must upgrade your function app to a supported bundle version before you can receive support.

You can view the extension bundle versions and their included extensions in the GitHub repo for Azure Functions extension bundles. You can find individual .NET packages on NuGet.org.

Related content