.NET Azure SDK Design Guidelines

Introduction

The following document describes .NET specific guidelines for designing Azure SDK client libraries. These guidelines complement general .NET Framework Design Guidelines with design considerations specific to the Azure SDK. These guidelines also expand on and simplify language-independent General Azure SDK Guidelines. More specific guidelines take precedence over more general guidelines.

Throughout this document, we’ll use the client library for the Azure Application Configuration service to illustrate various design concepts.

Design Principles

The main value of the Azure SDK is productivity building applications with Azure services. Other qualities, such as completeness, extensibility, and performance are important but secondary. We ensure our customers can be highly productive when using our libraries by ensuring these libraries are:

Idiomatic

• Azure SDK libraries follow .NET Framework Design Guidelines.
• Azure SDK libraries feel like designed by the designers of the .NET Standard libraries.
• Azure SDK libraries version just like the .NET Standard libraries.

We are not trying to fix bad parts of the language ecosystem; we embrace the ecosystem with its strengths and its flaws.

Consistent

• The Azure SDK feels like a single product of a single team, not a set of unrelated NuGet packages.
• Users learn common concepts once; apply the knowledge across all SDK components.
• All differences from the guidelines must have good reasons.

Approachable

• Small number of steps to get started; power knobs for advanced users
• Small number of concepts; small number of types; small number of members
• Approachable by our users, not only by engineers designing the SDK components
• Easy to find great getting started guides and samples
• Easy to acquire

Dependable

• 100% backward compatible
• Great logging, tracing, and error messages
• Predictable support lifecycle, feature coverage, and quality

General Guidelines

✅ DO follow the official .NET Framework Design Guidelines.

At the end of this document, you can find a section with the most commonly overlooked guidelines in existing Azure SDK libraries.

✅ DO follow the General Azure SDK Guidelines.

The guidelines provide a robust methodology for communicating with Azure services. The easiest way to ensure that your component meets these requirements is to use the Azure.Core package to call Azure services. Details of these helper APIs and their usage are described in the Using HttpPipeline section.

✅ DO use HttpPipeline to implement all methods that call Azure REST services.

The pipeline can be found in the Azure.Core package, and it takes care of many General Azure SDK Guidelines. Details of the pipeline design and usage are described in section Using HttpPipeline below. If you can’t use the pipeline, you must implement all the general requirements of Azure SDK manually.

Support for non-HTTP Protocols

This document contains guidelines developed primarily for typical Azure REST services, i.e. stateless services with request-response based interaction model. Many of the guidelines in this document are more broadly applicable, but some might be specific to such REST services.

Azure SDK API Design

Azure services will be exposed to .NET developers as one or more service client types and a set of supporting types.

The Service Client

Service clients are the main starting points for developers calling Azure services with the Azure SDK. Each client library should have at least one client in its main namespace, so it’s easy to discover. The guidelines in this section describe patterns for the design of a service client.

A service client should have the same shape as this code snippet:

namespace Azure.<group>.<service_name> {

    // main service client class
    public class <service_name>Client {

        // simple constructors; don't use default parameters
        public <service_name>Client(<simple_binding_parameters>);
        public <service_name>Client(<simple_binding_parameters>, <service_name>ClientOptions options);

        // 0 or more advanced constructors
        public <service_name>Client(<advanced_binding_parameters>, <service_name>ClientOptions options = default);

        // mocking constructor
        protected <service_name>Client();

        // service methods (synchronous and asynchronous)
        public virtual Task<Response<<model>> <service_operation>Async(<parameters>, CancellationToken cancellationToken = default);
        public virtual Response<model> <service_operation>(<parameters>, CancellationToken cancellationToken = default);

        // other members
    }

    // options for configuring the client
    public class <service_name>ClientOptions : ClientOptions {

    }
}

For example, the Application Configuration Service client looks like this code snippet:

namespace Azure.Data.Configuration {

    public class ConfigurationClient {

        public ConfigurationClient(string connectionString);
        public ConfigurationClient(string connectionString, ConfigurationClientOptions options);

        protected ConfigurationClient(); // for mocking

        public virtual Task<Response<<ConfigurationSetting>> GetConfigurationSettingAsync(string key, CancellationToken cancellationToken = default);
        public virtual Response<ConfigurationSetting> GetConfigurationSetting(string key, CancellationToken cancellationToken = default);

        // other members
        …
    }

    // options for configuring the client
    public class ConfigurationClientOptions : ClientOptions {
        ...
    }
}

You can find the full sources of here.

✅ DO name service client types with the Client suffix.

For example, the service client for the Application Configuration service is called ConfigurationClient.

✅ DO place at least one service client in the root namespace of their corresponding component.

✅ DO make service clients classes (reference types), not structs (value types).

✅ DO make service clients immutable.

Client instances are often shared between threads (stored in application statics) and it should be difficult, if not impossible, for one of these threads to affect others.

