共用方式為

適用于 .NET 的 Azure Core 共用用戶端程式庫 - 1.30.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 (的主要共用概念，因此使用 Azure.Core) 的 Azure SDK 程式庫包括：

  • 設定服務用戶端，例如設定重試、記錄 () ClientOptions 。
  • (存取 Response<T> HTTP 回應詳細資料， Response) 。
  • () Operation<T> 呼叫長時間執行的作業。
  • 分頁和非同步資料流程 (AsyncPageable<T>) 。
  • 以一致的方式回報來自服務要求之錯誤的例外狀況。 (RequestFailedException).
  • 自訂要求 (RequestContext) 。
  • 表示 Azure SDK 認證的抽象概念。 (TokenCredentials).

以下會更詳細地找到說明這些共用概念的章節。

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。 這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

用戶端選項 | 存取回應 | 長時間執行的作業 | 處理失敗 | 診斷 | 嘲笑 | 用戶端存留期

範例

注意： 此檔案中的範例僅適用于遵循 Azure SDK 設計指導方針的套件。 這類套件的名稱通常以 Azure 開頭。

使用 設定服務用戶端 ClientOptions

Azure SDK 用戶端程式庫通常會公開一或多個 服務用戶端 類型，這些是呼叫對應 Azure 服務的主要起點。 您可以輕鬆地找到這些用戶端類型作為其名稱結尾的 Client一詞。 例如， 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}");
}

更多回應範例中的回應類型

設定主控台記錄

若要建立將訊息輸出至主控台使用 AzureEventSourceListener.CreateConsoleLogger 方法的 Azure SDK 記錄接聽程式。

// 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 的一般服務用戶端組態之外，您也可以使用通訊協定方法或公開為參數的便利 API， RequestContext 自訂服務用戶端所傳送的要求。

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

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

RequestCoNtext 範例中有關要求自訂的詳細資訊

模擬

使用 Azure.Core 之新用戶端程式庫最重要的跨領域功能之一，就是其設計用於模擬。 模擬是由以下方式啟用：

  • 在用戶端類型上提供受保護的無參數建構函式。
  • 讓服務方法成為虛擬。
  • 提供 API 來建構從虛擬服務方法傳回的模型類型。 若要尋找這些 Factory 方法，請尋找具有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");

深入瞭解模擬 範例中的模擬

使用 Application Insights 的分散式追蹤

Application Insights 是 Azure 監視器的一項功能，其為適用於開發人員和 DevOps 專業人員的可擴充應用程式效能管理 (APM) 服務。 您可以使用它來監視即時應用程式。 它會自動偵測效能異常，並包含功能強大的分析工具，可協助您診斷問題，並瞭解使用者實際使用應用程式的功能

如果您的應用程式已經使用 ApplicationInsights，自版本 2.12.0 起支援自動收集 Azure SDK 追蹤。

若要為您的應用程式設定 ApplicationInsights 追蹤，請遵循 啟動監視應用程式 指南。

深入瞭解 診斷範例中的診斷。

疑難排解

疑難排解失敗的三種主要方式是 檢查例外狀況、啟用 記錄和 分散式追蹤

下一步

探索並安裝 可用的 Azure SDK 程式庫。

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數