Edit

Migrate function apps from Azure Service Bus extension version 4.x to version 5.x

  • Article

This article highlights considerations for upgrading your existing Azure Functions applications that use the Azure Service Bus extension version 4.x to use the newer extension version 5.x. Migrating from version 4.x to version 5.x of the Azure Service Bus extension has breaking changes for your application.

Important

On March 31, 2025 the Azure Service Bus extension version 4.x will be retired. The extension and all applications using the extension will continue to function, but Azure Service Bus will cease to provide further maintenance and support for this extension. We recommend migrating to the latest version 5.x of the extension.

This article walks you through the process of migrating your function app to run on version 5.x of the Azure Service Bus extension. Because project upgrade instructions are language dependent, make sure to choose your development language from the selector at the top of the article.

Update the extension version

.NET Functions uses extensions that are installed in the project as NuGet packages. Depending on your Functions process model, the NuGet package to update varies.

Functions process model Azure Service Bus extension Recommended version
In-process model Microsoft.Azure.WebJobs.Extensions.ServiceBus >= 5.13.4
Isolated worker model Microsoft.Azure.Functions.Worker.Extensions.ServiceBus >= 5.14.1

Update your .csproj project file to use the latest extension version for your process model. The following .csproj file uses version 5 of the Azure Service Bus extension.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.ServiceBus" Version="5.16.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Update the extension bundle

By default, extension bundles are used by non-.NET function apps to install binding extensions. The Azure Service Bus version 5 extension is part of extension bundle version 4.

To update your application to use the latest extension bundle, update your host.json. The following host.json file uses version 4 of the extension bundle.

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

Modify your function code

The Azure Functions Azure Service Bus extension version 5 is built on top of the Azure.Messaging.ServiceBus SDK version 3, which removed support for the Message class. Instead, use the ServiceBusReceivedMessage type to receive message metadata from Service Bus Queues and Subscriptions.

Next steps