.NET 用 Azure Core 共有クライアントライブラリ - バージョン 1.35.0

[アーティクル]
09/07/2023

Azure.Core には、最新の .NET Azure SDK クライアントライブラリ用の共有プリミティブ、抽象化、ヘルパーが用意されています。これらのライブラリは、.NET の Azure SDK 設計ガイドラインに従っており、'Azure' で始まるパッケージ名と名前空間名 (例: ) で簡単に識別できます。 Azure.Storage.Blobs Azure.Core を使用したクライアントライブラリの詳細な一覧については、こちらを参照してください。

Azure.Core を使用すると、クライアントライブラリは一貫した方法で共通の機能を公開できるため、1 つのクライアントライブラリでこれらの API を使用する方法を学習すると、他のクライアントライブラリでそれらを使用する方法がわかります。

ソースコード | パッケージ (NuGet) | API リファレンスドキュメント

作業の開始

通常、Azure.Core をインストールする必要はありません。これを使用してクライアントライブラリの 1 つをインストールすると、インストールされます。 (たとえば、独自のクライアントライブラリを実装するために) 明示的にインストールする場合は、ここで NuGet パッケージを見つけることができます。

主要な概念

Azure.Core のメイン共有の概念 (そのため、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 サービスを呼び出すためのメインの開始点である 1 つ以上のサービスクライアントの種類を公開します。これらのクライアントの種類は、名前の末尾として Client という単語で簡単に見つけることができます。たとえば、 BlockBlobClient を使用して BLOB ストレージサービスを呼び出しKeyClient、サービスの暗号化キー Key Vaultアクセスするために使用できます。

これらのクライアント型は、単純なコンストラクター、またはさまざまな構成オプションを受け取るオーバーロードを呼び出すことによってインスタンス化できます。これらのオプションは、Azure.Core によって公開されるクラスを拡張 ClientOptions するパラメーターとして渡されます。通常、さまざまなサービス固有のオプションがそのサブクラスに追加されますが、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 、スローされます。例外の種類では、Status プロパティに HTTP 状態コードと、サービス固有のエラーコードを含む 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 を使用した改ページ」を参照してください。

を使用した 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 を使用した新しいクライアントライブラリの最も重要なクロスカット機能の 1 つは、モック作成用に設計されていることです。モック作成は次の方法で有効になります。

クライアント型に対して保護されたパラメーターなしのコンストラクターを提供する。
サービスメソッドを仮想にする。
仮想サービスメソッドから返されるモデル型を構築するための 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 での単体テストとモック作成の詳細。

Application Insights を使用した分散トレース

Application Insights は Azure Monitor の機能であり、開発者や DevOps プロフェッショナル向けの拡張可能なアプリケーションパフォーマンス管理 (APM) サービスです。このサービスを使用して、実行中のアプリケーションを監視することができます。パフォーマンスの異常を自動的に検出し、問題を診断し、ユーザーがアプリで実際に何を行うかを理解するのに役立つ強力な分析ツールが含まれています

アプリケーションで ApplicationInsights が既に使用されている場合は、バージョン 2.12.0以降に Azure SDK トレースの自動収集がサポートされます。

アプリケーションの ApplicationInsights 追跡をセットアップするには、アプリケーションの監視の開始ガイドに従います。

診断サンプルの診断の詳細。

トラブルシューティング

エラーのトラブルシューティングメイン 3 つの方法は、例外の検査、ログ記録の有効化、分散トレースです

次のステップ

使用可能な Azure SDK ライブラリを調べてインストールします。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

.NET 用 Azure Core 共有クライアントライブラリ - バージョン 1.35.0

作業の開始

主要な概念

スレッドセーフ

その他の概念

例

を使用したサービスクライアントの構成 `ClientOptions`

を使用して HTTP 応答の詳細にアクセスする `Response<T>`

コンソールログの設定

エラーの報告 `RequestFailedException`

返されるサービスメソッドの使用 `AsyncPageable<T>`

を使用した Long-Running 操作の使用 `Operation<T>`

を使用した要求のカスタマイズ `RequestContext`

モック

Application Insights を使用した分散トレース

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

次の方法で共有

.NET 用 Azure Core 共有クライアント ライブラリ - バージョン 1.35.0

作業の開始

主要な概念

スレッド セーフ

その他の概念

例

を使用したサービス クライアントの構成 ClientOptions

を使用して HTTP 応答の詳細にアクセスする Response<T>

コンソール ログの設定

エラーの報告 RequestFailedException

返されるサービス メソッドの使用 AsyncPageable<T>

を使用した Long-Running 操作の使用 Operation<T>

を使用した要求のカスタマイズ RequestContext

モック

Application Insights を使用した分散トレース

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

.NET 用 Azure Core 共有クライアントライブラリ - バージョン 1.35.0

スレッドセーフ

を使用したサービスクライアントの構成 `ClientOptions`

を使用して HTTP 応答の詳細にアクセスする `Response<T>`

コンソールログの設定

エラーの報告 `RequestFailedException`

返されるサービスメソッドの使用 `AsyncPageable<T>`

を使用した Long-Running 操作の使用 `Operation<T>`

を使用した要求のカスタマイズ `RequestContext`