✅ DO see Namespace Naming guidelines for how to choose the namespace for the client types.

Client Hierarchies

Some Azure services store and manipulate resources organized in a hierarchy. For example, Azure Storage provides an account that contains zero or more containers, which in turn contain zero or more blobs. SDK libraries for such services might want to provide more than one client type representing various levels of the hierarchy. For example, the storage library provides BlobServiceClient, BlobContainerClient, and BlobClient.

✔️ YOU MAY provide a client type corresponding to each level in a resource hierarchy.

✅ DO provide a <parent>.Get<child>Client(...) method to retrieve a client for the named child.

For example, BlobContainerClient has a method GetBlobClient returning an instance of BlobClient. The method must not make a network call to verify the existence of the child. Also, note that per general client constructor guidelines, all clients need to provide at least one public constructor.

✔️ YOU MAY provide method <parent>.Create<child>(...) that creates a child resource.

The method should return an instance of a client for the newly created child resource.

✔️ YOU MAY provide method <parent>.Delete<child>(...) that deletes a child resource.

Service Client Constructors

✅ DO provide a minimal constructor that takes only the parameters required to connect to the service.

For example, you may use a connection string, or host name and authentication. It should be easy to start using the client without extensive customization.

public class ConfigurationClient {
    public ConfigurationClient(string connectionString);
}

⛔️ DO NOT use default parameters in the simplest constructor.

✅ DO provide constructor overloads that allow specifying additional options such as credentials, a custom HTTP pipeline, or advanced configuration.

Custom pipeline and client-specific configuration are represented by an options parameter. The type of the parameter is typically a subclass of ClientOptions type, shown below.

Using ClientOptions

✅ DO name subclasses of ClientOptions by adding Options suffix to the name of the client type the options subclass is configuring.

// options for configuring ConfigurationClient
public class ConfigurationClientOptions : ClientOptions {
    ...
}

public class ConfigurationClient {

    public ConfigurationClient(string connectionString, ConfigurationClientOptions options);
    ...
}

If the options type can be shared by multiple client types, name it with a plural or more general name. For example, the BlobClientsOptions class can be used by BlobClient, BlobContainerClient, and BlobAccountClient.

⛔️ DO NOT have a default constructor on the options type.

Each overload constructor should take at least version parameter to specify the service version. See Versioning guidelines for details.

For example, the ConfigurationClient type and its public constructors look as follows:

public class ConfigurationClient {
    public ConfigurationClient(string connectionString);
    public ConfigurationClient(string connectionString, ConfigurationClientOptions options);
    public ConfigurationClient(Uri uri, TokenCredential credential, ConfigurationClientOptions options = default);
}

Service Versions

✅ DO call the highest supported service API version by default.

✅ DO allow the consumer to explicitly select a supported service API version when instantiating the service client.

Use a constructor parameter called version on the client options type.

• The version parameter must be the first parameter to all constructor overloads.
• The version parameter must be required, and default to the latest supported service version.
• The type of the version parameter must be ServiceVersion; an enum nested in the options type.
• The ServiceVersion enum must use explicit values starting from 1.
• ServiceVersion enum value 0 is reserved. When 0 is passed into APIs, ArgumentException should be thrown.

For example, the following is a code snippet from the ConfigurationClientOptions:

public class ConfigurationClientOptions : ClientOptions {

    public ConfigurationClientOptions(ServiceVersion version = ServiceVersion.V2019_05_09) {
        if (version == default)
            throw new ArgumentException($"The service version {version} is not supported by this library.");
        }
    }

    public enum ServiceVersion {
        V2019_05_09 = 1,
    }
    ...
}

⛔️ DO NOT force consumers to test service API versions to check support for a feature. Use the tester-doer .NET pattern to implement feature flags, or use Nullable<T>.

For example, if the client library supports two service versions, only one of which can return batches, the consumer might write the following code:

if (client.CanBatch) {
    Response<SettingBatch> response = await client.GetBatch("some_key*");
    Guid? Guid = response.Result.Guid;
} else {
    Response<ConfigurationSetting> response1 = await client.GetAsync("some_key1");
    Response<ConfigurationSetting> response2 = await client.GetAsync("some_key2");
    Response<ConfigurationSetting> response3 = await client.GetAsync("some_key3");
}

Mocking

✅ DO provide protected parameterless constructor for mocking.

public class ConfigurationClient {
    protected ConfigurationClient();
}

⛔️ DO NOT reference virtual properties of the client class as parameters to other methods or constructors within the client constructor. This violates the .NET Framework Constructor Design because a field to which a virtual property refers may not be initialized yet, or a mocked virtual property may not be set up yet. Use parameters or local variables instead:

public class ConfigurationClient {
    private readonly ConfigurationRestClient _client;
    public ConfigurationClient(string connectionString) {
        ConnectionString = connectionString;
        // Use parameter below instead of the class-defined virtual property.
        _client = new ConfigurationRestClient(connectionString);
    }
    public virtual string ConnectionString { get; }
}

