Azure Template client library for .NET

Azure Template is a template project for creating Azure SDK libraries generated from TypeSpec.

Use this template as a starting point for:

• Creating new TypeSpec-based Azure SDK client libraries
• Understanding the project structure for TypeSpec-generated SDKs

Source code | Package (NuGet) | API reference documentation | Product documentation

Getting started

This section should include everything a developer needs to do to install and create their first client connection very quickly.

Install the package

First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like dotnet add package package-name, but should enable a developer to successfully install the package from NuGet, npm, or even cloning a GitHub repository.

Install the client library for .NET with NuGet:

dotnet add package Azure.Template --prerelease

Prerequisites

Include a section after the install command that details any requirements that must be satisfied before a developer can authenticate and test all of the snippets in the Examples section. For example, for Cosmos DB:

You must have an Azure subscription and Cosmos DB account (SQL API). In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the .NET Core SDK 3.0 or higher with a language version of latest. It is also possible to compile with the .NET Core SDK 2.1.x using a language version of preview.

Authenticate the client

If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating.

For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object.

Key concepts

The Key concepts section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity.

Include the Thread safety and Additional concepts sections below at the end of your Key concepts section. You may remove or add links depending on what your library makes use of:

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

You can familiarize yourself with different APIs using Samples.

Basic usage example

Replace this section with examples specific to your generated client library methods.

// Example code will be generated based on your TypeSpec definition
// See the samples directory for complete examples

Troubleshooting

Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery.

Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API.

If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code.

Next steps

• Provide a link to additional code examples, ideally to those sitting alongside the README in the package's /samples directory.
• If appropriate, point users to other packages that might be useful.
• If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for.

Contributing

This is a template, but your SDK readme should include details on how to contribute code to the repo/package.