Azure.Core 1.38.0

Prefix Reserved

.NET 6.0 .NET Standard 2.0 .NET Framework 4.6.1

There is a newer version of this package available.
See the version list below for details.

dotnet add package Azure.Core --version 1.38.0

NuGet\Install-Package Azure.Core -Version 1.38.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Azure.Core" Version="1.38.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add Azure.Core --version 1.38.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Azure.Core, 1.38.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install Azure.Core as a Cake Addin
#addin nuget:?package=Azure.Core&version=1.38.0

// Install Azure.Core as a Cake Tool
#tool nuget:?package=Azure.Core&version=1.38.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Azure Core shared client library for .NET

Azure.Core provides shared primitives, abstractions, and helpers for modern .NET Azure SDK client libraries. These libraries follow the Azure SDK Design Guidelines for .NET and can be easily identified by package and namespaces names starting with 'Azure', e.g. Azure.Storage.Blobs. A more complete list of client libraries using Azure.Core can be found here.

Azure.Core allows client libraries to expose common functionality in a consistent fashion, 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.

Source code | Package (NuGet) | API reference documentation

Getting started

Typically, you will not need to install Azure.Core; it will be installed for you when you install one of the client libraries using it. In case you want to install it explicitly (to implement your own client library, for example), you can find the NuGet package here.

Key concepts

The main shared concepts of Azure.Core (and so Azure SDK libraries using Azure.Core) include:

Configuring service clients, e.g. configuring retries, logging (ClientOptions).
Accessing HTTP response details (Response, Response<T>).
Calling long-running operations (Operation<T>).
Paging and asynchronous streams (AsyncPageable<T>).
Exceptions for reporting errors from service requests in a consistent fashion. (RequestFailedException).
Customizing requests (RequestContext).
Abstractions for representing Azure SDK credentials. (TokenCredentials).

Below, you will find sections explaining these shared concepts in more detail.

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

Examples

NOTE: Samples in this file apply only to packages that follow Azure SDK Design Guidelines. Names of such packages usually start with Azure.

Configuring Service Clients Using `ClientOptions`

Azure SDK client libraries typically expose one or more service client types that are the main starting points for calling corresponding Azure services. You can easily find these client types as their names end with the word Client. For example, BlockBlobClient can be used to call blob storage service, and KeyClient can be used to access Key Vault service cryptographic keys.

These client types can be instantiated by calling a simple constructor, or its overload that takes various configuration options. These options are passed as a parameter that extends ClientOptions class exposed by Azure.Core. Various service specific options are usually added to its subclasses, but a set of SDK-wide options are available directly on ClientOptions.

SecretClientOptions options = new SecretClientOptions()
{
    Retry =
    {
        Delay = TimeSpan.FromSeconds(2),
        MaxRetries = 10,
        Mode = RetryMode.Fixed
    },
    Diagnostics =
    {
        IsLoggingContentEnabled = true,
        ApplicationId = "myApplicationId"
    }
};

SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options);

More on client configuration in client configuration samples.

Accessing HTTP Response Details Using `Response<T>`

Service clients have methods that can be used to call Azure services. We refer to these client methods service methods. Service methods return a shared Azure.Core type Response<T> (in rare cases its non-generic sibling, a raw Response). This type provides access to both the deserialized result of the service call, and to the details of the HTTP response returned from the server.

// create a client
var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// call a service method, which returns Response<T>
Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName");

// Response<T> has two main accessors.
// Value property for accessing the deserialized result of the call
KeyVaultSecret secret = response.Value;

// .. and GetRawResponse method for accessing all the details of the HTTP response
Response http = response.GetRawResponse();

// for example, you can access HTTP status
int status = http.Status;

// or the headers
foreach (HttpHeader header in http.Headers)
{
    Console.WriteLine($"{header.Name} {header.Value}");
}

More on response types in response samples.

Setting up console logging

To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Reporting Errors `RequestFailedException`

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.

try
{
    KeyVaultSecret secret = client.GetSecret("NonexistentSecret");
}
// handle exception with status code 404
catch (RequestFailedException e) when (e.Status == 404)
{
    // handle not found error
    Console.WriteLine("ErrorCode " + e.ErrorCode);
}

More on handling responses in response samples.

Consuming Service Methods Returning `AsyncPageable<T>`

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.

// call a service method, which returns AsyncPageable<T>
AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecretProperties)
{
    Console.WriteLine(secretProperties.Name);
}

For more information on paged responses, see Pagination with the Azure SDK for .NET.

Consuming Long-Running Operations Using `Operation<T>`

Some operations take long time to complete and require polling for their status. Methods starting long-running operations return *Operation<T> types.