In mocks, using the virtual property instead of the parameter requires the property to be mocked to return the value before the constructor is called when the mock is created. In Moq this requires using the delegate parameter to create the mock, which may not be an obvious workaround.

See Support for Mocking for details.

Service Methods

Service methods are the methods on the client that invoke operations on the service.

Here are the main service methods in the ConfigurationClient. They meet all the guidelines that are discussed below.

public class ConfigurationClient {

    public virtual Task<Response<ConfigurationSetting>> AddAsync(ConfigurationSetting setting, CancellationToken cancellationToken = default);
    public virtual Response<ConfigurationSetting> Add(ConfigurationSetting setting, CancellationToken cancellationToken = default);

    public virtual Task<Response<ConfigurationSetting>> SetAsync(ConfigurationSetting setting, CancellationToken cancellationToken = default);
    public virtual Response<ConfigurationSetting> Set(ConfigurationSetting setting, CancellationToken cancellationToken = default);

    public virtual Task<Response<ConfigurationSetting>> GetAsync(string key, SettingFilter filter = default, CancellationToken cancellationToken = default);
    public virtual Response<ConfigurationSetting> Get(string key, SettingFilter filter = default, CancellationToken cancellationToken = default);

    public virtual Task<Response<ConfigurationSetting>> DeleteAsync(string key, SettingFilter filter = default, CancellationToken cancellationToken = default);
    public virtual Response<ConfigurationSetting> Delete(string key, SettingFilter filter = default, CancellationToken cancellationToken = default);
}

Sync and Async

✅ DO provide both asynchronous and synchronous variants for all service methods.

Many developers want to port existing applications to the Cloud. These applications are often synchronous, and the cost of rewriting them to be asynchronous is usually prohibitive. Calling asynchronous APIs from synchronous methods can only be done through a technique called sync-over-async, which can cause deadlocks. The Azure SDK provides synchronous APIs to minimize friction when porting existing application to Azure.

✅ DO ensure that the names of the asynchronous and the synchronous variants differ only by the Async suffix.

Naming

Most methods in Azure SDK libraries should be named following the typical .NET method naming conventions. The Azure SDK Design Guidelines add special conventions for methods that access and manipulate server resources.

☑️ YOU SHOULD use standard verbs for methods that access or manipulate server resources.

Cancellation

✅ DO ensure all service methods, both asynchronous and synchronous, take an optional CancellationToken parameter called cancellationToken.

The token should be further passed to all calls that take a cancellation token. DO NOT check the token manually, except when running a significant amount of CPU-bound work within the library, e.g. a loop that can take more than a typical network call.

Mocking

✅ DO make service methods virtual.

Virtual methods are used to support mocking. See Support for Mocking for details.

Return Types

✅ DO return Response<T> or Response from synchronous methods.

T represents the content of the response, as described below.

✅ DO return Task<Response<T>> or Task<Response> from asynchronous methods that make network requests.

There are two possible return types from asynchronous methods: Task and ValueTask. Your code will be doing a network request in the majority of cases. The Task variant is more appropriate for this use case. For more information, see this blog post.

T represents the content of the response, as described below.

The T can be either an unstructured payload (e.g. bytes of a storage blob) or a model type representing deserialized response content.

✅ DO use one of the following return types to represent an unstructured payload:

• System.IO.Stream - for large payloads
• byte[] - for small payloads
• ReadOnlyMemory<byte> - for slices of small payloads

✅ DO return a model type if the content has a schema and can be deserialized.

For more information, see Model Types

Thread Safety

✅ DO be thread-safe. All public members of the client type must be safe to call from multiple threads concurrently.

Service Method Parameters

Service methods fall into two main groups when it comes to the number and complexity of parameters they accept:

• Service Methods with Simple Inputs, simple methods for short
• Service Methods with Complex Inputs, complex methods for short

Simple methods are methods that take up to six parameters, with most of the parameters being simple BCL primitives. Complex methods are methods that take large number of parameters and typically correspond to REST APIs with complex request payloads.

Simple methods should follow standard .NET Framework Design Guidelines for parameter list and overload design.

Complex methods should use option parameter to represent the request payload, and consider providing convenience simple overloads for most common scenarios.

public class BlobContainerClient {

    // simple service method
    public virtual Response<BlobInfo> UploadBlob(string blobName, Stream content, CancellationToken cancellationToken = default);

    // complex service method
    public virtual Response<BlobInfo> CreateBlob(BlobCreateOptions options = null, CancellationToken cancellationToken = default);

    // convinience overload[s]
    public virtual Response<BlobContainerInfo> CreateBlob(string blobName, CancellationToken cancellationToken = default);
}

public class BlobCreateOptions {
    public PublicAccessType Access { get; set; }
    public IDictionary<string, string> Metadata { get; }
    public BlobContainerEncryptionScopeOptions Encryption { get; set; }
    ...
}

