This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

This guide helps with migration to Spring Cloud Azure 4.0 from legacy Azure Spring libraries.

Introduction

We'll call libraries whose group ID and artifact ID follow the pattern com.azure.spring:spring-cloud-azure-* the modern libraries, and those with pattern com.azure.spring:azure-spring-boot-* , com.azure.spring:azure-spring-cloud-* , or com.azure.spring:azure-spring-integration-* the legacy libraries.

This guide will focus on side-by-side comparisons for similar configurations between the modern and legacy libraries.

Familiarity with com.azure.spring:azure-spring-boot-* , com.azure.spring:azure-spring-cloud-* or com.azure.spring:azure-spring-integration-* package is assumed.

If you're new to the Spring Cloud Azure 4.0 libraries, see the Spring Cloud Azure developer guide rather than this guide.

Migration benefits

A natural question to ask when considering whether to adopt a new version or library is its benefits. As Azure has matured and been embraced by a more diverse group of developers, we've been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the Spring Cloud Azure libraries have.

There were several areas of consistent feedback expressed across the Spring Cloud Azure libraries. The most important is that the libraries for different Azure services haven't enabled the complete set of configurations. Additionally, the inconsistency of project naming, artifact IDs, versions, and configurations made the learning curve steep.

To improve the development experience across Spring Cloud Azure libraries, a set of design guidelines was introduced to ensure that Spring Cloud Azure libraries have a natural and idiomatic feel with respect to the Spring ecosystem. Further details are available in the design doc for those interested.

Spring Cloud Azure 4.0 provides the shared experience across libraries integrating with different Spring projects, for example Spring Boot, Spring Integration, Spring Cloud Stream, and so on. The shared experience includes:

Overview

This migration guide consists of the following sections:

Naming changes

There has never been a consistent or official name to call all the Spring Cloud Azure libraries. Some of them were called Azure Spring Boot and some of them Spring on Azure . Since 4.0, we began to use the project name Spring Cloud Azure to represent all the Azure Spring libraries.

We used to ship two BOMs for our libraries, the azure-spring-boot-bom and azure-spring-cloud-dependencies , but we combined these two BOMs into one BOM since 4.0, the spring-cloud-azure-dependencies . Add an entry in the dependencyManagement section of your project to benefit from the dependency management.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>4.10.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
If you're using Spring Boot 3.x, be sure to set the spring-cloud-azure-dependencies version to 5.4.0.
For more information about the spring-cloud-azure-dependencies version, see Which Version of Spring Cloud Azure Should I Use.
Artifact changes: renamed / added / deleted
Group IDs are the same for modern and legacy Spring Cloud Azure libraries. They're all com.azure.spring. Artifact IDs for the modern Spring Cloud Azure libraries have changed. According to which Spring project it belongs to, Spring Boot, Spring Integration, or Spring Cloud Stream, the artifact IDs pattern could be spring-cloud-azure-starter-[service], spring-integration-azure-[service], or spring-cloud-azure-stream-binder-[service]. The legacy starters for each has an artifact ID following the pattern azure-spring-*. This provides a quick and accessible means to help understand, at a glance, whether you're using modern or legacy starters.
In the process of developing Spring Cloud Azure 4.0, we renamed some artifacts to make them follow the new naming conventions, deleted some artifacts so that the functionality could be put into a more appropriate artifact, and added some new artifacts to better serve some scenarios.
The following table shows the mappings between legacy artifact ID and modern artifact ID:
azure-spring-boot-starter
spring-cloud-azure-starter
This artifact has been deleted with all functionality be merged into the new spring-cloud-azure-starter artifact.
azure-spring-boot-starter-active-directory
spring-cloud-azure-starter-active-directory
Renamed the artifact.
azure-spring-boot-starter-active-directory-b2c
spring-cloud-azure-starter-active-directory-b2c
Renamed the artifact.
azure-spring-boot-starter-cosmos
spring-cloud-azure-starter-data-cosmos
Renamed the artifact to add data, indicating using Spring Data Azure Cosmos DB.
azure-spring-boot-starter-keyvault-certificates
not applicable
Not included in this release, but will be supported in later version.
azure-spring-boot-starter-keyvault-secrets
spring-cloud-azure-starter-keyvault-secrets
Renamed the artifact.
azure-spring-boot-starter-servicebus-jms
spring-cloud-azure-starter-servicebus-jms
Renamed the artifact.
azure-spring-boot-starter-storage
spring-cloud-azure-starter-storage-blob 
spring-cloud-azure-starter-storage-file-share
The legacy artifact contains the functionality of both Storage Blob and File Share, it's been spliced into two separate artifacts in 4.0, spring-cloud-azure-starter-storage-blob and spring-cloud-azure-starter-storage-file-share.
azure-spring-boot
not applicable
This artifact has been deleted with all functionality be merged into the new spring-cloud-azure-autoconfigure artifact.
azure-spring-cloud-autoconfigure
not applicable
This artifact has been deleted with all functionality be merged into the new spring-cloud-azure-autoconfigure artifact.
azure-spring-cloud-context
not applicable
This artifact has been deleted with all functionality be merged into the new spring-cloud-azure-autoconfigure and spring-cloud-azure-resourcemanager artifacts.
azure-spring-cloud-messaging
spring-messaging-azure
The messaging listener annotation has been dropped.
azure-spring-cloud-starter-cache
not applicable
This artifact has been deleted, for using redis, just add spring-boot-starter-data-redis, spring-boot-starter-cache, spring-cloud-azure-resourcemanager and spring-cloud-azure-starter. For more information about usage, see Spring Cloud Azure Redis support.
azure-spring-cloud-starter-eventhubs-kafka
not applicable
This artifact has been deleted, for using kafka, just add spring kafka, spring-cloud-azure-resourcemanager and spring-cloud-azure-starter. For more information about usage, see Spring Cloud Azure Kafka support.
azure-spring-cloud-starter-eventhubs
spring-cloud-azure-starter-integration-eventhubs
Renamed the artifact to add integration, indicating using Spring Integration with Event Hubs.
azure-spring-cloud-starter-servicebus
spring-cloud-azure-starter-integration-servicebus
Renamed the artifact to add integration, indicating using Spring Integration with Service Bus.
azure-spring-cloud-starter-storage-queue
spring-cloud-azure-starter-integration-storage-queue
Renamed the artifact to add integration, indicating using Spring Integration with Storage Queue.
azure-spring-cloud-storage
not applicable
This artifact has been deleted with all functionalities merged into the new spring-cloud-azure-autoconfigure artifact.
azure-spring-cloud-stream-binder-eventhubs
spring-cloud-azure-stream-binder-eventhubs
This artifact has been refactored using a new design, mainly spring-cloud-azure-stream-binder-eventhubs and spring-cloud-azure-stream-binder-eventhubs-core.
azure-spring-cloud-stream-binder-service-core
spring-cloud-azure-stream-binder-servicebus-core
Renamed the artifact.
azure-spring-cloud-stream-binder-servicebus-queue
spring-cloud-azure-stream-binder-servicebus
This artifact has been deleted with all functionality be merged into the spring-cloud-azure-stream-binder-servicebus artifact.
azure-spring-cloud-stream-binder-servicebus-topic
spring-cloud-azure-stream-binder-servicebus
This artifact has been deleted with all functionality be merged into the spring-cloud-azure-stream-binder-servicebus artifact.
azure-spring-integration-core
spring-integration-azure-core
Renamed the artifact.
azure-spring-integration-eventhubs
spring-integration-azure-eventhubs
Rename the artifact.
azure-spring-integration-servicebus
spring-integration-azure-servicebus
Rename the artifact.
azure-spring-integration-storage-queue
spring-integration-azure-storage-queue
Rename the artifact.
not applicable
spring-cloud-azure-actuator
The newly added Spring Cloud Azure Actuator artifact.
not applicable
spring-cloud-azure-actuator-autoconfigure
The newly added Spring Cloud Azure Actuator AutoConfigure artifact, including autoconfiguration for actuator.
not applicable
spring-cloud-azure-autoconfigure
Newly added Spring Cloud Azure AutoConfigure artifact, including all auto-configuration for SDK clients, Spring Security support, Spring Data support and Spring Integration support.
not applicable
spring-cloud-azure-core
Newly added Spring Cloud Azure Core artifact, including all core functionality.
not applicable
spring-cloud-azure-resourcemanager
Newly added Resource Manager artifact. It's the Core library using Azure Resource Manager to read metadata and create resources.
not applicable
spring-cloud-azure-service
Newly added Spring Cloud Azure Service artifact, including abstractions for Azure services.
not applicable
spring-cloud-azure-starter-appconfiguration
Newly added starter for using Azure App Configuration SDK client.
not applicable
spring-cloud-azure-starter-cosmos
Newly added starter for using Azure Cosmos DB SDK client.
not applicable
spring-cloud-azure-starter-eventhubs
Newly added starter for using Azure Event Hubs SDK client.
not applicable
spring-cloud-azure-starter-servicebus
Newly added starter for using Azure Service Bus SDK client.
not applicable
spring-cloud-azure-starter-storage-blob
Newly added starter for using Azure Storage Blob SDK client.
not applicable
spring-cloud-azure-starter-storage-file-share
Newly added starter for using Azure Storage File Share SDK client.
not applicable
spring-cloud-azure-starter-storage-queue
Newly added starter for using Azure Storage Queue SDK client.
not applicable
spring-cloud-azure-starter-stream-eventhubs
Newly added starter for using Azure Event Hubs Spring Cloud Stream Binder.
not applicable
spring-cloud-azure-starter-stream-servicebus
Newly added starter for using Azure Service Bus Spring Cloud Stream Binder
not applicable
spring-cloud-azure-stream-binder-eventhubs-core
Newly added Spring Cloud Stream core artifact for Azure Event Hubs.
Dependencies changes
Some unnecessary dependencies were included in the legacy artifacts, which we've removed in the modern Spring Cloud Azure 4.0 libraries. Be sure to add the removed dependencies manually to your project to prevent crashes.
Libraries that have dependency changes include:
spring-cloud-azure-starter
spring-cloud-azure-starter-active-directory
spring-cloud-azure-starter-active-directory-b2c
Authentication changes
Spring Cloud Azure 4.0 supports all the authentication methods that each Azure Service SDK supports. It enables you to configure a global token credential as well as providing the token credential at each service level. But a credential isn't required to configure  Spring Cloud Azure 4.0 because it can apply the credential stored in a local developing environment or managed identity in Azure Services. Just be sure the principal has been granted sufficient permission to access the target Azure resources.
When assign roles to the security principals to interact with Azure messaging services, the Data related roles are required to conduct messaging operations. For Azure Spring Apps Stream Event Hubs / Service Bus Binder libraries, Contributor role is required when the function of auto creating resources is needed. For more information, see Azure built-in roles.
A chained credential, the DefaultAzureCredential bean is auto-configured by default and will be used by all components if no more authentication information is specified. For more information, see the DefaultAzureCredential section of Azure Identity client library for Java.
Configuration properties
Properties migration
We've created an additional-spring-configuration-metadata.json file to smooth the property migration when using with spring-boot-properties-migrator. First, add the following property migrator to your application:
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>
Or, if you’re using Gradle:
runtime("org.springframework.boot:spring-boot-properties-migrator")
If you run the app, it will identify the properties that are no longer managed by Spring Cloud Azure. If there's a replacement, it will temporarily remap the property for you with a warning. If there isn’t a replacement, an error report will give you more information. Either way, the configuration has to be updated and the dependency removed once you've updated the configuration.
Before you move on, it's a good idea to use the search feature of your IDE to double-check that you aren’t using one of the properties you’ve migrated in an integration test.
We've changed many configuration properties in this change. Using the spring-boot-properties-migrator will help smooth your migration.
Global configurations
The modern spring-cloud-azure-starter enables you to define properties that apply to all Azure SDKs in the namespace spring.cloud.azure. This feature wasn't supported in the legacy azure-spring-boot-starter. The global configurations can be divided into five categories, shown in the following table:
Prefix
Description
spring.cloud.azure.credential
Configures how to authenticate with Azure Active Directory.
spring.cloud.azure.profile
Configures the Azure cloud environment.
spring.cloud.azure.proxy
Configures the proxy options, apply to all Azure SDK clients.
spring.cloud.azure.retry
Configures the retry options, apply to all Azure SDK clients. The retry options have supported part of the SDKs, there’s no spring.cloud.azure.cosmos.retry.
For a full list of configurations, see Spring Cloud Azure configuration properties.
Configure each SDK
For details about the configuration options at the SDK level, use the following links:
From azure-spring-boot-starter-active-directory to spring-cloud-azure-starter-active-directory
From azure-spring-boot-starter-active-directory-b2c to spring-cloud-azure-starter-active-directory-b2c
From azure-spring-boot-starter-cosmos to spring-cloud-azure-starter-data-cosmos
From azure-spring-boot-starter-keyvault-secrets to spring-cloud-azure-starter-keyvault-secrets
From azure-spring-boot-starter-servicebus-jms to spring-cloud-azure-starter-servicebus-jms
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-blob
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-file-share
From azure-spring-cloud-starter-eventhubs to spring-cloud-azure-starter-integration-eventhubs
From azure-spring-cloud-starter-servicebus to spring-cloud-azure-starter-integration-servicebus
From azure-spring-cloud-starter-storage-queue to spring-cloud-azure-starter-integration-storage-queue
From azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs
From azure-spring-cloud-stream-binder-servicebus-* to spring-cloud-azure-stream-binder-servicebus
API breaking changes
For details about API breaking changes in each library, use the following links:




    

