|
| 1 | +# Azure Core shared client library for .NET |
| 2 | + |
| 3 | +Azure.Core provides shared primitives, abstractions, and helpers for modern .NET Azure SDK client libraries. |
| 4 | +These libraries follow the [Azure SDK Design Guidelines for .NET](https://azure.github.io/azure-sdk/dotnet_introduction.html) |
| 5 | +and can be easily identified by package and namespaces names starting with 'Azure', e.g. `Azure.Storage.Blobs`. |
| 6 | +A more complete list of client libraries using Azure.Core can be found [here](https://github.com/Azure/azure-sdk-for-net#core-services). |
| 7 | + |
| 8 | +Azure.Core allows client libraries to expose common functionality in a consistent fashion, |
| 9 | +so that once you learn how to use these APIs in one client library, you will know how to use them in other client libraries. |
| 10 | + |
| 11 | +[Source code][source] | [Package (NuGet)][package] | [API reference documentation][docs] |
| 12 | + |
| 13 | +## Getting started |
| 14 | + |
| 15 | +Typically, you will not need to install Azure.Core; |
| 16 | +it will be installed for you when you install one of the client libraries using it. |
| 17 | +In case you want to install it explicitly (to implement your own client library, for example), |
| 18 | +you can find the NuGet package [here](https://www.nuget.org/packages/Azure.Core). |
| 19 | + |
| 20 | +## Key concepts |
| 21 | + |
| 22 | +The main shared concepts of Azure.Core (and so Azure SDK libraries using Azure.Core) include: |
| 23 | + |
| 24 | +- Configuring service clients, e.g. configuring retries, logging (`ClientOptions`). |
| 25 | +- Accessing HTTP response details (`Response`, `Response<T>`). |
| 26 | +- Calling long-running operations (`Operation<T>`). |
| 27 | +- Paging and asynchronous streams (`AsyncPageable<T>`). |
| 28 | +- Exceptions for reporting errors from service requests in a consistent fashion. (`RequestFailedException`). |
| 29 | +- Customizing requests (`RequestContext`). |
| 30 | +- Abstractions for representing Azure SDK credentials. (`TokenCredentials`). |
| 31 | + |
| 32 | +Below, you will find sections explaining these shared concepts in more detail. |
| 33 | + |
| 34 | +### Thread safety |
| 35 | + |
| 36 | +We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. |
| 37 | + |
| 38 | +### Additional concepts |
| 39 | + |
| 40 | +[Client options](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | |
| 41 | +[Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) | |
| 42 | +[Long-running operations](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt) | |
| 43 | +[Handling failures](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#reporting-errors-requestfailedexception) | |
| 44 | +[Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md) | |
| 45 | +[Mocking](https://learn.microsoft.com/dotnet/azure/sdk/unit-testing-mocking) | |
| 46 | +[Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/) |
| 47 | + |
| 48 | + |
| 49 | +## Examples |
| 50 | + |
| 51 | +**NOTE:** Samples in this file apply only to packages that follow [Azure SDK Design Guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html). Names of such packages usually start with `Azure`. |
| 52 | + |
| 53 | +### Configuring Service Clients Using `ClientOptions` |
| 54 | + |
| 55 | +Azure SDK client libraries typically expose one or more _service client_ types that |
| 56 | +are the main starting points for calling corresponding Azure services. |
| 57 | +You can easily find these client types as their names end with the word _Client_. |
| 58 | +For example, `BlockBlobClient` can be used to call blob storage service, |
| 59 | +and `KeyClient` can be used to access Key Vault service cryptographic keys. |
| 60 | + |
| 61 | +These client types can be instantiated by calling a simple constructor, |
| 62 | +or its overload that takes various configuration options. |
| 63 | +These options are passed as a parameter that extends `ClientOptions` class exposed by Azure.Core. |
| 64 | +Various service specific options are usually added to its subclasses, but a set of SDK-wide options are |
| 65 | +available directly on `ClientOptions`. |
| 66 | + |
| 67 | +```C# Snippet:ConfigurationHelloWorld |
| 68 | +SecretClientOptions options = new SecretClientOptions() |
| 69 | +{ |
| 70 | + Retry = |
| 71 | + { |
| 72 | + Delay = TimeSpan.FromSeconds(2), |
| 73 | + MaxRetries = 10, |
| 74 | + Mode = RetryMode.Fixed |
| 75 | + }, |
| 76 | + Diagnostics = |
| 77 | + { |
| 78 | + IsLoggingContentEnabled = true, |
| 79 | + ApplicationId = "myApplicationId" |
| 80 | + } |
| 81 | +}; |
| 82 | + |
| 83 | +SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options); |
| 84 | +``` |
| 85 | + |
| 86 | +More on client configuration in [client configuration samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md). |
| 87 | + |
| 88 | +### Accessing HTTP Response Details Using `Response<T>` |
| 89 | + |
| 90 | +_Service clients_ have methods that can be used to call Azure services. We refer to these client methods _service methods_. |
| 91 | +_Service methods_ return a shared Azure.Core type `Response<T>` (in rare cases its non-generic sibling, a raw `Response`). |
| 92 | +This type provides access to both the deserialized result of the service call, |
| 93 | +and to the details of the HTTP response returned from the server. |
| 94 | + |
| 95 | +```C# Snippet:ResponseTHelloWorld |
| 96 | +// create a client |
| 97 | +var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential()); |
| 98 | + |
| 99 | +// call a service method, which returns Response<T> |
| 100 | +Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName"); |
| 101 | + |
| 102 | +// Response<T> has two main accessors. |
| 103 | +// Value property for accessing the deserialized result of the call |
| 104 | +KeyVaultSecret secret = response.Value; |
| 105 | + |
| 106 | +// .. and GetRawResponse method for accessing all the details of the HTTP response |
| 107 | +Response http = response.GetRawResponse(); |
| 108 | + |
| 109 | +// for example, you can access HTTP status |
| 110 | +int status = http.Status; |
| 111 | + |
| 112 | +// or the headers |
| 113 | +foreach (HttpHeader header in http.Headers) |
| 114 | +{ |
| 115 | + Console.WriteLine($"{header.Name} {header.Value}"); |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +More on response types in [response samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Response.md). |
| 120 | + |
| 121 | +### Setting up console logging |
| 122 | + |
| 123 | +To create an Azure SDK log listener that outputs messages to console use `AzureEventSourceListener.CreateConsoleLogger` method. |
| 124 | + |
| 125 | +```C# Snippet:ConsoleLogging |
| 126 | +// Setup a listener to monitor logged events. |
| 127 | +using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger(); |
| 128 | +``` |
| 129 | + |
| 130 | +More on logging in [diagnostics samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md). |
| 131 | + |
| 132 | +### Reporting Errors `RequestFailedException` |
| 133 | + |
| 134 | +When a service call fails `Azure.RequestFailedException` would get thrown. The exception type provides a Status property with an HTTP status code and an ErrorCode property with a service-specific error code. |
| 135 | + |
| 136 | +```C# Snippet:RequestFailedException |
| 137 | +try |
| 138 | +{ |
| 139 | + KeyVaultSecret secret = client.GetSecret("NonexistentSecret"); |
| 140 | +} |
| 141 | +// handle exception with status code 404 |
| 142 | +catch (RequestFailedException e) when (e.Status == 404) |
| 143 | +{ |
| 144 | + // handle not found error |
| 145 | + Console.WriteLine("ErrorCode " + e.ErrorCode); |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +More on handling responses in [response samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Response.md). |
| 150 | + |
| 151 | +### Consuming Service Methods Returning `AsyncPageable<T>` |
| 152 | + |
| 153 | +If a service call returns multiple values in pages, it would return `Pageable<T>/AsyncPageable<T>` as a result. You can iterate over `AsyncPageable` directly or in pages. |
| 154 | + |
| 155 | +```C# Snippet:AsyncPageable |
| 156 | +// call a service method, which returns AsyncPageable<T> |
| 157 | +AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync(); |
| 158 | + |
| 159 | +await foreach (SecretProperties secretProperties in allSecretProperties) |
| 160 | +{ |
| 161 | + Console.WriteLine(secretProperties.Name); |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +For more information on paged responses, see [Pagination with the Azure SDK for .NET](https://docs.microsoft.com/dotnet/azure/sdk/pagination). |
| 166 | + |
| 167 | +### Consuming Long-Running Operations Using `Operation<T>` |
| 168 | + |
| 169 | +Some operations take long time to complete and require polling for their status. Methods starting long-running operations return `*Operation<T>` types. |
| 170 | + |
| 171 | +The `WaitForCompletionAsync` method is an easy way to wait for operation completion and get the resulting value. |
| 172 | + |
| 173 | +```C# Snippet:OperationCompletion |
| 174 | +// create a client |
| 175 | +SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential()); |
| 176 | + |
| 177 | +// Start the operation |
| 178 | +DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName"); |
| 179 | + |
| 180 | +Response<DeletedSecret> response = await operation.WaitForCompletionAsync(); |
| 181 | +DeletedSecret value = response.Value; |
| 182 | + |
| 183 | +Console.WriteLine(value.Name); |
| 184 | +Console.WriteLine(value.ScheduledPurgeDate); |
| 185 | +``` |
| 186 | + |
| 187 | +More on long-running operations in [long-running operation samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/LongRunningOperations.md). |
| 188 | + |
| 189 | +### Customizing Requests Using `RequestContext` |
| 190 | + |
| 191 | +Besides general configuration of _service clients_ through `ClientOptions`, it is possible to customize the requests sent by _service clients_ |
| 192 | +using protocol methods or convenience APIs that expose `RequestContext` as a parameter. |
| 193 | + |
| 194 | +```C# Snippet:SetRequestContext |
| 195 | +var context = new RequestContext(); |
| 196 | +context.AddClassifier(404, isError: false); |
| 197 | + |
| 198 | +Response response = await client.GetPetAsync("pet1", context); |
| 199 | +``` |
| 200 | + |
| 201 | +More on request customization in [RequestContext samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/RequestContext.md). |
| 202 | + |
| 203 | +### Mocking |
| 204 | + |
| 205 | +One of the most important cross-cutting features of our new client libraries using Azure.Core is that they are designed for mocking. |
| 206 | +Mocking is enabled by: |
| 207 | + |
| 208 | +- providing a protected parameterless constructor on client types. |
| 209 | +- making service methods virtual. |
| 210 | +- providing APIs for constructing model types returned from virtual service methods. To find these factory methods look for types with the _ModelFactory_ suffix, e.g. `SecretModelFactory`. |
| 211 | + |
| 212 | +For example, the ConfigurationClient.Get method can be mocked (with [Moq](https://github.com/moq/moq4)) as follows: |
| 213 | + |
| 214 | +```C# Snippet:ClientMock |
| 215 | +// Create a mock response |
| 216 | +var mockResponse = new Mock<Response>(); |
| 217 | + |
| 218 | +// Create a mock value |
| 219 | +var mockValue = SecretModelFactory.KeyVaultSecret( |
| 220 | + SecretModelFactory.SecretProperties(new Uri("http://example.com")) |
| 221 | +); |
| 222 | + |
| 223 | +// Create a client mock |
| 224 | +var mock = new Mock<SecretClient>(); |
| 225 | + |
| 226 | +// Setup client method |
| 227 | +mock.Setup(c => c.GetSecret("Name", null, default)) |
| 228 | + .Returns(Response.FromValue(mockValue, mockResponse.Object)); |
| 229 | + |
| 230 | +// Use the client mock |
| 231 | +SecretClient client = mock.Object; |
| 232 | +KeyVaultSecret secret = client.GetSecret("Name"); |
| 233 | +``` |
| 234 | + |
| 235 | +More on mocking in [Unit testing and mocking with the Azure SDK for .NET](https://learn.microsoft.com/dotnet/azure/sdk/unit-testing-mocking). |
| 236 | + |
| 237 | +## Distributed tracing with OpenTelemetry |
| 238 | + |
| 239 | +Azure SDKs are instrumented for distributed tracing using [OpenTelemetry](https://opentelemetry.io/). Distributed tracing allows to follow request through multiple services, record how long network or logical call take along with structured properties describing such operations. |
| 240 | + |
| 241 | +More on diagnostics in [diagnostics samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md). |
| 242 | + |
| 243 | +To setup distributed tracing for your application follow your observability vendor documentation. If you use Azure Monitor, follow the [Start Monitoring Application](https://learn.microsoft.com/azure/azure-monitor/app/opentelemetry-enable?tabs=aspnetcore) guide. |
| 244 | + |
| 245 | +## Troubleshooting |
| 246 | + |
| 247 | +Three main ways of troubleshooting failures are [inspecting exceptions](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Response.md#handling-exceptions), enabling [logging](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md#Logging), and [distributed tracing](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md#Distributed-tracing) |
| 248 | + |
| 249 | +## Next steps |
| 250 | + |
| 251 | +Explore and install [available Azure SDK libraries](https://azure.github.io/azure-sdk/releases/latest/dotnet.html). |
| 252 | + |
| 253 | +## Contributing |
| 254 | + |
| 255 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com. |
| 256 | + |
| 257 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA. |
| 258 | + |
| 259 | +This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact opencode@microsoft.com with any additional questions or comments. |
| 260 | + |
| 261 | + |
| 262 | + |
| 263 | +[source]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/core/Azure.Core/src |
| 264 | +[package]: https://www.nuget.org/packages/Azure.Core/ |
| 265 | +[docs]: https://docs.microsoft.com/dotnet/api/azure.core |
| 266 | +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct |
| 267 | +[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
0 commit comments