The Options class is designed similarly to .NET custom attributes, where required service method parameters are modeled as Options class constructor parameters and get-only properties, and optional parameters are get-set properties.

✅ DO use the options parameter pattern for complex service methods.

✔️ YOU MAY use the options parameter pattern for simple service methods that you expect to grow in the future.

✔️ YOU MAY add simple overloads of methods using the options parameter pattern.

If in common scenarios, users are likely to pass just a small subset of what the options parameter represents, consider adding an overload with a parameter list representing just this subset.

    // main overload taking the options property bag
    public virtual Response<BlobInfo> CreateBlob(BlobCreateOptions options = null, CancellationToken cancellationToken = default);

    // simple overload with a subset of parameters of the options bag
    public virtual Response<BlobContainerInfo> CreateBlob(string blobName, CancellationToken cancellationToken = default);
}

✔️ YOU MAY name the option parameter type with the ‘Options’ suffix.

Parameter Validation

Service methods take two kinds of parameters: service parameters and client parameters. Service parameters are directly passed across the wire to the service. Client parameters are used within the client library and aren’t passed directly to the service.

✅ DO validate client parameters.

⛔️ DO NOT validate service parameters.

Common parameter validations include null checks, empty string checks, and range checks. Let the service validate its parameters.

✅ DO test the developer experience when invalid service parameters are passed in. Ensure clear error messages are generated by the client. If the developer experience is inadequate, work with the service team to correct the problem.

Methods Returning Collections (Paging)

Many Azure REST APIs return collections of data in batches or pages. A client library will expose such APIs as special enumerable types Pageable<T> or AsyncPageable<T>. These types are located in the Azure.Core package.

For example, the configuration service returns collections of items as follows:

public class ConfigurationClient {

    // asynchronous API returning a collection of items
    public virtual AsyncPageable<Response<ConfigurationSetting>> GetConfigurationSettingsAsync(...);

    // synchronous variant of the method above
    public virtual Pageable<ConfigurationSetting> GetConfigurationSettings(...);
    ...
}

✅ DO return Pageable<T> or AsyncPageable<T> from service methods that return a collection of items.

Methods Invoking Long Running Operations

Some service operations, known as Long Running Operations or LROs take a long time (up to hours or days). Such operations do not return their result immediately, but rather are started, their progress is polled, and finally the result of the operation is retrieved.

Azure.Core library exposes an abstract type called Operation<T>, which represents such LROs and supports operations for polling and waiting for status changes, and retrieving the final operation result. A service method invoking a long running operation will return a subclass of Operation<T>, as shown below.

// the following type is located in Azure.Core
public abstract class Operation<T> {

    public abstract bool HasCompleted { get; }
    public abstract bool HasValue { get; }

    public abstract string Id { get; }

    public abstract T Value { get; } // throws if CachedStatus != Succeeded
    public abstract Response GetRawResponse();

    public abstract Response UpdateStatus(CancellationToken cancellationToken = default);
    public abstract ValueTask<Response> UpdateStatusAsync(CancellationToken cancellationToken = default);

    public abstract ValueTask<Response<T>> WaitForCompletionAsync(CancellationToken cancellationToken = default);
    public abstract ValueTask<Response<T>> WaitForCompletionAsync(TimeSpan pollingInterval, CancellationToken cancellationToken);
}

Client libraries need to inherit from Operation<T> not only to implement all abstract members, but also to provide a constructor required to access an existing LRO (an LRO initiated by a different process).

public class CopyFromUriOperation : Operation<long> {
    public CopyFromUriOperation(string id, BlobBaseClient client);
    ...
}

public class BlobBaseClient {

    public virtual CopyFromUriOperation StartCopyFromUri(..., CancellationToken cancellationToken = default);
    public virtual Task<CopyFromUriOperation> StartCopyFromUriAsync(..., CancellationToken cancellationToken = default);
}

The following code snippet shows how an SDK consumer would use the Operation to poll for a response.

BlobBaseClient client = ...

// automatic polling
{
    var value = await client.StartCopyFromUri(...).WaitForCompletionAsync();
    Console.WriteLine(value);
}

// manual polling
{
    CopyFromUriOperation operation = await client.StartCopyFromUriAsync(...);
    while (true)
    {
        await client.UpdateStatusAsync();
        if (client.HasCompleted) break;
        await Task.Delay(1000); // play some elevator music
    }
    if (operation.HasValue) Console.WriteLine(operation.Value);
}

// saving operation ID
{
    CopyFromUriOperation operation = await client.StartCopyFromUriAsync(...);
    string operationId = operation.Id;

    // two days later
    var operation2 = new CopyFromUriOperation(operationId, client);
    var value = await operation2.WaitForCompletionAsync();
}

✅ DO name all methods that start an LRO with the Start prefix.

✅ DO return a subclass of Operation<T> from LRO methods.