The WaitForCompletionAsync method is an easy way to wait for operation completion and get the resulting value.

// create a client
SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// Start the operation
DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName");

Response<DeletedSecret> response = await operation.WaitForCompletionAsync();
DeletedSecret value = response.Value;

Console.WriteLine(value.Name);
Console.WriteLine(value.ScheduledPurgeDate);

More on long-running operations in long-running operation samples.

Customizing Requests Using `RequestContext`

Besides general configuration of service clients through ClientOptions, it is possible to customize the requests sent by service clients using protocol methods or convenience APIs that expose RequestContext as a parameter.

var context = new RequestContext();
context.AddClassifier(404, isError: false);

Response response = await client.GetPetAsync("pet1", context);

More on request customization in RequestContext samples.

Mocking

One of the most important cross-cutting features of our new client libraries using Azure.Core is that they are designed for mocking. Mocking is enabled by:

providing a protected parameterless constructor on client types.
making service methods virtual.
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.

For example, the ConfigurationClient.Get method can be mocked (with Moq) as follows:

// Create a mock response
var mockResponse = new Mock<Response>();

// Create a mock value
var mockValue = SecretModelFactory.KeyVaultSecret(
    SecretModelFactory.SecretProperties(new Uri("http://example.com"))
);

// Create a client mock
var mock = new Mock<SecretClient>();

// Setup client method
mock.Setup(c => c.GetSecret("Name", null, default))
    .Returns(Response.FromValue(mockValue, mockResponse.Object));

// Use the client mock
SecretClient client = mock.Object;
KeyVaultSecret secret = client.GetSecret("Name");

More on mocking in Unit testing and mocking with the Azure SDK for .NET.

Distributed tracing with OpenTelemetry

Azure SDKs are instrumented for distributed tracing using OpenTelemetry. Distributed tracing allows to follow request through multiple services, record how long network or logical call take along with structured properties describing such operations.

More on diagnostics in diagnostics samples.

To setup distributed tracing for your application follow your observability vendor documentation. If you use Azure Monitor, follow the Start Monitoring Application guide.

Troubleshooting

Three main ways of troubleshooting failures are inspecting exceptions, enabling logging, and distributed tracing

Next steps

Explore and install available Azure SDK libraries.

Contributing

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.

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.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 was computed.
.NET Framework	net461 is compatible. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 was computed. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.6.1
- Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
- System.ClientModel (>= 1.0.0)
- System.Diagnostics.DiagnosticSource (>= 6.0.1)
- System.Memory.Data (>= 1.0.2)
- System.Net.Http (>= 4.3.4)
- System.Numerics.Vectors (>= 4.5.0)
- System.Runtime.InteropServices.RuntimeInformation (>= 4.3.0)
- System.Text.Encodings.Web (>= 4.7.2)
- System.Text.Json (>= 4.7.2)
- System.Threading.Tasks.Extensions (>= 4.5.4)
.NETFramework 4.7.2
- Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
- System.ClientModel (>= 1.0.0)
- System.Diagnostics.DiagnosticSource (>= 6.0.1)
- System.Memory.Data (>= 1.0.2)
- System.Numerics.Vectors (>= 4.5.0)
- System.Text.Encodings.Web (>= 4.7.2)
- System.Text.Json (>= 4.7.2)
- System.Threading.Tasks.Extensions (>= 4.5.4)
.NETStandard 2.0
- Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
- System.ClientModel (>= 1.0.0)
- System.Diagnostics.DiagnosticSource (>= 6.0.1)
- System.Memory.Data (>= 1.0.2)
- System.Numerics.Vectors (>= 4.5.0)
- System.Text.Encodings.Web (>= 4.7.2)
- System.Text.Json (>= 4.7.2)
- System.Threading.Tasks.Extensions (>= 4.5.4)
net6.0
- Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
- System.ClientModel (>= 1.0.0)
- System.Diagnostics.DiagnosticSource (>= 6.0.1)
- System.Memory.Data (>= 1.0.2)
- System.Numerics.Vectors (>= 4.5.0)
- System.Text.Encodings.Web (>= 4.7.2)
- System.Text.Json (>= 4.7.2)
- System.Threading.Tasks.Extensions (>= 4.5.4)

NuGet packages (534)

Showing the top 5 NuGet packages that depend on Azure.Core:

Package	Downloads
Azure.Identity This is the implementation of the Azure SDK Client Library for Azure Identity	603.9M
Azure.Storage.Common This client library enables working with the Microsoft Azure Storage services which include the blob and file services for storing binary and text data, and the queue service for storing messages that may be accessed by a client. For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure.Storage.Common/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure.Storage.Common/CHANGELOG.md in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure.Storage.Common/BreakingChanges.txt Microsoft Azure Storage quickstarts and tutorials - https://docs.microsoft.com/en-us/azure/storage/ Microsoft Azure Storage REST API Reference - https://docs.microsoft.com/en-us/rest/api/storageservices/	314.5M
Azure.Security.KeyVault.Secrets This is the Microsoft Azure Key Vault Secrets client library	261.0M
Azure.Messaging.ServiceBus Azure Service Bus is a fully managed enterprise integration message broker. Service Bus can decouple applications and services. Service Bus offers a reliable and secure platform for asynchronous transfer of data and state. This client library allows for both sending and receiving messages using Azure Service Bus. For more information about Service Bus, see https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview	143.3M
Azure.Security.KeyVault.Certificates This is the Microsoft Azure Key Vault Certificates client library	97.2M

GitHub repositories (55)

Showing the top 5 popular GitHub repositories that depend on Azure.Core:

Repository	Stars
dotnet/orleans Cloud Native application framework for .NET	10.0K
Azure/azure-sdk-for-net This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.	5.2K
Azure/azure-powershell Microsoft Azure PowerShell	4.2K
microsoft/perfview PerfView is a CPU and memory performance-analysis tool	4.1K
Azure/azure-functions-host The host/runtime that powers Azure Functions	1.9K

Version	Downloads	Last updated
1.42.0	1,210,373	8/1/2024
1.41.0	3,875,401	7/11/2024
1.40.0	10,694,185	6/6/2024
1.39.0	10,085,887	4/19/2024
1.38.0	32,890,072	2/26/2024
1.37.0	30,707,351	1/11/2024
1.36.0	51,624,315	11/10/2023
1.35.0	75,122,935	9/7/2023
1.34.0	16,121,667	7/12/2023
1.33.0	14,520,373	6/16/2023
1.32.0	23,951,649	5/10/2023
1.31.0	24,375,698	4/10/2023
1.30.0	53,750,305	3/10/2023
1.28.0	13,280,148	2/6/2023
1.27.0	18,192,610	1/10/2023
1.26.0	8,895,961	11/8/2022
1.25.0	153,499,463	6/30/2022
1.24.0	114,937,118	4/5/2022
1.23.0	46,028,871	3/22/2022
1.22.0	29,190,677	1/13/2022
1.21.0	24,240,046	11/4/2021
1.20.0	76,888,651	10/4/2021
1.19.0	87,976,073	9/1/2021
1.18.0	7,016,028	8/19/2021
1.17.0	10,478,151	8/3/2021
1.16.0	9,037,684	7/1/2021
1.15.0	37,402,379	6/3/2021
1.14.0	38,144,346	5/6/2021
1.13.0	975,040	4/8/2021
1.12.0	885,271	3/31/2021
1.11.0	468,307	3/22/2021
1.10.0	24,446,429	3/8/2021
1.9.0	6,860,115	2/6/2021
1.8.1	24,370,311	1/11/2021
1.8.0	62,142	1/6/2021
1.7.0	5,240,268	12/14/2020
1.6.0	134,243,190	10/28/2020
1.5.1	557,892	10/1/2020
1.5.0	3,733,003	9/4/2020
1.4.1	24,880,028	8/18/2020
1.3.0	24,171,797	7/2/2020
1.2.2	8,639,557	6/4/2020
1.2.1	3,499,701	4/30/2020
1.2.0	1,547,885	4/3/2020
1.1.0	2,398,129	3/6/2020
1.0.2	82,831,780	2/10/2020
1.0.1	36,893,716	11/18/2019
1.0.0	5,897,250	10/29/2019
1.0.0-preview.9	27,032	10/7/2019
1.0.0-preview.8	14,718	9/9/2019
1.0.0-preview.7	8,923	8/5/2019
1.0.0-preview.6	6,145	6/27/2019
1.0.0-preview.5	14,080	5/3/2019

https://github.com/Azure/azure-sdk-for-net/blob/Azure.Core_1.38.0/sdk/core/Azure.Core/CHANGELOG.md

Total 1.4B

Current version 32.9M

Per day average 724.9K

Microsoft Azure Client Pipeline

Azure.Core 1.38.0

Azure Core shared client library for .NET

Getting started

Key concepts

Thread safety

Additional concepts

Examples

Configuring Service Clients Using ClientOptions

Accessing HTTP Response Details Using Response<T>

Setting up console logging

Reporting Errors RequestFailedException

Consuming Service Methods Returning AsyncPageable<T>

Consuming Long-Running Operations Using Operation<T>

Customizing Requests Using RequestContext