From azure-spring-boot-starter-active-directory to spring-cloud-azure-starter-active-directory
From azure-spring-boot-starter-active-directory-b2c to spring-cloud-azure-starter-active-directory-b2c
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-blob
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-file-share
From azure-spring-cloud-starter-eventhubs to spring-cloud-azure-starter-integration-eventhubs
From azure-spring-integration-eventhubs to spring-integration-azure-eventhubs
From azure-spring-cloud-starter-servicebus to spring-cloud-azure-starter-integration-servicebus
From azure-spring-integration-servicebus to spring-integration-azure-servicebus
From azure-spring-cloud-starter-storage-queue to spring-cloud-azure-starter-integration-storage-queue
From azure-spring-integration-storage-queue to spring-integration-azure-storage-queue
From azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs
From azure-spring-cloud-stream-binder-servicebus-* to spring-cloud-azure-stream-binder-servicebus
Library changes
Breaking changes in each library are introduced as follows.
From azure-spring-boot-starter to spring-cloud-azure-starter
This guide is intended to assist in the migration to spring-cloud-azure-starter from
version 3 of azure-spring-boot-starter.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
Dependency changes
Some unnecessary dependencies were included in the legacy artifacts, which we have removed in the modern Spring Cloud Azure 4.0 libraries. Be sure to add the removed dependencies manually to your project to prevent unintentional crash.
The following table shows the Removed dependencies:
From azure-spring-boot-starter-active-directory to spring-cloud-azure-starter-active-directory
This guide is intended to assist the migration to spring-cloud-azure-starter-active-directory from
version 3 of azure-spring-boot-starter-active-directory.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
Dependency changes
Some unnecessary dependencies in the legacy artifact have been removed since the modern Spring Cloud Azure 4.0 library. Add these removed dependencies to your project to prevent unintentional crash.
The following table shows the Removed dependencies:
com.fasterxml.jackson.core:jackson-databind
Add this dependency to your project if needed.
io.projectreactor.netty:reactor-netty
Add this dependency to your project if needed.
org.springframework.boot:spring-boot-starter-validation
Add this dependency to your project if needed.
org.springframework.boot:spring-boot-starter-webflux
Add this dependency to your project if needed.
SDK configuration changes
This section includes the changes about the properties added, removed and changed.
The following two points are the main to pay your attention to:
All configuration property names' prefix changed from azure.activedirectory to spring.cloud.azure.active-directory.
New property spring.cloud.azure.active-directory.enabled is added to enable/disable Azure AD related features. The default value is false.
The following table shows the property mappings between azure-spring-boot-starter-active-directory and spring-cloud-azure-starter-active-directory:
azure.activedirectory.application-type
spring.cloud.azure.active-directory.application-type
azure.activedirectory.authorization-clients
spring.cloud.azure.active-directory.authorization-clients
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.authorization-grant-type
spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.authorization-grant-type
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.on-demand
spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.on-demand
azure.activedirectory.authorization-clients.AZURE_CLIENT_NAME.scopes
spring.cloud.azure.active-directory.authorization-clients.AZURE_CLIENT_NAME.scopes
azure.activedirectory.authenticate-additional-parameters
spring.cloud.azure.active-directory.authenticate-additional-parameters
azure.activedirectory.base-uri
spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint
azure.activedirectory.client-id
spring.cloud.azure.active-directory.credential.client-id
azure.activedirectory.client-secret
spring.cloud.azure.active-directory.credential.client-secret
azure.activedirectory.graph-membership-uri
Check the following table for more information.
azure.activedirectory.jwt-connect-timeout
spring.cloud.azure.active-directory.jwt-connect-timeout.
azure.activedirectory.jwt-read-timeout
spring.cloud.azure.active-directory.jwt-read-timeout.
azure.activedirectory.jwt-size-limit
spring.cloud.azure.active-directory.jwt-size-limit.
azure.activedirectory.jwk-set-cache-lifespan
spring.cloud.azure.active-directory.jwk-set-cache-lifespan.
azure.activedirectory.jwk-set-cache-refresh-time
spring.cloud.azure.active-directory.jwk-set-cache-refresh-time
azure.activedirectory.post-logout-redirect-uri
spring.cloud.azure.active-directory.post-logout-redirect-uri
azure.activedirectory.session-stateless
spring.cloud.azure.active-directory.session-stateless
azure.activedirectory.redirect-uri-template
spring.cloud.azure.active-directory.redirect-uri-template
azure.activedirectory.resource-server.claim-to-authority-prefix-map
spring.cloud.azure.active-directory.resource-server.claim-to-authority-prefix-map
azure.activedirectory.resource-server.principal-claim-name
spring.cloud.azure.active-directory.resource-server.principal-claim-name
azure.activedirectory.tenant-id
spring.cloud.azure.active-directory.profile.tenant-id
azure.activedirectory.user-group.allowed-group-ids
spring.cloud.azure.active-directory.user-group.allowed-group-ids
azure.activedirectory.user-group.allowed-group-names
spring.cloud.azure.active-directory.user-group.allowed-group-names
azure.activedirectory.user-name-attribute
spring.cloud.azure.active-directory.user-name-attribute
The value type of the following properties is changed from long to Duration:
jwt-connect-timeout
jwt-read-timeout
jwk-set-cache-lifespan
jwk-set-cache-refresh-time.
The following properties are removed:
azure.activedirectory.allow-telemetry
azure.activedirectory.user-group.enable-full-list
azure.activedirectory.graph-base-uri
azure.activedirectory.graph-membership-uri
The following properties are added:
spring.cloud.azure.active-directory.enabled
spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint
spring.cloud.azure.active-directory.user-group.use-transitive-members
The function of azure.activedirectory.graph-membership-uri has been replaced by 2 properties: spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint and spring.cloud.azure.active-directory.user-group.use-transitive-members. The first property is used to specify the host name, and the second a flag for using the URL path: v1.0/me/memberOf or v1.0/me/transitiveMemberOf.
Here are some examples of migration:
Example 1. Case 1
For legacy:
azure.activedirectory.graph-membership-uri=https://graph.microsoft.com/v1.0/me/memberOf
For modern:
spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint=https://graph.microsoft.com/ +
spring.cloud.azure.active-directory.user-group.use-transitive-members=false
Example 2. Case 2
For legacy:
azure.activedirectory.graph-membership-uri=https://graph.microsoft.com/v1.0/me/transitiveMemberOf
For modern:
spring.cloud.azure.active-directory.profile.environment.microsoft-graph-endpoint=https://graph.microsoft.com/ +
spring.cloud.azure.active-directory.user-group.use-transitive-members=true
com.azure.spring.aad.webapi.AADJwtBearerTokenAuthenticationConverter
com.azure.spring.cloud.autoconfigure.aad.AadJwtBearerTokenAuthenticationConverter
com.azure.spring.aad.webapi.AADResourceServerProperties
com.azure.spring.cloud.autoconfigure.aad.properties.AadResourceServerProperties
com.azure.spring.aad.webapi.AADResourceServerWebSecurityConfigurerAdapter
com.azure.spring.cloud.autoconfigure.aad.AadResourceServerWebSecurityConfigurerAdapter
com.azure.spring.aad.webapp.AADWebSecurityConfigurerAdapter
com.azure.spring.cloud.autoconfigure.aad.AadWebSecurityConfigurerAdapter
com.azure.spring.aad.webapp.AuthorizationClientProperties
com.azure.spring.cloud.autoconfigure.aad.properties.AuthorizationClientProperties
com.azure.spring.aad.AADApplicationType
com.azure.spring.cloud.autoconfigure.aad.properties.AadApplicationType
com.azure.spring.aad.AADAuthorizationGrantType
com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthorizationGrantType
com.azure.spring.aad.AADAuthorizationServerEndpoints
com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthorizationServerEndpoints
com.azure.spring.aad.AADClientRegistrationRepository
com.azure.spring.cloud.autoconfigure.aad.AadClientRegistrationRepository
com.azure.spring.aad.AADTrustedIssuerRepository
com.azure.spring.cloud.autoconfigure.aad.AadTrustedIssuerRepository
com.azure.spring.autoconfigure.aad.AADAppRoleStatelessAuthenticationFilter
com.azure.spring.cloud.autoconfigure.aad.filter.AadAppRoleStatelessAuthenticationFilter
com.azure.spring.autoconfigure.aad.AADAuthenticationFilter
com.azure.spring.cloud.autoconfigure.aad.filter.AadAuthenticationFilter
com.azure.spring.autoconfigure.aad.AADAuthenticationProperties
com.azure.spring.cloud.autoconfigure.aad.properties.AadAuthenticationProperties
com.azure.spring.autoconfigure.aad.UserPrincipal
com.azure.spring.cloud.autoconfigure.aad.filter.UserPrincipal
com.azure.spring.autoconfigure.aad.UserPrincipalManager
com.azure.spring.cloud.autoconfigure.aad.filter.UserPrincipalManager
This section lists the removed classes from azure-spring-boot-starter-active-directory.
Removed legacy class
com.azure.spring.aad.webapp.AADHandleConditionalAccessFilter
com.azure.spring.aad.webapi.validator.AADJwtAudienceValidator
com.azure.spring.aad.webapi.validator.AADJwtClaimValidator
From azure-spring-boot-starter-active-directory-b2c to spring-cloud-azure-starter-active-directory-b2c
This guide is intended to assist in the migration to spring-cloud-azure-starter-active-directory-b2c from version 3 of azure-spring-boot-starter-active-directory-b2c.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
Dependency changes
Some unnecessary dependencies were included in the legacy artifacts, which we have removed in the modern Spring Cloud Azure 4.0 libraries. Be sure to add the removed dependencies manually to your project to prevent unintentional crash.
The following table shows the Removed dependencies:
SDK configuration changes
This section includes the changes about the properties added, removed and changed.
The following two points are the main to pay your attention to:
All configuration property names changed the prefix from azure.activedirectory.b2c to spring.cloud.azure.active-directory.b2c.
New property spring.cloud.azure.active-directory.b2c.enabled is added to allow enable / disable Azure AD B2C related features. The default value is false.
The following table shows the property mappings from azure-spring-boot-starter-active-directory-b2c to spring-cloud-azure-starter-active-directory-b2c:




    