✔️ YOU MAY add additional APIs to subclasses of Operation<T>. For example, some subclasses add a constructor allowing to create an operation instance from a previously saved operation ID. Also, some subclasses are more granular states besides the IsCompleted and HasValue states that are present on the base class.

✅ DO provide protected parameterless constructor for mocking in subclasses of Operation<T>.

public class CopyFromUriOperation {
    protected CopyFromUriOperation();
}

✅ DO make all properties virtual to allow mocking.

public class CopyFromUriOperation {
    public virtual Uri SourceUri { get; }
}

Conditional Request Methods

Some services support conditional requests that are used to implement optimistic concurrency control. In Azure, optimistic concurency is typically implemented using If-Match headers and ETags. See Managing Concurrency in Blob Storage as a good example.

✅ DO use Azure.Core ETag to represent ETags.

✔️ YOU MAY take MatchConditions, RequestConditions, (or a custom subclass) as a parameter to conditional service call methods.

TODO: more guidelines comming. see https://github.com/Azure/azure-sdk/issues/2154

Supporting Types

In addition to service client types, Azure SDK APIs provide and use other supporting types as well.

Model Types

This section describes guidelines for the design model types and all their transitive closure of public dependencies (i.e. the model graph). A model type is a representation of a REST service’s resource.

For example, review the configuration service model type below:

public sealed class ConfigurationSetting : IEquatable<ConfigurationSetting> {

    public ConfigurationSetting(string key, string value, string label = default);

    public string ContentType { get; set; }
    public string ETag { get; internal set; }
    public string Key { get; set; }
    public string Label { get; set; }
    public DateTimeOffset LastModified { get; internal set; }
    public bool Locked { get; internal set; }
    public IDictionary<string, string> Tags { get; }
    public string Value { get; set; }

    public bool Equals(ConfigurationSetting other);

    [EditorBrowsable(EditorBrowsableState.Never)]
    public override bool Equals(object obj);
    [EditorBrowsable(EditorBrowsableState.Never)]
    public override int GetHashCode();
    [EditorBrowsable(EditorBrowsableState.Never)]
    public override string ToString();
}

This model is returned from service methods as follows:

public class ConfigurationClient {
    public virtual Task<Response<ConfigurationSetting>> GetAsync(...);
    public virtual Response<ConfigurationSetting> Get(...);
    ...
}

✅ DO ensure model public properties are get-only if they aren’t intended to be changed by the user.

Most output-only models can be fully read-only. Models that are used as both outputs and inputs (i.e. received from and sent to the service) typically have a mixture of read-only and read-write properties.

For example, the Locked property of ConfigurationSetting is controlled by the service. It shouldn’t be changed by the user. The ContentType property, by contrast, can be modified by the user.

public sealed class ConfigurationSetting : IEquatable<ConfigurationSetting> {

    public string ContentType { get; set; }

    public bool Locked { get; internal set; }
}

Ensure you include an internal setter to allow for deserialization. For more information, see JSON Serialization.

✅ DO ensure model types are structs, if they meet the criteria for being structs.

Good candidates for struct are types that are small and immutable, especially if they are often stored in arrays. See .NET Framework Design Guidelines for details.

☑️ YOU SHOULD implement basic data type interfaces on model types, per .NET Framework Design Guidelines.

For example, implement IEquatable<T>, IComparable<T>, IEnumerable<T>, etc. if applicable.

☑️ YOU SHOULD use the following collection types for properties of model types:

• IReadOnlyList<T> and IList<T> for most collections
• IReadOnlyDictionary<T> and IDictionary<T> for lookup tables
• T[], Memory<T>, and ReadOnlyMemory<T> when low allocations and performance are critical

Note that this guidance does not apply to input parameters. Input parameters representing collections should follow standard .NET Framework Design Guidelines, e.g. use IEnumerable<T> is allowed. Also, this guidance does not apply to return types of service method calls. These should be using Pageable<T> and AsyncPageable<T> discussed in Methods Returning Collections.

✔️ YOU MAY place output model types in .Models subnamespace to avoid cluttering the main namespace with too many types.

It is important for the main namespace of a client library to be clutter free. Some client libraries have a relatively small number of model types, and these should keep the model types in the main namespace. For example, model types of Azure.Data.AppConfiguration package are in the main namespace. On the other hand, model types of Azure.Storage.Blobs package are in .Models subnamespace.

namespace Azure.Storage.Blobs {
    public class BlobClient { ... }
    public class BlobClientOptions { ... }
    ...
}
namespace Azure.Storage.Blobs.Models {
    ...
    public class BlobContainerItem { ... }
    public class BlobContainerProperties { ...}
    ...
}

☑️ YOU SHOULD apply the [EditorBrowsable(EditorBrowsableState.Never)] attribute to methods on the model type that the user isn’t meant to call.

Adding this attribute will hide the methods from being shown with IntelliSense. A user will almost never call GetHashCode() directly. Equals(object) is almost never called if the type implements IEquatable<T> (which is preferred). Hide the ToString() method if it isn’t overridden.

