Azure / Azure/azure-sdk-for-rust

Migration guide: `azure_core` (from azure_core ≤0.21.0 / azure_sdk_core)

Open
#4,230 0 comments 0 reactions 0 assignees View on GitHub
Azure.Core Docs rust
Dominant language
Rust
Stars
884
Forks
365
Avg merge
2d 19h
Merged PRs (30d)
112

Description

Part of #4228

## Migration guide: `azure_core`

### Official Crate

- **Name:** [`azure_core`](https://crates.io/crates/azure_core)
- **Current version:** 0.34.0
- **Service:** Core HTTP/retry/pipeline framework for all Azure SDK crates

### Unofficial Predecessor(s)

| Predecessor | Version(s) | Relationship | crates.io |
|---|---|---|---|
| `azure_core` v0.1.1–0.21.0 | Era 2 (Jan 2022 – Oct 2024) | **Same-crate older version** — major API rewrite at v0.22.0 (Feb 2025) | [crates.io](https://crates.io/crates/azure_core) |
| `azure_sdk_core` v0.43.7 | Era 1 (MindFlavor, 2017–2019) | **Different crate** — community-era core from [MindFlavor/AzureSDKForRust](https://github.com/MindFlavor/AzureSDKForRust), 90K downloads | [crates.io](https://crates.io/crates/azure_sdk_core) |

### Migration Guide Should Cover

- New pipeline model replacing the era 2 HTTP pipeline
- Redesigned `Pager` and `Poller` abstractions
- Pluggable async runtime support (no more hard Tokio dependency)
- Cloud configuration (`CloudConfig`) for sovereign clouds
- `SecretBytes` for credential handling
- HTTP logging with sanitization
- Sync response handling changes
- OpenTelemetry tracing macro integration
- Dependency version bumps and feature flag changes
- Migration path for `azure_sdk_core` users (start from scratch)

### Acceptance Criteria

- [ ] Migration guide published in repo docs (e.g., `docs/migration/azure_core.md`)
- [ ] Code samples for key scenarios: creating a custom pipeline policy, using Pager/Poller, configuring cloud endpoints
- [ ] FAQ section covering common migration pitfalls
- [ ] Linked from the `azure_core` crate README
- [ ] Reviewed by SDK team

Contributor guide

Open the contributing guide

Research direction

Start with the proposed docs/migration/azure_core.md and the azure_core crate README. Organize the listed migration topics, code samples, and FAQ around the acceptance criteria, then link the guide from the README and obtain SDK team review.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.