Azure SDK for .NET: the monorepo behind the Azure client and management libraries

What azure-sdk-for-net actually is, and who it is for

The name invites a wrong assumption. There is no single Azure SDK for .NET package. The repository describes itself as being for active development of the Azure SDK for .NET, and it tells consumers of the SDK to visit the public developer docs or the versioned developer docs instead. So the primary audience of this repository is people working on the libraries, and the secondary audience is people who want to read the source, the samples, or the per-library README files. If you are an application developer looking for a download, the README's own direction is to a library folder, not to a root artifact.

The libraries themselves are grouped by service under the /sdk directory. That layout matters more than it first appears: the root README does not document how to call Blob Storage or Key Vault. It says that to get started with a library you should see the README.md file located in that library's project folder. The root document is an index and a policy statement, not a tutorial. Anyone who reads only it will come away knowing the categories and the naming conventions, and nothing about the API surface.

The Azure.* and Microsoft.Azure.* split decides which library you get

The README divides packages into four categories: client new releases, client previous versions, management new releases, and management previous versions. The naming is the tell. New client libraries start with Azure, followed by the service category, then the service name, as in Azure.Storage.Blobs. New management libraries use namespaces starting with Azure.ResourceManager, as in Azure.ResourceManager.Network. The older generations carry Microsoft.Azure in their names, for example Microsoft.Azure.KeyVault for clients and Microsoft.Azure.Management.Network for management.

The trade-off is stated plainly. The new libraries follow the Azure SDK Design Guidelines for .NET and share core features such as HTTP retries, logging, transport protocols and authentication protocols, so learning those features once carries across client libraries. The older libraries might not implement the guidelines or have the same feature set, but they offer wider coverage of services. That is a real decision, not a formality: a service you need may exist only in the older generation, and a service you already use may behave differently after a migration because the shared pipeline is new.

The shared behaviour lives in Azure.Core, and the README points to that project's README for the details. This is the strongest structural argument for the new generation. Retry policy, logging and credential handling are not reimplemented per service, so a bug fix or a behaviour change in the pipeline propagates. The cost is that you inherit the pipeline's defaults, including telemetry, whether or not you thought about it.

Installing Azure SDK for .NET: NuGet packages, not the repository

You do not install azure-sdk-for-net. You install the individual library. The README points to the latest available packages page for the complete list, and the related search terms people use (azure sdk for net nuget, azure sdk for .net download) reflect the confusion the naming creates. The practical route is NuGet with the library's package name, which matches its namespace, for example Azure.Storage.Blobs or Azure.ResourceManager.Network.

Once the package is referenced, the shape of a client is consistent across the new generation: an endpoint, a TokenCredential, and an options object. The README's telemetry example shows exactly this construction, and it is the clearest short illustration of the pattern in the repository root.

Uri serviceEndpoint = new Uri("https://example.contoso.com");
TokenCredential credential = new DefaultAzureCredential();

SampleClientOptions clientOptions = new SampleClientOptions()
{
    Diagnostics = { IsTelemetryEnabled = false }
};

SampleClient client = new SampleClient(serviceEndpoint, credential, clientOptions);

That block is quoted from the README's telemetry section, with SampleClient standing in for a real client. What you should take from it is the three-argument constructor and the nested Diagnostics property, since those recur across the new client libraries. For a real service, replace the sample types with the ones from the library folder you chose.

If you are working with the management libraries instead, the README directs you to a separate quickstart guide in the repository at doc/mgmt_preview_quickstart.md. That is a different entry point from the client libraries, and it is worth reading before you assume the client pattern carries over unchanged. The repository also ships samples under samples/, with subfolders for eventhubs, keyvault, servicebus, voicelive and agentserver, which is a faster way to see a working call than reading generated API reference.

Telemetry is on by default and the opt-out is two different switches

The README states that telemetry collection is on by default and that the software may collect information about you and your use of the software and send it to Microsoft. That is a design decision with consequences for anyone in a regulated environment, and the documentation does not soften it.

There are two opt-outs. Per client, set IsTelemetryEnabled to false in the diagnostics options, as in the code above. Globally, set the AZURE_TELEMETRY_DISABLED environment variable to true before creating any clients. The ordering in that second sentence is load-bearing: the README says to set it before creating any clients, so a process that reads the variable after a client is constructed should not expect the setting to apply.

The README also draws a boundary that is easy to misread. It notes that HttpClient may set default user agent headers as part of .NET platform behavior, and that this value does not contain any Azure SDK telemetry information. So a user agent string in your outbound traffic is not evidence that SDK telemetry is enabled, and disabling the SDK switch will not remove it. For more detail the README points to the Telemetry Guidelines page rather than reproducing the data categories itself.