public sealed class ConfigurationSetting : IEquatable<ConfigurationSetting> {
    [EditorBrowsable(EditorBrowsableState.Never)]
    public override bool Equals(object obj);
    [EditorBrowsable(EditorBrowsableState.Never)]
    public override int GetHashCode();
}

✅ DO ensure all model types can be used in mocks.

In practice, you need to provide public APIs to construct model graphs. See Support for Mocking for details.

Model Type Naming

TODO: issue #2298

Enumerations

✅ DO use an enum for parameters, properties, and return types when values are known.

✔️ YOU MAY use a readonly struct in place of an enum that declares well-known fields but can contain unknown values returned from the service, or user-defined values passed to the service.

See enumeration-like structure documentation for implementation details.

Using Azure Core Types

The Azure.Core package provides common functionality for client libraries. Documentation and usage examples can be found in the azure/azure-sdk-for-net repository.

Using Primitive Types

✅ DO use Azure.ETag to represent ETags.

The Azure.ETag type is located in Azure.Core package.

✅ DO use System.Uri to represent URIs.

Exceptions

In .NET, throwing exceptions is how we communicate to library consumers that the services returned an error.

✅ DO throw RequestFailedException or its subtype when a service method fails with non-success status code.

The exception is available in Azure.Core package:

public class RequestFailedException : Exception {

    public RequestFailedException(int status, string message);
    public RequestFailedException(int status, string message, Exception innerException);

    public int Status { get; }
}

☑️ YOU SHOULD use ResponseExceptionExtensions to create RequestFailedException instances.

The exception message should contain detailed response information. For example:

if (response.Status != 200) {
    throw await response.CreateRequestFailedExceptionAsync(message);
}

✅ DO use RequestFailedException or one of its subtypes where possible.

Don’t introduce new exception types unless there’s a programmatic scenario for handling the new exception that’s different than RequestFailedException

Authentication

The client library consumer should construct a service client using just the constructor. After construction, service methods can successfully invoke service operations. The constructor parameters must take all parameters required to create a functioning client, including all information needed to authenticate with the service.

The general constructor pattern refers to binding parameters.

// simple constructors
public <service_name>Client(<simple_binding_parameters>);
public <service_name>Client(<simple_binding_parameters>, <service_name>ClientOptions options);

// 0 or more advanced constructors
public <service_name>Client(<advanced_binding_parameters>, <service_name>ClientOptions options = default);

Typically, binding parameters would include a URI to the service endpoint and authorization credentials. For example, the blob service client can be bound using any of:

• a connection string (which contains both endpoint information and credentials),
• an endpoint (for anonymous access),
• an endpoint and credentials (for authenticated access).

// hello world constructors using the main authentication method on the service's Azure Portal (typically a connection string)
// we don't want to use default parameters here; all other overloads can use default parameters
public BlobServiceClient(string connectionString)
public BlobServiceClient(string connectionString, BlobClientOptions options)

// anonymous access
public BlobServiceClient(Uri uri, BlobClientOptions options = default)

// using credential types
public BlobServiceClient(Uri uri, StorageSharedKeyCredential credential, BlobClientOptions options = default)
public BlobServiceClient(Uri uri, TokenCredential credential, BlobClientOptions options = default)

☑️ YOU SHOULD use credential types provided in the Azure.Core package.

Currently, Azure.Core provides TokenCredential for OAuth style tokens, including MSI credentials.

✅ DO support changing credentials without having to create a new client instance.

Credentials passed to the constructors must be read before every request (for example, by calling TokenCredential.GetToken()).

✅ DO contact adparch if you want to add a new credential type.

✔️ YOU MAY offer a way to create credentials from a connection string only if the service offers a connection string via the Azure portal.

Don’t ask users to compose connection strings manually if they aren’t available through the Azure portal. Connection strings are immutable. It’s impossible for an application to roll over credentials when using connection strings.

Namespaces

✅ DO adhere to the following scheme when choosing a namespace: Azure.<group>.<service>[.<feature>]

For example, Azure.Storage.Blobs.

✅ DO use one of the following pre-approved namespace groups:

• Azure.AI for artificial intelligence, including machine learning
• Azure.Analytics for client libraries that gather or process analytics data
• Azure.Communication communication services
• Azure.Core for libraries that aren’t service specific
• Azure.Cosmos for object database technologies
• Azure.Data for client libraries that handle databases or structured data stores
• Azure.DigitalTwins for DigitalTwins related technologies
• Azure.Identity for authentication and authorization client libraries
• Azure.IoT for client libraries dealing with the Internet of Things.
  • Use Iot for Pascal cased compound words, such as IotClient, otherwise follow language conventions.
  • Do not use IoT more than once in a namespace.
