Skip to content

Latest commit

 

History

History
120 lines (94 loc) · 6.07 KB

migrate-service-bus-version-4-version-5.md

File metadata and controls

120 lines (94 loc) · 6.07 KB
Raw
title description ms.service ms.custom ms.topic ms.date zone_pivot_groups
Migrate Azure Service Bus extension for Azure Functions to version 5.x
This article shows you how to upgrade your existing function apps using the Azure Service Bus extension version 4.x to be able to use version 5.x of the extension.
azure-functions
devx-track-extended-java, devx-track-js, devx-track-python
how-to
01/12/2024
programming-languages-set-functions

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

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.

::: zone pivot="programming-language-csharp"

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.

Isolated worker model

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

In-process model

[!INCLUDE functions-in-process-model-retirement-note]

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.ServiceBus" Version="5.13.4" />
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Azure Service Bus SDK changes

The underlying SDK used by extension changed to use the Azure.Messaging.ServiceBus SDK, for cases where you were using SDK related types, please look at the Guide for migrating to Azure.Messaging.ServiceBus from Microsoft.Azure.ServiceBus for more information.

::: zone-end
::: zone pivot="programming-language-javascript,programming-language-python,programming-language-java,programming-language-powershell,programming-language-typescript"

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

::: zone-end
::: zone pivot="programming-language-csharp"

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. ::: zone-end

Next steps