Azure.Core 1.42.0

前缀已预留
.NET 6.0 此包针对 .NET 6.0。此包与该框架兼容或更高。 .NET Standard 2.0 此包针对 .NET Standard 2.0。此包与该框架兼容或更高。 .NET Framework 4.6.1 此包针对 .NET Framework 4.6.1。此包与该框架兼容或更高。 
dotnet add package Azure.Core --version 1.42.0                

                    
                

            
NuGet\Install-Package Azure.Core -Version 1.42.0
此命令旨在在 Visual Studio 的包管理器控制台中使用，因为它使用 NuGet 模块的 Install-Package 版本。
<PackageReference Include="Azure.Core" Version="1.42.0" />
对于支持 PackageReference 的项目，将此 XML 节点复制到项目文件中以引用此包。
paket add Azure.Core --version 1.42.0                

                    
                

            
#r "nuget: Azure.Core, 1.42.0"
#r 指令可以在 F# Interactive 和 Polyglot Notebooks 中使用。请将此复制到交互工具或脚本的源代码中以便引用此包。
// Install Azure.Core as a Cake Addin
#addin nuget:?package=Azure.Core&version=1.42.0

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

Azure Core 共享客户端库（.NET）

Azure.Core 提供了现代 .NET Azure SDK 客户端库所用的共享原语、抽象和助手。这些库遵循 Azure SDK 设计指南 for .NET，并且可以通过以 'Azure' 为名称开头的包和命名空间名称轻松识别，例如 Azure\Storage:Blobs。可以使用 Azure.Core 的客户端库的更完整的列表可以在 这里 找到。

Azure.Core 允许客户端库以一致的方式公开常见功能，一旦你学会了如何在一个客户端库中使用这些 API，你将知道如何在其他客户端库中使用它们。

源代码 | 包（NuGet） | API 参考文档

入门

通常，你不需要安装 Azure.Core；当你安装使用它的客户端库之一时，它会为你安装。如果你想显式安装它（例如，实现自己的客户端库），你可以在 这里 找到 NuGet 包。

关键概念

Azure.Core 的主要共享概念（以及因此使用 Azure.Core 的 Azure SDK 库）包括

  • 配置服务客户端，例如配置重试、日志（ClientOptions）。
  • 访问 HTTP 响应详细信息（Response，Response）。
  • 调用长时间运行的操作（Operation）。
  • 分页和异步流（AsyncPageable）。
  • 用于以一致方式报告服务请求错误的异常。（RequestFailedException）。
  • 自定义请求（RequestContext）。
  • 表示 Azure SDK 凭据的抽象。（TokenCredentials）。

以下部分将更详细地解释这些共享概念。

线程安全性

我们保证所有客户端实例方法都是线程安全的，并且相互独立（指导原则）。这确保了重用客户端实例的建议始终安全，即使在跨线程的情况下也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

注意：该文件中的示例仅适用于遵循 Azure SDK 设计指南 的包。此类包的名称通常以 Azure 开头。

使用 ClientOptions 配置服务客户端

Azure SDK 客户端库通常会公开一个或多个 服务客户端 类型，这是调用相应 Azure 服务的主要起点。你可以轻松找到这些客户端类型，因为它们的名称以单词 Client 结尾。例如，使用 BlockBlobClient 可以调用 blob 存储服务，使用 KeyClient 可以访问密钥保管库服务的加密密钥。

这些客户端类型可以通过调用简单的构造函数或带有各种配置选项的重载来实现实例化。这些选项通过 Azure.Core 暴露的 ClientOptions 类传递作为参数。通常将各种特定于服务选项添加到其子类中，但在 ClientOptions 中可以直接使用一组 SDK 全局选项。

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);

有关客户端配置的更多信息，请参阅 客户端配置示例。

使用 Response<T> 访问 HTTP 响应详细信息

服务客户端具有可以用来调用 Azure 服务的方泰。我们将这些客户端方法称为 服务方法。服务方法返回一个共享的 Azure.Core 类型 Response<T>（在罕见的情况下，为其非泛型同族，一个原始的 Response）。此类提供对服务调用反序列化结果的访问，以及对从服务器返回的 HTTP 响应的细节。

// 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}");
}

有关响应类型的更多信息，请参阅 响应示例。

设置控制台日志记录

要创建一个输出消息到控制台的自定义 Azure SDK 日志监听器，请使用 AzureEventSourceListener.CreateConsoleLogger 方法。

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

有关日志记录的更多信息，请参阅 诊断示例。

报告错误 RequestFailedException