• Azure.Media for client libraries that deal with audio, video, or mixed reality
• Azure.Messaging for client libraries that provide messaging services, such as push notifications or pub-sub.
• Azure.ResourceManager.[ResourceProvider] for management plane client libraries for a given resource provider.
  • For example the compute management plane namespace would be Azure.ResourceManager.Compute.
• Azure.Search for search technologies
• Azure.Security for client libraries dealing with security
• Azure.Storage for client libraries that handle unstructured data

If you think a new group should be added to the list, contact adparch.

✅ DO register all namespaces with adparch.

⛔️ DO NOT place APIs in the second-level namespace (directly under the Azure namespace).

☑️ YOU SHOULD consider placing model types in a .Models namespace if number of model types is or might become large.

See model type guidelines for details.

Support for Mocking

All client libraries must support mocking to enable non-live testing of service clients by customers.

Here is an example of how the ConfigurationClient can be mocked using Moq (a popular .NET mocking library):

// Create a mock response
var mockResponse = new Mock<Response>();
// Create a client mock
var mock = new Mock<ConfigurationClient>();
// Setup client method
mock.Setup(c => c.Get("Key", It.IsAny<string>(), It.IsAny<DateTimeOffset>(), It.IsAny<CancellationToken>()))
    .Returns(new Response<ConfigurationSetting>(mockResponse.Object, ConfigurationModelFactory.ConfigurationSetting("Key", "Value")));

// Use the client mock
ConfigurationClient client = mock.Object;
ConfigurationSetting setting = client.Get("Key");
Assert.AreEqual("Value", setting.Value);

Review the full sample in the GitHub repository.

✅ DO provide protected parameterless constructor for mocking.

✅ DO make all service methods virtual.

✅ DO make all properties virtual.

    public class BlobContainerClient {
        public virtual string Name { get; }
        public virtual Uri Uri { get; }
    }

✅ DO make methods returning other clients virtual.

public class BlobContainerClient
{
    public virtual BlobClient GetBlobClient();
}

✅ DO use instance methods instead of extension methods when defined in the same assembly. The instance methods are simpler to mock.

public class BlobContainerClient
{
    // This method is possible to mock
    public virtual AppendBlobClient GetAppendBlobClient() {}
}

public class BlobContainerClientExtensions
{
    // This method is impossible to mock
    public static AppendBlobClient GetAppendBlobClient(this BlobContainerClient containerClient) {}
}

✅ DO provide factory or builder for constructing model graphs returned from virtual service methods.

Model types shouldn’t have public constructors. Instances of the model are typically returned from the client library, and are not constructed by the consumer of the library. Mock implementations need to create instances of model types. Implement a static class called <service>ModelFactory in the same namespace as the model types:

public static class ConfigurationModelFactory {
    public static ConfigurationSetting ConfigurationSetting(string key, string value, string label=default, string contentType=default, ETag eTag=default, DateTimeOffset? lastModified=default, bool? locked=default);
    public static SettingBatch SettingBatch(ConfigurationSetting[] settings, string link, SettingSelector selector);
}

✅ DO hide older overloads and avoid ambiguity.

When read-only properties are added to models and factory methods must be added to optionally set these properties, you must hide the previous method and remove all default parameter values to avoid ambiguity:

public static class ConfigurationModelFactory {
    [EditorBrowsable(EditorBrowsableState.Never)]
    public static ConfigurationSetting ConfigurationSetting(string key, string value, string label, string contentType, ETag eTag, DateTimeOffset? lastModified, bool? locked) =>
        ConfigurationSetting(key, value, label, contentType, eTag, lastModified, locked, default);
    public static ConfigurationSetting ConfigurationSetting(string key, string value, string label=default, string contentType=default, ETag eTag=default, DateTimeOffset? lastModified=default, bool? locked=default, int? ttl=default);
}

Azure SDK Library Design

Packaging

✅ DO package all components as NuGet packages.

If your client library is built by the Azure SDK engineering systems, all packaging requirements will be met automatically. Follow the .NET packaging guidelines if you’re self-publishing. For Microsoft owned packages we need to support both windows (for windows dump diagnostics) and portable (for x-platform debugging) pdb formats which means you need to publish them to the Microsoft symbol server and not the Nuget symbol server which only supports portable pdbs.

✅ DO name the package based on the name of the main namespace of the component.

For example, if the component is in the Azure.Storage.Blobs namespace, the component DLL will be Azure.Storage.Blobs.dll and the NuGet package will bAzure.Storage.Blobs``.

☑️ YOU SHOULD place small related components that evolve together in a single NuGet package.

✅ DO build all libraries for .NET Standard 2.0.

Use the following target setting in the .csproj file:

<TargetFramework>netstandard2.0</TargetFramework>

Common Libraries

There are occasions when common code needs to be shared between several client libraries. For example, a set of cooperating client libraries may wish to share a set of exceptions or models.

✅ DO gain Architecture Board discuss how to design such common library.

Versioning

Client Versions

✅ DO be 100% backwards compatible with older versions of the same package.