Preview packages and the production warning

The README repeats a warning in two places: if you need to ensure your code is ready for production, use one of the stable, non-preview libraries. The management section says the same thing about the new Azure.ResourceManager generation, which it describes as being in Public Preview.

The recent release list shows what that means in practice. Azure.ResourceManager.Network has 1.18.0-beta.1 and an alpha build dated 2026-09-20, and Azure.Messaging.WebPubSub.Chat has 1.0.0-beta.1. Those are the packages a reader might pull without noticing the suffix. A beta or alpha version string in NuGet is the signal, and the README's advice is unambiguous about what to do with it.

The repository itself is not archived, and its last push was on 2026-09-22. That tells you the source tree is moving. It does not tell you that the specific library you depend on is stable, and the two questions are separate. A busy repository can still publish a preview of the one package you need.

Where azure-sdk-for-net is the wrong choice

The clearest failure mode is treating this repository as an installable product. The README's first instruction to consumers is to go elsewhere for documentation, and there is no root package, no root installer, and no root version. A team that adds azure-sdk-for-net as a dependency has added nothing usable.

The second case is source-level contribution. The top-level entries include build.proj, Directory.Build.props, Directory.Build.targets, global.json, eng/, common/ and a package.json pinned to autorest ^3.7.1, alongside CONTRIBUTING.md and AGENTS.md. That is a build system for a large multi-service monorepo, and it exists to regenerate and ship libraries. If your goal is to call Azure APIs from an application, none of it is on your path, and cloning the repository to read a library's README is a heavier route than opening the library folder on GitHub.

The third case is expecting one consistent API across every Azure service. The README explicitly allows that older libraries offer wider coverage while possibly not implementing the guidelines or matching the newer feature set. If your workload spans a service with a modern Azure.* client and one that only has a Microsoft.Azure.* client, you will write two styles of code in one solution, and the shared retry and authentication behaviour will apply to only one of them.

How this compares with generating your own client from the service specification

The repository's package.json depends on autorest ^3.7.1, and there is a swagger_to_sdk_config.json at the top level. That is the alternative worth naming: generating a client from an OpenAPI or Swagger specification yourself, using the same generator family the SDK build uses.

The difference is in who owns the result. A generated client gives you exactly the operations in the specification you fed it, with no Azure.Core pipeline underneath unless you add one, and no shared credential, retry or logging behaviour that you did not write. The Azure SDK libraries give you that pipeline and the guideline-conformant surface, at the cost of accepting the library's release cadence, its preview or stable status, and its telemetry default. If you need a service or an API version the shipped library does not cover, generation is the route the repository's own tooling implies. If you need retries, credential handling and tracing to behave the same way across several services, hand-generating each client means building that layer yourself.

Licence, upgrade cost and what to check before adopting

The repository is MIT licensed, with LICENSE.txt and NOTICE.txt at the top level. MIT is permissive, so the licence itself is unlikely to be the blocker for most teams. The parts that deserve a closer look are the ones the licence does not cover: the telemetry described in the README, and the separate terms attached to the Azure services the libraries call. This is a description of what the repository states, not legal advice, and anyone with compliance requirements should read LICENSE.txt and NOTICE.txt directly rather than rely on a summary.

Upgrade cost is not uniform, because the repository ships many independently versioned packages. The release list shows Azure.ResourceManager.Network at 1.18.0-beta.1 alongside a dated alpha, and Azure.Messaging.WebPubSub.Chat at 1.0.0-beta.1. Each library moves on its own schedule, so a solution referencing several of them accumulates several upgrade paths, and the preview ones can change before they stabilize. The README's guidance to prefer stable, non-preview libraries is also the cheapest upgrade strategy: it removes the packages most likely to break between releases.

Editorial conclusion

Adopt it when you are building .NET code against Azure services and want the guideline-conformant Azure.* client and Azure.ResourceManager.* management libraries, and check the README.md inside the specific library folder under /sdk before writing code, because that file, not the root README, carries the usage details. Do not adopt it if you expected a single installable SDK: there is no such package, and the root README points consumers to the public developer docs instead. Verify two things first: whether the library you picked is stable or preview, since the README states that production code should use a stable, non-preview library, and whether you need the Azure.* generation or the older Microsoft.Azure.* one, because the two differ in feature set and guideline conformance.

Frequently asked questions

Official sources

1. Azure/azure-sdk-for-net on GitHub
2. Issues
3. License: MIT
4. README
5. Releases