当服务调用失败时，将抛出 Azure.RequestFailedException。异常类型提供具有 HTTP 状态码的 Status 属性和具有特定于服务错误码的 ErrorCode 属性。

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);
}

有关处理响应的更多信息，请参阅 响应示例。

消费返回 AsyncPageable<T> 的服务方法

如果一个服务调用在分页中返回多个值，它将返回 Pageable<T>/AsyncPageable<T> 作为结果。你可以直接迭代 AsyncPageable 或分页。

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

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

有关分页响应的更多信息，请参阅 使用 Azure SDK for .NET 进行分页。

使用 Operation<T> 消费长时间运行的操作

一些操作需要很长时间才能完成，需要轮询其状态。返回长时间运行操作的方法返回 *Operation<T> 类型。

使用 WaitForCompletionAsync 方法是一个轻松等待操作完成并获得结果的简单方法。

// 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);

有关长时间运行操作的更多信息，请参阅 长时间运行操作示例。

使用 RequestContext 自定义请求

除了通过 ClientOptions 对 服务客户端 进行一般配置之外，还可能通过公开 RequestContext 作为参数的协议方法或便利 API 来自定义 服务客户端 发送的请求。

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

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

有关请求自定义的更多信息，请参阅 RequestContext 示例。

模拟

我们使用 Azure.Core 的新客户端库的最重要特性之一是它们设计为可模拟。模拟是通过以下方式实现的：

  • 在客户端类型上提供一个受保护的参数构造函数。
  • 将服务方法设置为虚拟。
  • 提供构造从虚拟服务方法返回的模型类型的 API。为了找到这些工厂方法，请查找带有 ModelFactory 后缀的类型，例如 SecretModelFactory。

例如，ConfigurationClient.Get 方法可以模拟（使用 Moq）如下

// 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");

在使用 Azure SDK for .NET 进行单元测试和模拟中了解更多关于模拟的内容。

使用 OpenTelemetry 的分布式跟踪

Azure SDK 使用 OpenTelemetry 进行分布式跟踪。分布式跟踪允许跟踪请求通过多个服务，记录网络或逻辑调用所需时间以及描述此类操作的结构化属性。

在诊断示例中了解更多关于诊断的信息。

要为您的应用程序设置分布式跟踪，请遵循您的可观测性供应商文档。如果您使用 Azure Monitor，请遵循开始监控应用程序指南。

故障排除

主要有三种故障排除方法：检查异常，启用日志和分布式跟踪。

下一步

探索和安装可用的 Azure SDK 库。

贡献

本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权利事实上已经授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA，并适当地修饰 PR（例如，标记、评论）。只需遵循 bot 提供的说明。您只需要在整个使用我们的 CLA 的所有存储库中这样做一次。

本项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅行为准则 FAQ，或与 [email protected] 联系，提出任何额外的问题或意见。

产品 兼容和额外的计算目标框架版本。
.NET net5.0已计算。 net5.0-windows已计算。 net6.0兼容。 net6.0-android已计算。 net6.0-ios已计算。 net6.0-maccatalyst已计算。 net6.0-macos已计算。 net6.0-tvos已计算。 net6.0-windows已计算。 net7.0已计算。 net7.0-android已计算。 net7.0-ios已计算。 net7.0-maccatalyst已计算。 net7.0-macos已计算。 net7.0-tvos已计算。 net7.0-windows已计算。 net8.0已计算。 net8.0-android已计算。 net8.0-browser已计算。 net8.0-ios已计算。 net8.0-maccatalyst已计算。 net8.0-macos已计算。 net8.0-tvos已计算。 net8.0-windows已计算。
.NET Core netcoreapp2.0已计算。 netcoreapp2.1已计算。 netcoreapp2.2已计算。 netcoreapp3.0已计算。 netcoreapp3.1已计算。
.NET Standard netstandard2.0兼容。 netstandard2.1已计算。
.NET Framework net461 兼容。 net462 已计算。 net463 已计算。 net47 已计算。 net471 已计算。 net472 兼容。 net48 已计算。 net481 已计算。
MonoAndroid monoandroid 已计算。
MonoMac monomac 已计算。
MonoTouch monotouch 已计算。
Tizen tizen40 已计算。 tizen60 已计算。
Xamarin.iOS xamarinios 已计算。
Xamarin.Mac xamarinmac 已计算。
Xamarin.TVOS xamarintvos 已计算。
Xamarin.WatchOS xamarinwatchos 已计算。
兼容的目标框架
包含的目标框架（在包中）
了解更多关于 目标框架 和 .NET Standard 的信息。

NuGet 包 (496)

显示依赖 Azure.Core 的前 5 个 NuGet 包