For detailed rules, see .NET Breaking Changes.

✅ DO introduce a new package (with new assembly names, new namespace names, and new type names) if you must do an API breaking change.

Breaking changes should happen rarely, if ever. Register your intent to do a breaking change with adparch. You’ll need to have a discussion with the language architect before approval.

Package Version Numbers

Consistent version number scheme allows consumers to determine what to expect from a new version of the library.

✅ DO use MAJOR.MINOR.PATCH format for the version of the library dll and the NuGet package.

Use -beta._N suffix for beta package versions. For example, 1.0.0-beta.2.

✅ DO change the version number of the client library when ANYTHING changes in the client library.

✅ DO increment the patch version when fixing a bug.

⛔️ DO NOT include new APIs in a patch release.

✅ DO increment the major or minor version when adding support for a service API version.

✅ DO increment the major or minor version when adding a new method to the public API.

☑️ YOU SHOULD increment the major version when making large feature changes.

✅ DO select a version number greater than the highest version number of any other released Track 1 package for the service in any other scope or language.

Dependencies

☑️ YOU SHOULD minimize dependencies outside of the .NET Standard and Azure.Core packages.

⛔️ DO NOT depend on any NuGet package except the following packages:

• Azure.* packages from the azure/azure-sdk-for-net repository.
• System.Text.Json.
• Microsoft.BCL.AsyncInterfaces.
• packages produced by your own team.

In the past, [JSON.NET] was commonly used for serialization and deserialization. Use the System.Text.Json package that is now a part of the .NET platform instead.

⛔️ DO NOT publicly expose types from dependencies unless the types follow these guidelines as well.

Native Code

Native dependencies introduce lots of complexities to .NET libraries and so they should be avoided.

⚠️ YOU SHOULD NOT native dependencies.

Documentation Comments

✅ DO document every exposed (public or protected) type and member within your library’s code.

✅ DO use C# documentation comments for reference documentation.

See the documentation guidelines for language-independent guidelines for how to provide good documentation.

Repository Guidelines

✅ DO locate all source code and README in the azure/azure-sdk-for-net GitHub repository.

✅ DO follow Azure SDK engineering systems guidelines for working in the azure/azure-sdk-for-net GitHub repository.

Documentation Style

TODO: issue #2338

README

✅ DO have a README.md file in the component root folder.

An example of a good README.md file can be found here.

✅ DO optimize the README.md for the consumer of the client library.

The contributor guide (CONTRIBUTING.md) should be a separate file linked to from the main component README.md.

Samples

Each client library should have a quickstart guide with code samples. Developers like to learn about a library by looking at sample code; not by reading in-depth technology papers.

✅ DO have usage samples in samples subdirectory of main library directory.

For a complete example, see the Configuration Service samples.

✅ DO have a README.md file with the following front matter:

---
page_type: sample
languages:
- csharp
products:
- azure
- azure-app-configuration
name: Azure.Data.AppConfiguration samples for .NET
description: Samples for the Azure.Data.AppConfiguration client library
---

The README.md file should be written as a getting started guide. See the ServiceBus README for a good example.

✅ DO link to each of the samples files using a brief description as the link text.

✅ DO have a sample file called Sample1_HelloWorld.md. All other samples are ordered from simplest to most complex using the Sample<number>_ prefix.

✅ DO use synchronous APIs in the Sample1_HelloWorld.md sample. Add a second sample named Sample1_HelloWorldAsync.md that does the same thing as Sample1_HelloWorld.md using asynchronous code.

✅ DO use #regions in source with a unique identifier starting with “Snippet:” like Snippet:AzConfigSample1_CreateConfigurationClient. This must be unique within the entire repo.

✅ DO C# code fences with the corresponding #region name like so:

```C# Snippet:AzConfigSample1_CreateConfigurationClient
var client = new ConfigurationClient(connectionString);
```

✅ DO make sure all the samples build and run as part of the CI process.

TODO: Update guidance on samples to reflect what we do in most places.

Commonly Overlooked .NET API Design Guidelines

Some .NET Framework Design Guidelines have been notoriously overlooked in earlier Azure SDKs. This section serves as a way to highlight these guidelines.

⚠️ YOU SHOULD NOT have many types in the main namespace. Number of types is directly proportional to the perceived complexity of a library.

⛔️ DO NOT use abstractions unless the Azure SDK both returns and consumes the abstraction. An abstraction is either an interface or abstract class.

⛔️ DO NOT use interfaces if you can use abstract classes. The only reasons to use an interface are: a) you need to “multiple-inherit”, b) you want structs to implement an abstraction.

⛔️ DO NOT use generic words and terms for type names. For example, do not use names like OperationResponse or DataCollection.

⚠️ YOU SHOULD NOT use parameter types where it’s not clear what valid values are supported. For example, do not use strings but only accept certain values in the string.

⛔️ DO NOT have empty types (types with no members).