azure.activedirectory.b2c.authenticate-additional-parameters
spring.cloud.azure.active-directory.b2c.authenticate-additional-parameters
azure.activedirectory.b2c.authorization-clients
spring.cloud.azure.active-directory.b2c.authorization-clients
azure.activedirectory.b2c.authorization-clients.<AZURE_CLIENT_NAME>.authorization-grant-type
spring.cloud.azure.active-directory.b2c.authorization-clients.<AZURE_CLIENT_NAME>.authorization-grant-type
azure.activedirectory.b2c.authorization-clients.<AZURE_CLIENT_NAME>.scopes
spring.cloud.azure.active-directory.b2c.authorization-clients.<AZURE_CLIENT_NAME>.scopes
azure.activedirectory.b2c.app-id-uri
spring.cloud.azure.active-directory.b2c.app-id-uri
azure.activedirectory.b2c.base-uri
spring.cloud.azure.active-directory.b2c.base-uri
azure.activedirectory.b2c.client-id
spring.cloud.azure.active-directory.b2c.credential.client-id
azure.activedirectory.b2c.client-secret
spring.cloud.azure.active-directory.b2c.credential.client-secret
azure.activedirectory.b2c.jwt-connect-timeout
spring.cloud.azure.active-directory.b2c.jwt-connect-timeout
azure.activedirectory.b2c.jwt-read-timeout
spring.cloud.azure.active-directory.b2c.jwt-read-timeout
azure.activedirectory.b2c.jwt-size-limit
spring.cloud.azure.active-directory.b2c.jwt-size-limit
azure.activedirectory.b2c.login-flow
spring.cloud.azure.active-directory.b2c.login-flow
azure.activedirectory.b2c.logout-success-url
spring.cloud.azure.active-directory.b2c.logout-success-url
azure.activedirectory.b2c.reply-url
spring.cloud.azure.active-directory.b2c.reply-url
azure.activedirectory.b2c.tenant-id
spring.cloud.azure.active-directory.b2c.profile.tenant-id
azure.activedirectory.b2c.user-flows
spring.cloud.azure.active-directory.b2c.user-flows
azure.activedirectory.b2c.user-name-attribute-name
spring.cloud.azure.active-directory.b2c.user-name-attribute-name
Removed properties from azure-spring-boot-starter-active-directory-b2c:
azure.activedirectory.b2c.allow-telemetry
azure.activedirectory.b2c.tenant
The value type of the following properties is changed from long to Duration:
jwt-connect-timeout
jwt-read-timeout
API changes
The following table shows the class mappings from azure-spring-boot-starter-active-directory-b2c to spring-cloud-azure-starter-active-directory-b2c:
com.azure.spring.autoconfigure.b2c.AADB2CAuthorizationRequestResolver
com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cAuthorizationRequestResolver
com.azure.spring.autoconfigure.b2c.AADB2CJwtBearerTokenAuthenticationConverter
com.azure.spring.cloud.autoconfigure.aad.AadJwtBearerTokenAuthenticationConverter
com.azure.spring.autoconfigure.b2c.AADB2CLogoutSuccessHandler
com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cLogoutSuccessHandler
com.azure.spring.autoconfigure.b2c.AADB2COidcLoginConfigurer
com.azure.spring.cloud.autoconfigure.aadb2c.AadB2COidcLoginConfigurer
com.azure.spring.autoconfigure.b2c.AADB2CProperties
com.azure.spring.cloud.autoconfigure.aadb2c.properties.AadB2cProperties
com.azure.spring.autoconfigure.b2c.AADB2CTrustedIssuerRepository
com.azure.spring.cloud.autoconfigure.aadb2c.AadB2cTrustedIssuerRepository
com.azure.spring.autoconfigure.b2c.AuthorizationClientProperties
com.azure.spring.cloud.autoconfigure.aad.properties.AuthorizationClientProperties
From azure-spring-boot-starter-cosmos to spring-cloud-azure-starter-data-cosmos
This guide is intended to assist in the migration to spring-cloud-azure-starter-data-cosmos from version 3 of azure-spring-boot-starter-cosmos.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
All configuration property names changed the prefix from azure.cosmos to spring.cloud.azure.cosmos.
The following table shows the class mappings from azure-spring-boot-starter-cosmos to spring-cloud-azure-starter-data-cosmos:
From azure-spring-boot-starter-keyvault-secrets to spring-cloud-azure-starter-keyvault-secrets
This guide is intended to assist in the migration to spring-cloud-azure-starter-keyvault-secrets from version 3 of azure-spring-boot-starter-keyvault-secrets.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
This section includes the changes about the properties added, removed and changed.
The following table shows the property mappings from azure-spring-boot-starter-keyvault-secrets to spring-cloud-azure-starter-keyvault-secrets:
azure.keyvault.case-sensitive-keys
spring.cloud.azure.keyvault.secret.property-source[n].case-sensitive
azure.keyvault.certificate-password
spring.cloud.azure.keyvault.secret.property-source[n].credential.client-certificate-password
azure.keyvault.certificate-path
spring.cloud.azure.keyvault.secret.property-source[n].credential.client-certificate-path
azure.keyvault.client-id
spring.cloud.azure.keyvault.secret.property-source[n].credential.client-id
azure.keyvault.client-key
spring.cloud.azure.keyvault.secret.property-source[n].credential.client-secret
azure.keyvault.enabled
spring.cloud.azure.keyvault.secret.property-source-enabled and spring.cloud.azure.keyvault.secret.property-source-enabled
azure.keyvault.order
No longer supported. Use the order in property-source[n] instead.
azure.keyvault.refresh-interval
spring.cloud.azure.keyvault.secret.property-source[n].refresh-interval
azure.keyvault.secret-keys
spring.cloud.azure.keyvault.secret.property-source[n].secret-keys
azure.keyvault.tenant-id
spring.cloud.azure.keyvault.secret.property-source[n].profile.tenant-id
azure.keyvault.uri
spring.cloud.azure.keyvault.secret.property-source[n].endpoint
Removed properties from spring-cloud-azure-starter-keyvault-secrets
azure.keyvault.allow-telemetry
azure.keyvault.order
The following points you should pay your attention to:
All configuration property names changed the prefix from azure.keyvault to spring.cloud.azure.keyvault.secret.
spring.cloud.azure.keyvault.secret.enabled is used to enable all Key Vault Secret features, include configure Key Vault secret client beans(like SecretClient and SecretAsyncClient) and add KeyVaultPropertySource in ConfigurableEnvironment.
spring.cloud.azure.keyvault.secret.property-source-enabled is used to enable all KeyVaultPropertySource. It will take effect only when spring.cloud.azure.keyvault.secret.enabled=true.
For Azure common properties(like client, proxy, retry, credential, profile) and Key Vault properties(like endpoint, service-version). If spring.cloud.azure.keyvault.secret.property-sources[n].PROPERTY_NAME isn't configured, spring.cloud.azure.keyvault.secret.PROPERTY_NAME will be used.
spring.cloud.azure.keyvault.secret.property-sources[n].resource is specific to a unique Azure resource, so if it's not configured, it won't get value from other places.
From azure-spring-boot-starter-servicebus-jms to spring-cloud-azure-starter-servicebus-jms
This guide is intended to assist in the migration to spring-cloud-azure-starter-servicebus-jms from version 3 of azure-spring-boot-starter-servicebus-jms.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
Configuration type for spring.jms.servicebus.idle-timeout changed from long(milliseconds) to Duration pattern for readability.
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-blob
This guide is intended to assist in the migration to spring-cloud-azure-starter-storage-blob from version 3 of azure-spring-boot-starter-storage.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
All configuration property names changed the prefix from azure.storage to spring.cloud.azure.storage.blob.
The following table shows the property mappings from azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-blob:
Legacy properties
Modern properties
com.azure.spring.autoconfigure.storage.resource.AzureStorageProtocolResolver
com.azure.spring.core.resource.AzureStorageBlobProtocolResolver
com.azure.spring.autoconfigure.storage.resource.BlobStorageResource
com.azure.spring.core.resource.StorageBlobResource
com.azure.spring.autoconfigure.storage.resource.AzureStorageResourcePatternResolver
com.azure.spring.core.resource.AzureStorageBlobProtocolResolver
From azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-file-share
This guide is intended to assist in the migration to spring-cloud-azure-starter-storage-file-share from version 3 of azure-spring-boot-starter-storage.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
All configuration property names changed the prefix from azure.storage to spring.cloud.azure.storage.fileshare.
The following table shows the property mappings from azure-spring-boot-starter-storage to spring-cloud-azure-starter-storage-file-share:
Legacy properties
Modern properties
com.azure.spring.autoconfigure.storage.resource.AzureStorageProtocolResolver
com.azure.spring.core.resource.AzureStorageFileProtocolResolver
com.azure.spring.autoconfigure.storage.resource.FileStorageResource
com.azure.spring.core.resource.StorageFileResource
com.azure.spring.autoconfigure.storage.resource.AzureStorageResourcePatternResolver
com.azure.spring.core.resource.AzureStorageFileProtocolResolver
From azure-spring-cloud-starter-eventhubs to spring-cloud-azure-starter-integration-eventhubs
This guide is intended to assist in the migration to spring-cloud-azure-starter-integration-eventhubs from version 2 of azure-spring-cloud-starter-eventhubs.




    