包 下载
Azure.Identity

这是 Azure SDK 客户端库 Azure Identity 的实现
Azure.Storage.Common

此客户端库使您能够与Microsoft Azure存储服务交互，其中包括用于存储二进制和文本数据的Blob和文件服务，以及队列服务用于存储可能由客户端访问的消息。有关此版本的信息，请参阅说明 - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure.Storage.Common/README.md 和 https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure Storage.Common/CHANGELOG.md，以及重大更改 https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/Azure.Storage.Common/BreakingChanges.txt，Microsoft Azure Storage quickstart 和教程 - https://docs.microsoft.com/en-us/azure/storage/，Microsoft Azure Storage REST API 参考文档 - https://docs.microsoft.com/en-us/rest/api/storageservices/
Azure.Security.KeyVault.Secrets

这是Microsoft Azure Key Vault Secrets客户端库
Azure.Messaging.ServiceBus

Azure Service Bus是一个全面管理的企业级集成消息代理。Service Bus可以解耦应用程序和服务。Service Bus提供一个可靠且安全的平台，用于异步数据状态传输。此客户端库允许使用Azure Service Bus发送和接收消息。有关Service Bus的更多信息，请参阅https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview
Azure.Security.KeyVault.Certificates

这是Microsoft Azure Key Vault Certificates客户端库

GitHub仓库 (46)

显示依赖Azure.Core的前5个最受欢迎的GitHub仓库

仓库 星星
dotnet/orleans
适用于.NET的云原生应用程序框架
Azure/azure-sdk-for-net
此仓库是Azure SDK for .NET的积极开发仓库。对于SDK的消费者，我们建议访问我们的公共开发人员文档https://learn.microsoft.com/dotnet/azure/或我们的版本开发人员文档https://azure.github.io/azure-sdk-for-net/。
Azure/azure-powershell
Microsoft Azure PowerShell
microsoft/perfview
PerfView是一款CPU和内存性能分析工具
Azure/azure-functions-host
Azure Functions的后台/运行时
版本 下载 最后更新
1.42.0 96,971 8/1/2024
1.41.0 1,394,093 7/11/2024
1.40.0 6,099,556 6/6/2024
1.39.0 7,742,756 4/19/2024
1.38.0 26,278,722 2/26/2024
1.37.0 25,578,937 1/11/2024
1.36.0 47,749,921 11/10/2023
1.35.0 67,735,864 9/7/2023
1.34.0 15,375,930 7/12/2023
1.33.0 13,898,453 6/16/2023
1.32.0 23,232,431 5/10/2023
1.31.0 23,271,446 4/10/2023
1.30.0 51,365,199 3/10/2023
1.28.0 12,815,911 2/6/2023
1.27.0 17,546,599 1/10/2023
1.26.0 8,679,159 11/8/2022
1.25.0 149,210,678 6/30/2022
1.24.0 112,815,359 4/5/2022
1.23.0 44,461,595 3/22/2022
1.22.0 28,750,723 1/13/2022
1.21.0 23,915,750 11/4/2021
1.20.0 74,516,550 10/4/2021
1.19.0 85,481,031 9/1/2021
1.18.0 6,926,037 8/19/2021
1.17.0 10,396,744 8/3/2021
1.16.0 8,936,501 7/1/2021
1.15.0 36,878,688 6/3/2021
1.14.0 37,657,582 5/6/2021
1.13.0 971,831 4/8/2021
1.12.0 874,955 3/31/2021
1.11.0 465,752 3/22/2021
1.10.0 23,410,707 3/8/2021
1.9.0 6,818,118 2/6/2021
1.8.1 24,175,589 1/11/2021
1.8.0 61,955 1/6/2021
1.7.0 4,999,004 12/14/2020
1.6.0 131,969,094 10/28/2020
1.5.1 557,125 10/1/2020
1.5.0 3,686,133 9/4/2020
1.4.1 24,671,742 8/18/2020
1.3.0 23,954,354 7/2/2020
1.2.2 8,605,422 6/4/2020
1.2.1 3,488,947 4/30/2020
1.2.0 1,544,853 4/3/2020
1.1.0 2,383,226 3/6/2020
1.0.2 81,597,033 2/10/2020
1.0.1 36,501,486 11/18/2019
1.0.0 5,832,280 10/29/2019
1.0.0-preview.9 26,901 10/7/2019
1.0.0-preview.8 14,662 9/9/2019
1.0.0-preview.7 8,859 8/5/2019
1.0.0-preview.6 6,048 6/27/2019
1.0.0-preview.5 14,025 5/3/2019

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