Azure SDK for Java

April 23, 2026 · View on GitHub

This directory is the canonical documentation hub for the Azure SDK for Java repository. It is structured so that both humans and LLM/agent tooling can navigate directly to any topic.

Not sure where to start?

Using an Azure SDK library → see User Guides

Contributing code to this repo → see Contributor Guides

Understanding repo layout → see Repository Structure

Repository at a Glance

Item	Location
Root README (overview, packages, need help)	`/README.md`
Contributing rules & PR process	`/CONTRIBUTING.md`
Security policy	`/SECURITY.md`
Support channels	`/SUPPORT.md`
Code of Conduct	`/CODE_OF_CONDUCT.md`
Per-library documentation	`sdk/<service>/<library>/README.md`
Per-library changelog	`sdk/<service>/<library>/CHANGELOG.md`
Engineering tooling & pipelines	`/eng/`
GitHub Copilot agent instructions	`.github/copilot-instructions.md`

Getting Started

The fastest way to start is to find your service in the list of available packages and follow that library's README.md.

All client libraries:

Baseline on Java 8 and are tested up to the latest Java LTS release.
Follow the Azure SDK Design Guidelines for Java.
Share common infrastructure (retry, logging, authentication, tracing) from azure-core.

Add whatever library you need. Example for Azure Blob Storage:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
  <version>12.x.x</version>
</dependency>

Or use the Azure SDK BOM to manage versions automatically:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.2.x</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

See BOM Guidelines for details.

User Guides

For consumers of the Azure SDK for Java libraries:

Guide	Description
Frequently Asked Questions	Async gotchas, dependency conflicts, Security Manager
Azure Identity Examples	All credential types with code samples
Configuration	Environment variables, HTTP client tuning, retries
Logging	SLF4J setup, log levels, HTTP logging, filtering by package
Performance Tuning	SSL, connection pooling, async vs. sync
Test Proxy Migration	Migrate test recordings to the external assets repo
Azure JSON Migration	Replace Jackson with `azure-json` stream serialization
Serialization	`JacksonAdapter`, `JsonSerializer`, default config
Protocol Methods	Direct low-level HTTP access via `RequestOptions`
Management Libraries	Auth, sync/async calls, LROs for ARM libraries
Azure V2 — Logging & HTTP	`clientcore` logging best practices, OkHttp
Using the SDK with AI tools	Copilot, MCP server, Azure SDK skills, AI coding tools

Contributor Guides

For developers building or maintaining SDK libraries:

Guide	Description
Contributor Guide Index	Index of all contributor guides
Getting Started	Set up your dev environment (Java, Maven, Git, IDE)
Building	Build commands, skipping analysis, HTML reports
Unit Testing	Mocking, test parallelization, remote debugging
Live Testing	Deploy test resources and run live tests
Code Quality	CheckStyle, SpotBugs, Revapi, JaCoCo
Versioning	Version files, dependency tags, incrementing
Adding a Module	Create a new SDK module in the repo
TypeSpec Quickstart	End-to-end workflow: generate, build, test, release
Working with AutoRest	OpenAPI 2.0 / Swagger code generation
Writing Performance Tests	`perf-test-core` benchmarking framework
JavaDoc & Code Snippets	Javadoc standards + codesnippet plugin
Access Helpers	Cross-package internal access without public APIs
Deprecation Process	How to mark a library deprecated and release it
BOM Guidelines	Azure SDK BOM (bill of materials) guidelines
Release Checklist	Pre-release checklist from Beta 1 through GA
Credential Scan	Monitor and fix CredScan warnings
SDK Generation Pipeline Troubleshooting	Diagnose SDK auto-generation pipeline failures

Documentation Placement Decisions

See STRUCTURE.md for the full rationale on what lives here versus in eng/ or alongside individual SDK libraries.

Need Help?

Reference documentation: aka.ms/java-docs
Tutorials and quick starts: Azure for Java Developers
File a bug or feature request: GitHub Issues
Community Q&A: Stack Overflow azure-java-sdk tag
Commercial support: Azure Support

Documentation

The docs/ directory is the authoritative source for contributor and user documentation. Key topics previously on the GitHub Wiki have been migrated here.