For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
Important
Configuration prefix has been changed from spring.cloud.azure.eventhub to spring.cloud.azure.eventhubs.
For changes to the child entries for this prefix, see the following tables:
The following table shows property mappings from azure-spring-cloud-starter-eventhubs to spring-cloud-azure-starter-integration-eventhubs:
spring.cloud.azure.eventhub.connection-string
spring.cloud.azure.eventhubs.connection-string
spring.cloud.azure.eventhub.checkpoint-storage-account
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name
spring.cloud.azure.eventhub.checkpoint-access-key
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key
spring.cloud.azure.eventhub.checkpoint-container
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name
      eventhub:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        checkpoint-storage-account: ${AZURE_CHECKPOINT_STORAGE_ACCOUNT_NAME}
        checkpoint-access-key: ${AZURE_CHECKPOINT_ACCOUNT_KEY}
        checkpoint-container: ${AZURE_CHECKPOINT_CONTAINER_NAME}
spring:
  cloud:
    azure:
      eventhubs:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        processor:
          checkpoint-store:
            container-name: ${AZURE_STORAGE_CONTAINER_NAME}
            account-name: ${AZURE_STORAGE_ACCOUNT_NAME}
            account-key: ${AZURE_STORAGE_ACCOUNT_KEY}
API changes
For the changes to the listener annotations, see the migration guide of the <<migration-azure-spring-cloud-messaging, azure-spring-cloud-messaging>> library.
Drop EventHubOperation with the subscribing function moved to class EventHubsMessageListenerContainer and the sending function moved to EventHubsTemplate.
Rename EventHubInboundChannelAdapter as EventHubsInboundChannelAdapter to keep consistent with the service of Azure
Event Hubs.
Change the constructor from EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) to EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer) and EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode).
Change CheckpointConfig instantiation style to the simple constructor instead of build style.
Drop API EventHubOperation#setCheckpointConfig. To set the checkpoint configuration for the inbound channel adapter, users can call the method EventHubsContainerProperties#setCheckpointConfig.
Drop API EventHubOperation#setBatchConsumerConfig. To set the batch-consuming configuration for the inbound channel adapter, users can call the two methods EventHubsContainerProperties#getBatch#setMaxSize and EventHubsContainerProperties#getBatch#setMaxWaitTime meanwhile.
For the batch consuming mode, change the message header names converted from batched messages.
Change message header from azure_eventhub_enqueued_time to azure_eventhubs_batch_converted_enqueued_time.
Change message header from azure_eventhub_offset to azure_eventhubs_batch_converted_offset.
Change message header from azure_eventhub_sequence_number to azure_eventhubs_batch_converted_sequence_number.
Change message header from azure_partition_key to azure_batch_converted_partition_key.
When publishing messages to Event Hubs, ignore all message headers converted from batched messages. Headers include:
azure_batch_converted_partition_key
azure_eventhubs_batch_converted_enqueued_time
azure_eventhubs_batch_converted_offset
azure_eventhubs_batch_converted_sequence_number
azure_eventhubs_batch_converted_system_properties
azure_eventhubs_batch_converted_application_properties
The BATCH checkpoint mode only works in the batch-consuming mode now, which can be enabled by passing ListenerMode.BATCH to EventHubsInboundChannelAdapter constructor.
The following table shows the class mappings from azure-spring-cloud-starter-eventhubs to spring-cloud-azure-starter-integration-eventhubs:
com.azure.spring.integration.core.EventHubHeaders
com.azure.spring.messaging.eventhubs.support.EventHubsHeaders
com.azure.spring.integration.core.api.CheckpointConfig
com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode
com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.eventhub.inbound.EventHubInboundChannelAdapter
com.azure.spring.integration.eventhubs.inbound.EventHubsInboundChannelAdapter
    @Bean
    public EventHubInboundChannelAdapter messageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel, EventHubOperation   eventhubOperation) {
        eventhubOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode  (CheckpointMode.MANUAL).build());
        EventHubInboundChannelAdapter adapter = new EventHubInboundChannelAdapter("EVENTHUB_NAME",
            eventhubOperation, "CONSUMER_GROUP");
        adapter.setOutputChannel(inputChannel);
        return adapter;
