通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure Core 共享客户端库 - 版本 1.35.0

  • 项目

Azure.Core 为新式 .NET Azure SDK 客户端库提供共享基元、抽象和帮助程序。 这些库遵循 适用于 .NET 的 Azure SDK 设计指南 ，可以通过以“Azure”开头的包和命名空间名称轻松识别，例如 Azure.Storage.Blobs。 可 在此处找到使用 Azure.Core 的客户端库的更完整列表。

Azure.Core 允许客户端库以一致的方式公开常见功能，因此，在了解如何在一个客户端库中使用这些 API 后，你将了解如何在其他客户端库中使用这些 API。

源代码 | 包 (NuGet) | API 参考文档

入门

通常，无需安装 Azure.Core;使用它安装其中一个客户端库时，会为你安装它。 如果要显式安装它 (实现自己的客户端库（例如) ），可 在此处找到 NuGet 包。

关键概念

Azure.Core (main共享的概念，因此使用 Azure.Core) 的 Azure SDK 库包括：

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

下面，你将找到更详细地介绍这些共享概念的部分。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。 这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

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

使用 配置服务客户端 ClientOptions

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

可以通过调用简单构造函数或其采用各种配置选项的重载来实例化这些客户端类型。 这些选项作为参数传递，用于扩展 ClientOptions Azure.Core 公开的类。 通常将各种特定于服务的选项添加到其子类中，但 SDK 范围的一组选项直接在 上 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);

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

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

服务客户端 具有可用于调用 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);
}

有关分页响应的详细信息，请参阅 使用适用于 .NET 的 Azure SDK 进行分页。

使用 Long-Running 操作 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。

例如，可以使用 Moq) 对 ConfigurationClient.Get 方法进行模拟 (，如下所示：

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

有关使用 适用于 .NET 的 Azure SDK 进行单元测试和模拟中的模拟的详细信息。

使用 Application Insights 进行分布式跟踪

Application Insights 是 Azure Monitor 的一项功能，是面向开发人员和 DevOps 专业人员的一项可扩展的应用程序性能管理 (APM) 服务。 使用它可以监视实时应用程序。 它将自动检测性能异常，并包括功能强大的分析工具，以帮助你诊断问题并了解用户实际对应用执行的操作

如果应用程序已使用 ApplicationInsights，则自版本 2.12.0以来支持自动收集 Azure SDK 跟踪。

若要为应用程序设置 ApplicationInsights 跟踪，请按照 启动监视应用程序 指南进行操作。

有关诊断示例中诊断的详细信息。

疑难解答

排查故障的三种main方法包括检查异常、启用日志记录和分布式跟踪

后续步骤

浏览并安装 可用的 Azure SDK 库。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 在所有存储库中执行此操作一次。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

曝光数