Azure SDK Migration Guidelines

Context

The application is identified using legacy Azure SDKs for Java (com.microsoft.azure.*). These libraries reached end of support in 2023. They are not recommended for use in production, should be migrated to the latest Azure SDKs with the latest security patches and new capabilities support.

Follow these steps:

* Inventory legacy dependencies: Use tools such as mvn dependency:tree or gradlew dependencies to find every com.microsoft.azure.* SDK and map each one to its modern counterpart under com.azure.*. Do not rely solely on the root reactor — also grep the entire repository for legacy coordinates so you catch build files that aren't reachable from the root project. Run from the repo root:

  # Find every file referencing legacy groupIds/artifacts, including CI, samples, parent poms, buildSrc, version catalogs, Dockerfiles, and docs.
  grep -RIn --exclude-dir={.git,target,build,node_modules,out} \
    -E 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["'\''])' .

PowerShell equivalent (run from repo root):

  Get-ChildItem -Path . -Recurse -File |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["''])'

Commonly overlooked locations:.ci/**/pom.xml, ci/**, parent/BOM poms, buildSrc/, gradle/libs.versions.toml, settings.gradle(.kts), archetype-resources/, sample sub-modules, Dockerfiles, shell/PowerShell scripts, and README snippets. Every hit must end up on the migration file list.

* Adopt supported SDKs: Replace the legacy dependencies with their modern equivalents in your pom.xml or build.gradle, following the migration guide to align feature parity and new SDK names.

* Update application code: Refactor your code to the builder-based APIs, updated authentication flows (Azure Identity), and modern async or reactive patterns required by the latest SDKs. Add concise comments explaining non-obvious changes.

* Test thoroughly: Run unit, integration, and end-to-end tests to validate that the modern SDKs behave as expected, focusing on authentication, retry, and serialization differences.

Migration Guide

Assumption

Project is Maven or Gradle.
Java code is on JDK 8 or above.

Migrate dependencies

Use the latest stable azure-sdk-bom version from the Azure SDK for Java source of truth before editing any build file. Versions below 1.3.0 are invalid for this migration flow and must not be used.

Follow the detailed steps in BOM Migration Guide — it covers how to determine the latest BOM version, plus Maven, plain Gradle, TOML version catalogs (libs.versions.toml), and programmatic version catalogs (settings.gradle).

Migrate Java Code

Make a list of source code/maven/gradle files that contains legacy SDK packages. Migrate each of them.
Determine legacy SDK artifacts according to previous files, find suitable migration guides in Package-Specific Migration Guides and follow the guides whenever possible. Record which migration guide URL you used for each legacy package (e.g., in your plan or commit messages), so you can validate against them later.
Do not change the Java package ...; declaration at the top of each source file, and do not rename or move the source file's directory path to match a new SDK package structure. Keep every .java file in its original directory; only update import statements and type usages inside the file body. For example, if a file lives in src/main/java/com/microsoft/azure/eventprocessorhosts/Consumer.java with package com.microsoft.azure.eventprocessorhosts;, it must stay in that exact directory and keep that exact package declaration — even though the modern SDK uses com.azure.messaging.eventhubs.
Do not upgrade JDK version, if it is already JDK 8 or above.
If there is test in the project, Java code there also need to be updated.

Package-Specific Source Code Guidelines (Add them to plan guidelines when generating plan)

Use these package-specific references:

Validation

Make sure

Migrated project pass compilation.
All tests pass. Don't silently skip tests.
No legacy SDK dependencies/references exist. This is a hard gate, not a self-assessment — you must prove it by running the commands below from the repo root and showing they return zero hits. Do not declare migration complete until all three return empty:

  # 1. Legacy groupId / artifact references in ANY text file (pom.xml, *.gradle, *.gradle.kts, libs.versions.toml, Dockerfile, *.sh, *.md, etc.)
  grep -RIn --exclude-dir={.git,target,build,node_modules,out} \
    -E 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["'\''])' .

  # 2. Legacy imports still in Java sources
  grep -RIn --include='*.java' -E '^\s*import\s+com\.microsoft\.azure\.' .

  # 3. Every pom.xml and *.gradle(.kts) file in the repo (not just the root reactor) — eyeball each for legacy coordinates
  find . -type d \( -name .git -o -name target -o -name build -o -name node_modules \) -prune -o \
    -type f \( -name 'pom.xml' -o -name '*.gradle' -o -name '*.gradle.kts' -o -name 'libs.versions.toml' \) -print

PowerShell equivalent (run from repo root):

  # 1. Legacy groupId / artifact references in ANY text file
  Get-ChildItem -Path . -Recurse -File |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["''])'

  # 2. Legacy imports still in Java sources
  Get-ChildItem -Path . -Recurse -File -Filter *.java |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern '^\s*import\s+com\.microsoft\.azure\.'

  # 3. Every pom.xml and *.gradle(.kts) file in the repo — eyeball each for legacy coordinates
  Get-ChildItem -Path . -Recurse -File -Include 'pom.xml','*.gradle','*.gradle.kts','libs.versions.toml' |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules)(\\|/)' } |
    Select-Object -ExpandProperty FullName

Pay special attention to files outside the root Maven/Gradle reactor— e.g. .ci/**/pom.xml, ci/**, buildSrc/, sample sub-modules, archetype resources — these are frequently missed because mvn dependency:tree on the root project never visits them.

If azure-sdk-bom is used, ensure NO explicit version dependencies for Azure libraries that are in azure-sdk-bom.

E.g. Instead of implementation 'com.azure.resourcemanager:azure-resourcemanager:2.60.0', we should use implementation 'com.azure.resourcemanager:azure-resourcemanager'. For Azure libraries in azure-sdk-bom, check https://raw.githubusercontent.com/Azure/azure-sdk-for-java/main/sdk/boms/azure-sdk-bom/pom.xml. The BOM version used during migration must be the latest stable version available at migration time and must not be below 1.3.0. If the BOM version is below 1.3.0 or missing, or individual Azure packages still have explicit versions that should be managed by the BOM, follow the appropriate section in BOM Migration Guide to fix it.

Version catalog projects: Follow the BOM Validation Checklist — it covers TOML, programmatic settings.gradle catalogs, and plain Gradle.
For each migration guide you recorded during migration:

Fetch and read the full content of the guide URL.
Identify the migrated source files that correspond to that guide's package.
Verify the migrated code follows the guide's recommended API replacements, class mappings, authentication patterns, and async/sync conventions.
Fix any deviations — do not just report them.

Package-Specific Migration Guides

Azure SDK Migration Guidelines

Context

Follow these steps:

  # Find every file referencing legacy groupIds/artifacts, including CI, samples, parent poms, buildSrc, version catalogs, Dockerfiles, and docs.
  grep -RIn --exclude-dir={.git,target,build,node_modules,out} \
    -E 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["'\''])' .

PowerShell equivalent (run from repo root):

  Get-ChildItem -Path . -Recurse -File |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["''])'

* Adopt supported SDKs: Replace the legacy dependencies with their modern equivalents in your pom.xml or build.gradle, following the migration guide to align feature parity and new SDK names.

* Test thoroughly: Run unit, integration, and end-to-end tests to validate that the modern SDKs behave as expected, focusing on authentication, retry, and serialization differences.

Migration Guide

Assumption

Project is Maven or Gradle.
Java code is on JDK 8 or above.

Migrate dependencies

Migrate Java Code

Make a list of source code/maven/gradle files that contains legacy SDK packages. Migrate each of them.
Determine legacy SDK artifacts according to previous files, find suitable migration guides in Package-Specific Migration Guides and follow the guides whenever possible. Record which migration guide URL you used for each legacy package (e.g., in your plan or commit messages), so you can validate against them later.
Do not change the Java package ...; declaration at the top of each source file, and do not rename or move the source file's directory path to match a new SDK package structure. Keep every .java file in its original directory; only update import statements and type usages inside the file body. For example, if a file lives in src/main/java/com/microsoft/azure/eventprocessorhosts/Consumer.java with package com.microsoft.azure.eventprocessorhosts;, it must stay in that exact directory and keep that exact package declaration — even though the modern SDK uses com.azure.messaging.eventhubs.
Do not upgrade JDK version, if it is already JDK 8 or above.
If there is test in the project, Java code there also need to be updated.

Package-Specific Source Code Guidelines (Add them to plan guidelines when generating plan)

Use these package-specific references:

Validation

Make sure

Migrated project pass compilation.
All tests pass. Don't silently skip tests.
No legacy SDK dependencies/references exist. This is a hard gate, not a self-assessment — you must prove it by running the commands below from the repo root and showing they return zero hits. Do not declare migration complete until all three return empty:

  # 1. Legacy groupId / artifact references in ANY text file (pom.xml, *.gradle, *.gradle.kts, libs.versions.toml, Dockerfile, *.sh, *.md, etc.)
  grep -RIn --exclude-dir={.git,target,build,node_modules,out} \
    -E 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["'\''])' .

  # 2. Legacy imports still in Java sources
  grep -RIn --include='*.java' -E '^\s*import\s+com\.microsoft\.azure\.' .

  # 3. Every pom.xml and *.gradle(.kts) file in the repo (not just the root reactor) — eyeball each for legacy coordinates
  find . -type d \( -name .git -o -name target -o -name build -o -name node_modules \) -prune -o \
    -type f \( -name 'pom.xml' -o -name '*.gradle' -o -name '*.gradle.kts' -o -name 'libs.versions.toml' \) -print

PowerShell equivalent (run from repo root):

  # 1. Legacy groupId / artifact references in ANY text file
  Get-ChildItem -Path . -Recurse -File |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern 'com\.microsoft\.azure(\.|:)|microsoft-azure-|azure-eventhubs-eph|azure-keyvault(:|["''])'

  # 2. Legacy imports still in Java sources
  Get-ChildItem -Path . -Recurse -File -Filter *.java |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules|out)(\\|/)' } |
    Select-String -Pattern '^\s*import\s+com\.microsoft\.azure\.'

  # 3. Every pom.xml and *.gradle(.kts) file in the repo — eyeball each for legacy coordinates
  Get-ChildItem -Path . -Recurse -File -Include 'pom.xml','*.gradle','*.gradle.kts','libs.versions.toml' |
    Where-Object { $_.FullName -notmatch '(\\|/)(\.git|target|build|node_modules)(\\|/)' } |
    Select-Object -ExpandProperty FullName

If azure-sdk-bom is used, ensure NO explicit version dependencies for Azure libraries that are in azure-sdk-bom.

Version catalog projects: Follow the BOM Validation Checklist — it covers TOML, programmatic settings.gradle catalogs, and plain Gradle.
For each migration guide you recorded during migration:

Fetch and read the full content of the guide URL.
Identify the migrated source files that correspond to that guide's package.
Verify the migrated code follows the guide's recommended API replacements, class mappings, authentication patterns, and async/sync conventions.
Fix any deviations — do not just report them.

Azure Upgrade

references/languages/java/INSTRUCTION.md

Azure SDK Migration Guidelines

Context

Migration Guide

Assumption

Migrate dependencies

Migrate Java Code

Package-Specific Source Code Guidelines (Add them to plan guidelines when generating plan)

Validation

Package-Specific Migration Guides

Preparing the source view

Azure Upgrade

references/languages/java/INSTRUCTION.md

Azure SDK Migration Guidelines

Context

Migration Guide

Assumption

Migrate dependencies

Migrate Java Code

Package-Specific Source Code Guidelines (Add them to plan guidelines when generating plan)

Validation

Package-Specific Migration Guides