Modern code:
public class Demo {
    @Bean
    public EventHubsMessageListenerContainer messageListenerContainer(EventHubsProcessorFactory processorFactory) {
        EventHubsContainerProperties containerProperties = new EventHubsContainerProperties();
        containerProperties.setEventHubName("EVENTHUB_NAME");
        containerProperties.setConsumerGroup("CONSUMER_GROUP");
        CheckpointConfig config = new CheckpointConfig(CheckpointMode.MANUAL);
        containerProperties.setCheckpointConfig(config);
        return new EventHubsMessageListenerContainer(processorFactory, containerProperties);
    @Bean
    public EventHubsInboundChannelAdapter messageChannelAdapter(@Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
                                                                EventHubsMessageListenerContainer listenerContainer) {
        EventHubsInboundChannelAdapter adapter = new EventHubsInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
DefaultMessageHandler sample code:
Legacy code:
public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL")
    public MessageHandler messageSender(EventHubOperation eventhubOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("EVENTHUB_NAME", eventhubOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.error("There was an error sending the message.", ex);
        return handler;
Modern code:
public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL")
    public MessageHandler messageSender(EventHubsTemplate eventhubOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("EVENTHUB_NAME", eventhubOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.error("There was an error sending the message.", ex);
        return handler;
From azure-spring-integration-eventhubs to spring-integration-azure-eventhubs
This guide is intended to assist in the migration to spring-integration-azure-eventhubs from version 2 of azure-spring-integration-eventhubs.
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
API changes
Drop EventHubOperation with the subscribing function moved to class EventHubsMessageListenerContainer and the sending function moved to EventHubsTemplate.
Rename EventHubInboundChannelAdapter as EventHubsInboundChannelAdapter to keep consistent with the service of Azure Event Hubs.
Change the constructor from EventHubInboundChannelAdapter(String, SubscribeByGroupOperation, String) to EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer) and EventHubsInboundChannelAdapter(EventHubsMessageListenerContainer, ListenerMode).
Change CheckpointConfig instantiation style to the simple constructor instead of build style.
Drop API EventHubOperation#setCheckpointConfig. To set the checkpoint configuration for the inbound channel adapter, users can call the method EventHubsContainerProperties#setCheckpointConfig.
Drop API EventHubOperation#setBatchConsumerConfig. To set the batch-consuming configuration for the inbound channel adapter, users can call the two methods EventHubsContainerProperties#getBatch#setMaxSize and EventHubsContainerProperties#getBatch#setMaxWaitTime meanwhile.
For the batch consuming mode, change the message header names converted from batched messages.
Change message header from azure_eventhub_enqueued_time to azure_eventhubs_batch_converted_enqueued_time.
Change message header from azure_eventhub_offset to azure_eventhubs_batch_converted_offset.
Change message header from azure_eventhub_sequence_number to azure_eventhubs_batch_converted_sequence_number.
Change message header from azure_partition_key to azure_batch_converted_partition_key.
When publishing messages to Event Hubs, ignore all message headers converted from batched messages. Headers include:
azure_batch_converted_partition_key
azure_eventhubs_batch_converted_enqueued_time
azure_eventhubs_batch_converted_offset
azure_eventhubs_batch_converted_sequence_number
azure_eventhubs_batch_converted_system_properties
azure_eventhubs_batch_converted_application_properties
The BATCH checkpoint mode only works in the batch-consuming mode now, which can be enabled by passing ListenerMode.BATCH to EventHubsInboundChannelAdapter constructor.
The following table shows the class mappings from azure-spring-integration-eventhubs  to spring-integration-azure-eventhubs:
com.azure.spring.integration.core.EventHubHeaders
com.azure.spring.messaging.eventhubs.support.EventHubsHeaders
com.azure.spring.integration.core.api.CheckpointConfig
com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointConfig
com.azure.spring.integration.core.api.CheckpointMode
com.azure.spring.messaging.eventhubs.core.checkpoint.CheckpointMode
com.azure.spring.integration.core.api.reactor.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.eventhub.inbound.EventHubInboundChannelAdapter
com.azure.spring.integration.eventhubs.inbound.EventHubsInboundChannelAdapter
From azure-spring-cloud-starter-servicebus to spring-cloud-azure-starter-integration-servicebus
This guide is intended to assist in the migration to spring-cloud-azure-starter-integration-servicebus from version 2 of azure-spring-cloud-starter-servicebus.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
For all configuration options supported in spring-cloud-azure-starter-integration-servicebus, the prefix remains as spring.cloud.azure.servicebus.
The following table shows the property mappings from azure-spring-cloud-starter-servicebus to spring-cloud-azure-starter-integration-servicebus:
spring.cloud.azure.servicebus.transport-type
spring.cloud.azure.servicebus.client.transport-type
spring.cloud.azure.servicebus.retry-options.retry-mode
spring.cloud.azure.servicebus.retry.mode
spring.cloud.azure.servicebus.retry-options.max-retries
spring.cloud.azure.servicebus.retry.exponential.max-retries or spring.cloud.azure.servicebus.retry.fixed.max-retries, should be configured depending on spring.cloud.azure.servicebus.retry.mode=fixed or exponential
spring.cloud.azure.servicebus.retry-options.delay
spring.cloud.azure.servicebus.retry.exponential.base-delay or spring.cloud.azure.servicebus.retry.fixed.delay, should be configured depending on spring.cloud.azure.servicebus.retry.mode=fixed or exponential
spring.cloud.azure.servicebus.retry-options.max-delay
spring.cloud.azure.servicebus.retry.exponential.max-delay
spring.cloud.azure.servicebus.retry-options.try-timeout
spring.cloud.azure.servicebus.retry.try-timeout
API changes
Drop ServiceBusQueueOperation and ServiceBusTopicOperation with the subscribing function moved to class ServiceBusMessageListenerContainer and the sending function moved to ServiceBusTemplate.
Drop ServiceBusQueueInboundChannelAdapter and ServiceBusTopicInboundChannelAdapter, and move the functionality to listen to a Service Bus queue/topic entity to ServiceBusInboundChannelAdapter.
Change the constructor from ServiceBusQueueInboundChannelAdapter(String, SubscribeByGroupOperation, String) to ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) and ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode).
Change the constructor from ServiceBusTopicInboundChannelAdapter(String, SubscribeByGroupOperation, String) to ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) and ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode).
Drop APIs ServiceBusQueueOperation#setCheckpointConfig and ServiceBusTopicOperation#setCheckpointConfig. To set the checkpoint configuration for the inbound channel adapter, users can call the method ServiceBusContainerProperties#setAutoComplete instead. To disable the auto-complete mode is equivalent to MANUAL checkpoint mode and to enable it will trigger the RECORD mode.
Drop APIs ServiceBusQueueOperatio#setClientConfig and ServiceBusTopicOperation#setClientConfig. To configure the underlying ServiceBusProcessorClient used by the inbound channel adapter, users can use ServiceBusContainerProperties instead.
Drop CompletableFuture support in ServiceBusTemplate and DefaultMessageHandler, support Reactor instead.
Add new API of ServiceBusTemplate#setDefaultEntityType to specify the entity type, which is required when no bean of PropertiesSupplier&lt;String, ProducerProperties&gt; is provided for the ProducerProperties#entityType.
Drop message header AzureHeaders.RAW_ID. Use ServiceBusMessageHeaders.MESSAGE_ID instead.
The following table shows the class mappings from azure-spring-cloud-starter-servicebus to spring-cloud-azure-starter-integration-servicebus:




    

com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders
com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageConverter
com.azure.spring.messaging.servicebus.support.converter.ServiceBusMessageConverter
com.azure.spring.integration.core.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.servicebus.inbound.ServiceBusQueueInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusTopicInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
ServiceBusInboundChannelAdapter sample code:
Legacy code of using ServiceBusQueueInboundChannelAdapter or ServiceBusTopicInboundChannelAdapter:
public class Demo {
    @Bean
    public ServiceBusQueueInboundChannelAdapter queueMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL_NAME") MessageChannel inputChannel, ServiceBusQueueOperation queueOperation) {
        queueOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode(CheckpointMode.MANUAL).build());
        ServiceBusQueueInboundChannelAdapter adapter = new ServiceBusQueueInboundChannelAdapter("QUEUE_NAME",
            queueOperation);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    @Bean
    public ServiceBusTopicInboundChannelAdapter topicMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL_NAME") MessageChannel inputChannel, ServiceBusTopicOperation topicOperation) {
        topicOperation.setCheckpointConfig(CheckpointConfig.builder().checkpointMode(CheckpointMode.MANUAL).build());
        ServiceBusTopicInboundChannelAdapter adapter = new ServiceBusTopicInboundChannelAdapter("TOPIC_NAME",
            topicOperation, "SUBSCRIPTION_NAME");
        adapter.setOutputChannel(inputChannel);
        return adapter;
Modern code:
public class Demo {
    @Bean("queue-listener-container")
    public ServiceBusMessageListenerContainer messageListenerContainer(ServiceBusProcessorFactory processorFactory) {
        ServiceBusContainerProperties containerProperties = new ServiceBusContainerProperties();
        containerProperties.setEntityName("QUEUE_NAME");
        containerProperties.setAutoComplete(false);
        return new ServiceBusMessageListenerContainer(processorFactory, containerProperties);
    @Bean
    public ServiceBusInboundChannelAdapter queueMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
        @Qualifier("queue-listener-container") ServiceBusMessageListenerContainer listenerContainer) {
        ServiceBusInboundChannelAdapter adapter = new ServiceBusInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
    @Bean("topic-listener-container")
    public ServiceBusMessageListenerContainer messageListenerContainer(ServiceBusProcessorFactory processorFactory) {
        ServiceBusContainerProperties containerProperties = new ServiceBusContainerProperties();
        containerProperties.setEntityName("TOPIC_NAME");
        containerProperties.setSubscriptionName("SUBSCRIPTION_NAME");
        containerProperties.setAutoComplete(false);
        return new ServiceBusMessageListenerContainer(processorFactory, containerProperties);
    @Bean
    public ServiceBusInboundChannelAdapter topicMessageChannelAdapter(
        @Qualifier("INPUT_CHANNEL") MessageChannel inputChannel,
        @Qualifier("topic-listener-container") ServiceBusMessageListenerContainer listenerContainer) {
        ServiceBusInboundChannelAdapter adapter = new ServiceBusInboundChannelAdapter(listenerContainer);
        adapter.setOutputChannel(inputChannel);
        return adapter;
DefaultMessageHandler sample code:
Legacy code, taking queue as example:
public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL_NAME")
    public MessageHandler queueMessageSender(ServiceBusQueueOperation queueOperation) {
        DefaultMessageHandler handler = new DefaultMessageHandler("QUEUE_NAME", queueOperation);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully.");
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.info("There was an error sending the message.");
        return handler;
Modern code:
public class Demo {
    @Bean
    @ServiceActivator(inputChannel = "OUTPUT_CHANNEL_NAME")
    public MessageHandler queueMessageSender(ServiceBusTemplate serviceBusTemplate) {
        serviceBusTemplate.setDefaultEntityType(ServiceBusEntityType.QUEUE);
        DefaultMessageHandler handler = new DefaultMessageHandler("QUEUE_NAME", serviceBusTemplate);
        handler.setSendCallback(new ListenableFutureCallback<Void>() {
            @Override
            public void onSuccess(Void result) {
                LOGGER.info("Message was sent successfully for {}.", "QUEUE_NAME");
            @Override
            public void onFailure(Throwable ex) {
                LOGGER.info("There was an error sending the message.");
        return handler;
From azure-spring-integration-servicebus to spring-integration-azure-servicebus
This guide is intended to assist in the migration to spring-integration-azure-servicebus from version 2 of azure-spring-integration-servicebus.
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
API changes
Drop ServiceBusQueueOperation and ServiceBusTopicOperation with the subscribing function moved to class ServiceBusMessageListenerContainer and the sending function moved to ServiceBusTemplate.
Drop ServiceBusQueueInboundChannelAdapter and ServiceBusTopicInboundChannelAdapter, and move the functionality to listen to a Service Bus queue/topic entity to ServiceBusInboundChannelAdapter.
Change the constructor from ServiceBusQueueInboundChannelAdapter(String, SubscribeByGroupOperation, String) to ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) and ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode).
Change the constructor from ServiceBusTopicInboundChannelAdapter(String, SubscribeByGroupOperation, String) to ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer) and ServiceBusInboundChannelAdapter(ServiceBusMessageListenerContainer, ListenerMode).
Drop APIs ServiceBusQueueOperation#setCheckpointConfig and ServiceBusTopicOperation#setCheckpointConfig. To set the checkpoint configuration for the inbound channel adapter, users can call the method ServiceBusContainerProperties#setAutoComplete instead. To disable the auto-complete mode is equivalent to MANUAL checkpoint mode and to enable it will trigger the RECORD mode.
Drop APIs ServiceBusQueueOperation#setClientConfig and ServiceBusTopicOperation#setClientConfig. To configure the underlying ServiceBusProcessorClient used by the inbound channel adapter, users can use ServiceBusContainerProperties instead.
Drop CompletableFuture support in ServiceBusTemplate and DefaultMessageHandler, support Reactor instead.
Add new API of ServiceBusTemplate#setDefaultEntityType to specify the entity type, which is required when no bean of PropertiesSupplier&lt;String, ProducerProperties&gt; is provided for the ProducerProperties#entityType.
Drop message header AzureHeaders.RAW_ID. Use ServiceBusMessageHeaders.MESSAGE_ID instead.
The following table shows the class mappings from azure-spring-integration-servicebus to spring-integration-azure-servicebus:
com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders
com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.servicebus.converter.ServiceBusMessageConverter
com.azure.spring.messaging.servicebus.support.converter.ServiceBusMessageConverter
com.azure.spring.integration.core.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.servicebus.inbound.ServiceBusQueueInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusTopicInboundChannelAdapter
com.azure.spring.integration.servicebus.inbound.ServiceBusInboundChannelAdapter
From azure-spring-cloud-starter-storage-queue to spring-cloud-azure-starter-integration-storage-queue
This guide is intended to assist in the migration to spring-cloud-azure-starter-integration-storage-queue from version 2 of azure-spring-cloud-starter-storage-queue.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
All configuration property names changed the prefix from spring.cloud.azure.storage to spring.cloud.azure.storage.queue.
The following table shows the property mappings from azure-spring-cloud-starter-storage-queue to spring-cloud-azure-starter-integration-storage-queue:
Drop StorageQueueOperation and provide StorageQueueTemplate instead.
Drop checkpoint-mode configuration in StorageQueueTemplate, only support the MANUAL mode.
The following table shows the class mappings from azure-spring-cloud-starter-storage-queue to spring-cloud-azure-starter-integration-storage-queue.
com.azure.spring.integration.storage.queue.converter.StorageQueueMessageConverter
com.azure.spring.messaging.storage.queue.support.converter.StorageQueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.storage.queue.StorageQueueTemplate
com.azure.spring.storage.queue.core.StorageQueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource
From azure-spring-integration-storage-queue to spring-integration-azure-storage-queue
This guide is intended to assist in the migration to spring-integration-azure-storage-queue from version 2 of azure-spring-integration-storage-queue.
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
API changes
Drop StorageQueueOperation and provide StorageQueueTemplate instead.
Drop checkpoint-mode configuration in StorageQueueTemplate, only support the MANUAL mode.
The following table shows the class mappings from azure-spring-integration-storage-queue to spring-integration-azure-storage-queue.
com.azure.spring.integration.storage.queue.converter.StorageQueueMessageConverter
com.azure.spring.messaging.storage.queue.support.converter.StorageQueueMessageConverter
com.azure.spring.integration.core.api.reactor.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.storage.queue.StorageQueueTemplate
com.azure.spring.storage.queue.core.StorageQueueTemplate
com.azure.spring.integration.core.api.reactor.DefaultMessageHandler
com.azure.spring.integration.core.handler.DefaultMessageHandler
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource
com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource
From azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs
This guide is intended to assist in the migration to spring-cloud-azure-stream-binder-eventhubs from version 2 of azure-spring-cloud-stream-binder-eventhubs.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
Important




    

Configuration prefix has been changed from spring.cloud.azure.eventhub to spring.cloud.azure.eventhubs.
Important
The binder type is renamed from: eventhub to eventhubs.
For changes to the child entries for the following prefix, see the following table.
The following table shows property mappings from azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs:
spring.cloud.azure.eventhub.connection-string
spring.cloud.azure.eventhubs.connection-string
spring.cloud.azure.eventhub.checkpoint-storage-account
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-name
spring.cloud.azure.eventhub.checkpoint-access-key
spring.cloud.azure.eventhubs.processor.checkpoint-store.account-key
spring.cloud.azure.eventhub.checkpoint-container
spring.cloud.azure.eventhubs.processor.checkpoint-store.container-name
spring.cloud.stream.eventhub.bindings.binding-name.consumer.max-batch-size
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.batch.max-size
spring.cloud.stream.eventhub.bindings.binding-name.consumer.max-wait-time
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.batch.max-wait-time
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-mode
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.mode
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-count
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.count
spring.cloud.stream.eventhub.bindings.binding-name.consumer.checkpoint-interval
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.checkpoint.interval
spring.cloud.stream.eventhub.bindings.binding-name.consumer.start-position
spring.cloud.stream.eventhubs.bindings.binding-name.consumer.initial-partition-event-position
The value type of the start-position configuration is also changed from an enum of com.azure.spring.integration.core.api.StartPosition to a map of StartPositionProperties for each partition. Thus, the key is the partition ID, and the value is of com.azure.spring.cloud.service.eventhubs.properties.StartPositionProperties which includes properties of offset, sequence number, enqueued date time and whether inclusive.
Configuration migration examples
To use the connection string for authentication and migrate the above mentioned properties, configuration changes are listed the follows:
Legacy configuration:
spring:
  cloud:
    azure:
      eventhub:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        checkpoint-storage-account: ${AZURE_CHECKPOINT_STORAGE_ACCOUNT_NAME}
        checkpoint-access-key: ${AZURE_CHECKPOINT_ACCOUNT_KEY}
        checkpoint-container: ${AZURE_CHECKPOINT_CONTAINER_NAME}
    stream:
      eventhub:
        bindings:
          <binding-name>:
            consumer:
              max-batch-size: ${AZURE_MAX_BATCH_SIZE}
              max-wait-time: ${AZURE_MAX_WAIT_TIME}
              checkpoint-mode: ${AZURE_CHECKPOINT_MODE}
              checkpoint-count: ${AZURE_CHECKPOINT_COUNT}
              checkpoint-interval: ${AZURE_CHECKPOINT_INTERVAL}
              start-position: EARLIEST
Modern configuration:
spring:
  cloud:
    azure:
      eventhubs:
        connection-string: ${AZURE_EVENTHUBS_CONNECTION_STRING}
        processor:
          checkpoint-store:
            container-name: ${AZURE_STORAGE_CONTAINER_NAME}
            account-name:  ${AZURE_STORAGE_ACCOUNT_NAME}
            account-key: ${AZURE_STORAGE_ACCOUNT_KEY}
    stream:
      eventhubs:
        bindings:
          <binding-name>:
            consumer:
              batch:
                max-size: ${AZURE_MAX_BATCH_SIZE}
                max-wait-time: ${AZURE_MAX_WAIT_TIME}
              checkpoint:
                mode: ${AZURE_CHECKPOINT_MODE}
                count: ${AZURE_CHECKPOINT_COUNT}
                interval: ${AZURE_CHECKPOINT_INTERVAL}
              initial-partition-event-position:
                  offset: earliest
                  sequence-number: 100
                  enqueued-date-time: 2022-01-12T13:32:47.650005Z
                  inclusive: false
If you use security principals instead of connection strings, in versions before 4.0 the application will firstly connect to Azure Resource Manager (ARM) with the provided security principal, and then retrieve the connection string of the specified namespace with ARM. In the end the application uses the retrieved connection string to connect to Azure Event Hubs. In this way the provided security principal should be granted with the Contributor role to retrieve of the associated Azure Event Hubs namespace.
For Azure Spring Apps 4.0, we provide two ways of leveraging security principals for authentication. One is still using the principals to connect to ARM and retrieve the connection strings where the Contributor role is required for the principals. The other leverages security principals to authenticate to Azure Active Directory (Azure AD) and then connect to Azure Event Hubs directly. In this case, the Contributor role isn't necessary anymore, while other Data related roles are required for messaging operations. To make sure the security principal has been granted the sufficient permission to access the Azure resource, see Authorize access with Azure AD.
For authentication based on ARM, taking service principal as example, configuration migration is listed the follows, where the assigned role should not change:
Legacy configuration:
spring:
  cloud:
    azure:
      client-id: ${AZURE_CLIENT_ID}
      client-secret: ${AZURE_CLIENT_SECRET}
      tenant-id: ${AZURE_TENANT_ID}
      resource-group: ${EVENTHUB_RESOURCE_GROUP}
      eventhub:
        namespace: ${EVENTHUB_NAMESPACE}
Modern configuration, properties for Azure subscription ID and resource group are required:
spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}
        resource:
          resource-group: ${RESOURCE_GROUP}
You can also migrate to authenticate and authorize with Azure AD directly without making a detour to ARM. Make sure to grant the security principal necessary Data roles for messaging operations. The configuration examples of the service principal and the managed identity are listed the follows:
With a service principal
spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}
With a managed identity
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${AZURE_MANAGED_IDENTITY_CLIENT_ID} # Only needed when using a user-assigned managed identity
      eventhubs:
        namespace: ${EVENTHUB_NAMESPACE}
API changes
The following table shows the class mappings from azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs.
com.azure.spring.integration.core.api.reactor.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer
com.azure.spring.integration.core.AzureHeaders
com.azure.spring.messaging.AzureHeaders
com.azure.spring.integration.core.EventHubHeaders
com.azure.spring.messaging.eventhubs.support.EventHubsHeaders
From azure-spring-cloud-stream-binder-servicebus-* to spring-cloud-azure-stream-binder-servicebus
This guide is intended to assist in the migration to spring-cloud-azure-stream-binder-servicebus from version 2 of azure-spring-cloud-stream-binder-servicebus-queue or azure-spring-cloud-stream-binder-servicebus-topic.
For general information, use the following links:
For an overview of the changes in 4.0, see the Introduction and Migration benefits sections.
To learn more about the strategy changes in the project naming, see the Naming changes section.
To learn how to use one BOM for all Spring Cloud Azure libraries, see the BOM section.
To learn how to handle authentication in Spring Cloud Azure 4.0, see the Authentication changes section.
To learn how to leverage spring-boot-properties-migrator during migration, see the Configure each SDK section.
To learn more about the global and common configuration changes, see the Global configurations section.
SDK configuration changes
Important
Legacy binder libaries are azure-spring-cloud-stream-binder-servicebus-queue and azure-spring-cloud-stream-binder-servicebus-topic, and now they're merged into one spring-cloud-azure-stream-binder-servicebus.
Important
The binder type is combined from servicebus-queue and servicebus-topic as servicebus.
The following table lists the new configuration properties of spring-cloud-azure-stream-binder-servicebus:
spring.cloud.azure.servicebus.transport-type
spring.cloud.azure.servicebus.client.transport-type
spring.cloud.azure.servicebus.retry-options.retry-mode
spring.cloud.azure.servicebus.retry.mode
spring.cloud.azure.servicebus.retry-options.max-retries
spring.cloud.azure.servicebus.retry.exponential.max-retries or spring.cloud.azure.servicebus.retry.fixed.max-retries, should be configured depending on spring.cloud.azure.servicebus.retry.mode=fixed or exponential
spring.cloud.azure.servicebus.retry-options.delay
spring.cloud.azure.servicebus.retry.exponential.base-delay or spring.cloud.azure.servicebus.retry.fixed.delay, should be configured depending on spring.cloud.azure.servicebus.retry.mode=fixed or exponential
spring.cloud.azure.servicebus.retry-options.max-delay
spring.cloud.azure.servicebus.retry.exponential.max-delay
spring.cloud.azure.servicebus.retry-options.try-timeout
spring.cloud.azure.servicebus.retry.try-timeout
spring.cloud.stream.servicebus.queue.bindings.*
spring.cloud.stream.servicebus.bindings.*
spring.cloud.stream.servicebus.queue.bindings.binding-name.consumer.concurrency
spring.cloud.stream.servicebus.bindings.binding-name.consumer.max-concurrent-sessions/max-concurrent-calls
spring.cloud.stream.servicebus.queue.bindings.binding-name.consumer.checkpoint-mode
spring.cloud.stream.servicebus.bindings.binding-name.consumer.auto-complete
spring.cloud.stream.servicebus.topic.bindings.*
spring.cloud.stream.servicebus.bindings.*
spring.cloud.stream.servicebus.topic.bindings.binding-name.consumer.concurrency
spring.cloud.stream.servicebus.bindings.binding-name.consumer.max-concurrent-sessions/max-concurrent-calls
spring.cloud.stream.servicebus.topic.bindings.binding-name.consumer.checkpoint-mode
spring.cloud.stream.servicebus.bindings.binding-name.consumer.auto-complete
The concurrency property will be replaced by the maxConcurrentSessions when sessionsEnabled is true and the maxConcurrentCalls when sessionsEnabled is false.
Enabling auto-complete is equal to RECORD checkpoint mode, and oppositely the MANUAL mode.
Configuration migration examples
Legacy configuration, taking queue as example:
spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${AZURE_SERVICEBUS_BINDER_CONNECTION_STRING}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
        supply-out-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
      servicebus:
        queue:
          bindings:
            consume-in-0:
              consumer:
                checkpoint-mode: MANUAL
Modern configuration:
spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${AZURE_SERVICEBUS_BINDER_CONNECTION_STRING}
    stream:
      function:
        definition: consume;supply
      bindings:
        consume-in-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
        supply-out-0:
          destination: ${AZURE_SERVICEBUS_QUEUE_NAME}
      servicebus:
        bindings:
          consume-in-0:
            consumer:
              auto-complete: false
          supply-out-0:
            producer:
              entity-type: queue #set as topic if needed
If you use security principals instead of connection strings, in versions before 4.0 the application will firstly connect to Azure Resource Manager (ARM) with the provided security principal, and then retrieve the connection string of the specified namespace with ARM. In the end the application uses the retrieved connection string to connect to Azure Service Bus. In this way the provided security principal should be granted with the Contributor role to retrieve of the associated Azure Service Bus namespace.
For Azure Spring Apps 4.0, we provide two ways of leveraging security principals for authentication. One is still using the principals to connect to ARM and retrieve the connection strings where the Contributor role is required for the principals. The other leverages security principals to authenticate to Azure Active Directory (Azure AD) and then connect to the Azure Service Bus directly. In this case, the Contributor role isn't necessary anymore, while other Data related roles are required for messaging operations. To make sure the security principal has been granted the sufficient permission to access the Azure resource, see Authorize access with Azure AD.
For authentication based on ARM, taking service principal as example, configuration migration is listed the follows, where the assigned role should not change:
Legacy configuration:
spring:
  cloud:
    azure:
      client-id: ${AZURE_CLIENT_ID}
      client-secret: ${AZURE_CLIENT_SECRET}
      tenant-id: ${AZURE_TENANT_ID}
      resource-group: ${SERVICEBUS_RESOURCE_GROUP}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
Modern configuration, properties for Azure subscription ID and resource group are required:
spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
        resource:
          resource-group: ${SERVICEBUS_RESOURCE_GROUP}
You can also migrate to authenticate and authorize with Azure AD directly without making a detour to ARM. Make sure to grant the security principal necessary Data roles for messaging operations. The configuration examples of the service principal and the managed identity are listed the follows:
With a service principal
spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: ${AZURE_TENANT_ID}
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
With a managed identity
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${AZURE_MANAGED_IDENTITY_CLIENT_ID} # Only needed when using a user-assigned   managed identity
      servicebus:
        namespace: ${SERVICEBUS_NAMESPACE}
API changes
Drop message header AzureHeaders.RAW_ID. Use ServiceBusMessageHeaders.MESSAGE_ID instead.
The following table shows the class mappings from azure-spring-cloud-stream-binder-eventhubs to spring-cloud-azure-stream-binder-eventhubs.
com.azure.spring.integration.servicebus.converter.ServiceBusMessageHeaders
com.azure.spring.messaging.servicebus.support.ServiceBusMessageHeaders
com.azure.spring.integration.core.api.Checkpointer
com.azure.spring.messaging.checkpoint.Checkpointer