WebAPIService クラスライブラリ (C#)

[アーティクル]
02/23/2023

WebAPIService は、Dataverse Web APIを使用するときに含める必要があるいくつかの重要な機能を示すサンプル .NET 6.0 クラスライブラリプロジェクトです。

このライブラリでは、以下を示します:

.NET の回復性と一時的なエラー処理ライブラリ Polly による Dataverse サービス保護制限の管理。
IHttpClientFactory を使用した .NET での HttpClient の管理。
構成データを使用したクライアントの動作の管理。
Dataverse Web API によって返されるエラーの管理。
コード再利用のパターン:
- HttpRequestMessage と HttpResponseMessage を継承するクラスの作成。
- これらのクラスを使用するメソッド。
- 必要に応じて新しい機能を追加するためのモジュールパターン。

注意

このサンプルライブラリは、すべての Dataverse C# Web API サンプルで使用されるヘルパーですが、SDK ではありません。それを使用するサンプルが正常に動作することを確認するためだけにテストされます。このサンプルコードは「現状のまま」提供され、再利用の保証はありません。

このライブラリには以下の機能はありません:

認証の管理。これは、使用するアクセストークンを提供するアプリケーションから渡される関数に依存します。すべての Web API サンプルは、Microsoft 認証ライブラリ (MSAL) を使用して認証を管理する、共有済みアプリクラスに依存します。 MSAL では、いくつかの異なる種類の認証フローがサポートされています。これらのサンプルでは、簡素化のためにユーザー名/パスワード (ROPC) フローを使用していますが、このフローは推奨されません。アプリの場合は、他のフローのいずれかを使用する必要があります。詳細: Microsoft 認証ライブラリでの認証フローのサポート。
コード生成機能の提供。サンプルで使用されるすべてのクラスは手動で記述されています。すべてのビジネスエンティティデータは、エンティティタイプを表すクラスではなく、既知の Json.NET JObject クラスを使用します。
OData クエリを作成するためのオブジェクトモデルの提供。すべてのクエリは、OData クエリ構文をクエリパラメーターとして表示します。

コード

WebApiService クラスライブラリのソースコードと Visual Studio ソリューションは PowerApps - サンプル/cds/webapi/C#/CDSWebApiService にあります

クラスリスト

次が WebAPIService に含まれたクラスです。

Service クラス

Service クラスは、IHttpClientFactory を使用して管理される HttpClient を通じて Dataverse に要求を送信するメソッドを提供します。

Service はすべてのサンプルのコアコンポーネントであり、これを使用してサンプルコードで示されている操作を完了できます。 WebAPIService に含まれる他のすべてのもの、またはそれを使用するサンプルはコードの再利用を可能にし、Dataverse Web API の機能をより高いレベルでデモンストレーションできるようにします。

Service コンストラクターは、次の 2 つの必須プロパティを含む Config クラスインスタンスを受け取ります: GetAccessToken および Url。他のすべてのプロパティは、既定値を持つオプションを表します。

コンストラクターは依存関係の挿入を使用して、ConfigureHttpClient 関数で指定されたプロパティを持つ名前付き HttpClient を返すことができる IHttpClientFactory を作成します。このクライアントが Cookie を使用するかどうかは、Config.DisableCookies パラメータが設定されているかどうかによって決まります。コンストラクターでは、一時的なエラーと GetRetryPolicy サービス保護制限の管理方法を制御する静的 Dataverse メソッドによって定義されたポリシー。

サービスメソッド

Service クラスには、次のメソッドがあります:

SendAsync メソッド

このメソッドは、すべての操作の最終的な責任を負います。

このメソッドは:

HttpRequestMessage パラメーターを持ちます。
Task<HttpResponseMessage> を返します
HttpClient.SendAsync(HttpRequestMessage) メソッドと同じシグネチャを公開し、同じ方法で使用できます。
Config.GetAccessToken メソッドで設定された関数を呼び出して、要求の Authorization ヘッダー値を設定します。
IHttpClientFactory.CreateClient メソッドを使用して、名前付き HttpClient を取得し要求を送信します。
HttpResponseMessage.IsSuccessStatusCode プロパティが false の場合は、ServiceException をスローし、このメソッドを使用する時は IsSuccessStatusCode をチェックする必要はありません。

SendAsync<T> メソッド

このメソッドは、Dataverse Web API の OData アクションおよび関数によって返される ComplexTypes にあるプロパティを含むクラスを返すことを容易にします。

HttpRequestMessage パラメーターを持ちます。このメソッドを使用する場合、要求パラメータが HttpResponseMessage から派生した *応答クラスのいずれかであることが想定されますが、必須ではありません。
T が HttpResponseMessage から派生したクラスである Task<T> を返します。詳細については、*応答クラスを参照してください。
SendAsync メソッドを呼び出します。
HttpResponseMessage As<T> を使用し、要求された型を返します。

次の例は、WhoAmI function の使用法を示しています:

static async Task WhoAmI(Service service)
{
   var response = await service.SendAsync<WhoAmIResponse>(new WhoAmIRequest());

   Console.WriteLine($"Your user ID is {response.UserId}");
}

ParseError メソッド

このメソッドは、失敗した HttpResponseMessage HttpRequestMessage の内容を解析して ServiceException を返します。 SendAsync メソッドは、HttpResponseMessage.IsSuccessStatusCode プロパティが false の場合にこのメソッドを使用します。また、BatchRequest.ContinueOnError プロパティが true に設定されているときに、BatchResponse.HttpResponseMessages から返された HttpResponseMessage インスタンスからエラー情報を抽出するためにも使用できます。詳細: Batch

Service プロパティ

Service には 1 つのプロパティがあります: BaseAddress。

BaseAddress プロパティ

このプロパティは、Config.Url で設定された基本 URL を返します。この URL は、BatchRequest クラスをインスタンス化するとき、および絶対 URL が必要な場合に相対URLに追加するときに必要になります。

Config クラス

Config クラスには、次の表に示すように、アプリケーションの動作を制御するプロパティが含まれています。

Property	タイプ	Description
`GetAccessToken`	`Func<Task<string>>`	アクセストークンを返すためにクライアントアプリケーションによって提供される関数。
`Url`	`string?`	環境の基本 URL。例: `https://org.api.crm.dynamics.com`
`CallerObjectId`	`Guid`	偽装に適用する SystemUser.ActiveDirectoryGuid 値。デフォルトは Guid.Empty です詳細情報: Web API を使用して別のユーザーを偽装する
`TimeoutInSeconds`	`ushort`	タイムアウトまでの待機時間。既定値は 120 秒です。
`MaxRetries`	`byte`	サービス保護制限が発生したときに再試行する最大回数。既定値は 3 です。
`Version`	`string`	使用するサービスのバージョン。既定は `v9.2`
`DisableCookies`	`bool`	データの一括読み込みシナリオでパフォーマンスを向上させるために Cookie を無効にするかどうか。詳細: サーバーの親和性

EntityReference クラス

EntityReference クラスは Dataverse テーブルのレコードをへの参照を表します。 OData は URL でリソースを識別します。 EntityReference は、URL のプロパティの作成とアクセスを簡単にするメソッドを提供します。

EntityReference コンストラクター

次のコンストラクターを使用して、 EntityReference をインスタンス化します。

EntityReference(string entitySetName, Guid? ID)

EntitySetName と Guid を使用してエンティティ参照を作成します。

EntityReference(string uri)

絶対または相対 URL を解析して、代替キーを使用する URL を含むエンティティ参照を作成します。

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

このコンストラクターを使用して、代替キーを使用してエンティティ参照をインスタンス化します。

注意

キー値は文字列値である必要があります。これにより、他の型が適切な文字列に変換されることはありません。

EntityReference プロパティ

EntityReference には、次の公開プロパティがあります。

Property	タイプ	Description
`Id`	`Guid?`	代替キーを使用しない場合のレコードの主キー値。
`KeyAttributes`	`Dictionary<string, string>`	URL で使用される代替キー値を表す文字列値。
`SetName`	`string`	エンティティ型の `EntitySetName`。
`Path`	`string`	レコードへの相対 URL。

EntityReference メソッド

EntityReference には、次の公開メソッドがあります。どちらもパラメーターを必要としません。

メソッド名	返り値の種類	説明設定
`AsODataId`	`string`	OData 関数の URL 内のレコードへのパラメーター参照として使用するために書式設定された文字列を返します。
`AsJObject`	`JObject`	OData アクション内のレコードへのパラメーター参照として使用できる `JObject` を返します。

エラークラス

ODataError、Error、ODataException は、サービスから返されたエラーを逆シリアル化するために使用されるクラスです。彼らと直接協力する必要はありません。

ServiceException

ServiceException は、サービスによって返されたエラーのプロパティを含む Exception クラスです。 ParseError メソッドを使用し、この例外のインスタンスを取得します。

拡張

WebApiService は、.NET 型の拡張メソッドが 1 つあります。

HttpResponseMessage As<T>

この拡張機能は、T が HttpResponseMessage から派生した T のインスタンスをインスタンス化し、HttpResponseMessage のプロパティを派生クラスにコピーします。 Service SendAsync<T> Method はこのメソッドを使用しますが、個別に使用することもできます。たとえば、バッチリクエストクラスを使うとき、BatchResponse.HttpResponseMessages 内の項目は HttpResponseMessage タイプです。この拡張機能を使用して、それらを適切な派生クラスに変換し、プロパティへのアクセスを容易にすることができます。

[メッセージ]

Messages フォルダーには、HttpRequestMessage または HttpResponseMessage を継承するクラスが含まれています。

これらのクラスは、どの Dataverse 環境でも使用できる OData 操作に対応する、要求と応答の再利用可能な定義を提供します。

これらのクラスは、これらの型から派生することなく、HttpRequestMessage と HttpResponseMessage を使用して適用できる特定の操作の例も提供します。

アプリケーション内では、同じパターンを使用して、環境内のカスタム API を表すなど、カスタムメッセージを作成することもできます。これらはモジュールクラスであり、WebAPIService.Messages フォルダーに含める必要はありません。

たとえば、Web API 関数とアクションのサンプル (C#) は、カスタム API を含むソリューションがインストールされるまで、Dataverse に含まれていないカスタム API を使用します。このメッセージを使用するための対応するクラスの定義は、このメッセージを使用するサンプルアプリケーションにあります。

*要求クラス

これらのクラスには通常、操作を実行するために必要なデータが含まれる HttpRequestMessage パラメータをインスタンス化するコンストラクタがあります。必要に応じて、個別のプロパティを持つことができます。

このパターンの最もシンプルな例は、WhoAmIRequest クラスです。

namespace PowerApps.Samples.Messages
{
    /// <summary>
    /// Contains the data to perform the WhoAmI function
    /// </summary>
    public sealed class WhoAmIRequest : HttpRequestMessage
    {
        /// <summary>
        /// Initializes the WhoAmIRequest
        /// </summary>
        public WhoAmIRequest()
        {
            Method = HttpMethod.Get;
            RequestUri = new Uri(
                uriString: "WhoAmI", 
                uriKind: UriKind.Relative);
        }
    }
}

これらのクラスの名前は通常、Dataverse SDK Microsoft.Xrm.Sdk.Messages Namespace でこのクラスと調節しますが、これらの操作に限定されません。 Web API は、例えば、CreateRetrieveRequest レコードを作成し、それを取得するメッセージである、SDK では実行できないいくつかの操作を実行するために提供されます。 Dataverse SDKは、単一の要求でこの機能を提供しません。

*応答クラス

*リクエストクラスは値を返すとき、対応する *返されたプロパティにアクセスするための応答クラスがあります。もし *返品のリクエスト 204 No Content の場合、操作は HttpResponseMessage を返しますが、派生クラスはありません。 SendAsync メソッドを使用して、これらの要求を送信します。

*応答クラスは、HttpResponseMessage Headers または Content プロパティにアクセスし、それらを解析して、操作によって返される複合型へのアクセスを提供する型付きプロパティを提供します。

WhoAmIResponse クラスは例です。このクラス内で、WhoAmIResponse ComplexType のプロパティを抽出するために必要なすべてのコードを見つけることができます。

using Newtonsoft.Json.Linq;

namespace PowerApps.Samples.Messages
{
    // This class must be instantiated by either:
    // - The Service.SendAsync<T> method
    // - The HttpResponseMessage.As<T> extension in Extensions.cs

    /// <summary>
    /// Contains the response from the WhoAmIRequest
    /// </summary>
    public sealed class WhoAmIResponse : HttpResponseMessage
    {

        // Cache the async content
        private string? _content;

        //Provides JObject for property getters
        private JObject _jObject
        {
            get
            {
                _content ??= Content.ReadAsStringAsync().GetAwaiter().GetResult();

                return JObject.Parse(_content);
            }
        }

        /// <summary>
        /// Gets the ID of the business to which the logged on user belongs.
        /// </summary>
        public Guid BusinessUnitId => (Guid)_jObject.GetValue(nameof(BusinessUnitId));

        /// <summary>
        /// Gets ID of the user who is logged on.
        /// </summary>
        public Guid UserId => (Guid)_jObject.GetValue(nameof(UserId));

        /// <summary>
        /// Gets ID of the organization that the user belongs to.
        /// </summary>
        public Guid OrganizationId => (Guid)_jObject.GetValue(nameof(OrganizationId));
    }
}

これらのクラスは、SendAsync< T> Method または、BatchResponse.HttpResponseMessages プロパティの HttpResponseMessage の中に HttpResponseMessage As< T> の拡張子によって返されます。

バッチ

Batch フォルダーには、OData $batch 要求の送信を管理する 3 つのクラスが含まれています。詳細: Web API を使用してバッチ操作を実行する。

BatchRequest

BatchRequest コンストラクターは、SendAsync<T> メソッドで使用できる HttpRequestMessage を初期化し、バッチで要求を送信します。コンストラクターでは、Service.BaseAddress 値をパラメーターとして渡す必要があります。

BatchRequest には、次のプロパティがあります。

Property	タイプ	説明設定
`ContinueOnError`	`Bool`	エラーが発生したときにバッチ操作を続行するかどうかを制御します。
`ChangeSets`	`List<ChangeSet>`	バッチに含まれる 1 つ以上の変更セット。
`Requests`	`List<HttpRequestMessage>`	`ChangeSet` の外に送信される 1 つ以上の `HttpMessageRequest`。

ChangeSets または Requests が設定されると、HttpMessageContent にカプセル化され、要求の Content に追加されます。プライベート ToMessageContent メソッドは、ヘッダーに必要な変更を適用し、ChangeSets と Requests の両方のプロパティの HttpMessageContent を返します。

Changeset

変更セットは、トランザクション内で完了する必要がある要求のグループを表します。

次の 1 つのプロパティが含まれます:

Property	タイプ	説明設定
`Requests`	`List<HttpRequestMessage>`	トランザクション内で実行される 1 つ以上の `HttpMessageRequest`。

BatchResponse

BatchResponse には 1 つのプロパティがあります:

Property	タイプ	説明設定
`HttpResponseMessages`	`List<HttpResponseMessage>`	`$batch` 演算からの応答。

BatchResponse には、個々の HttpResponseMessage に返された MultipartContent を解析するために、HttpResponseMessages プロパティゲッターによって使用されるプライベート ParseMultipartContent メソッドがあります。

返された HttpResponseMessage インスタンスの型プロパティにアクセスするには、HttpResponseMessage As<T> 拡張メソッドを使用します。

メソッド

頻繁に実行される操作の場合、Methods フォルダーには、Service クラスの拡張機能が含まれます。これらのメソッドを使用すると、対応する *Request クラスを 1 行で使用できます。

次のメソッドが含まれます:

メソッド	返り値の種類	説明設定
`Create`	`Task<EntityReference>`	新しいレコードを作成します。
`CreateRetrieve`	`Task<JObject>`	新しいレコードを作成して取得します。
`Delete`	`Task`	レコードを削除します。
`FetchXml`	`Task<FetchXmlResponse>`	FetchXml クエリの結果を取得します。要求が `$batch` を使用して `POST` で送信され、`GET` で送信される長い URL が制限を超える可能性がある問題を緩和します。
`GetColumnValue<T>`	`Task<T>`	テーブル行から単一の列値を取得します。
`Retrieve`	`Task<JObject>`	レコードを取得します。
`RetrieveMultiple`	`Task<RetrieveMultipleResponse>`	複数のレコードを取得します。
`SetColumnValue<T>`	`Task`	テーブル行の列の値を設定します。
`Update`	`Task`	レコードを更新します。
`Upsert`	`Task<UpsertResponse>`	レコードに対して Upsert を実行します。

サンプルアプリケーション内で使用する WebAPIService、操作が次の場所で見つかったAPIを表していない場合 Dataverse デフォルトでは、メソッドはアプリケーション内ではなくアプリケーション内で定義されます。 WebAPIService。

たとえば、Web API 関数とアクションのサンプル (C#) は、カスタム API を含むソリューションがインストールされるまで、Dataverse に含まれていないカスタム API を使用します。このメソッドの定義は、使用するサンプルアプリケーションにあります: FunctionsAndActions/Methods/IsSystemAdmin.cs

Types

Types フォルダーには、メッセージのパラメーターまたは応答プロパティとして必要な ComplexTypes または EnumTypes に対応するクラスまたは列挙型が含まれています。

Metadata

Metadata フォルダーには、Dataverse スキーマ定義で動作する操作に固有の Messages と Types が含まれています。これらのクラスには、複合型を返す多くのプロパティが含まれることがよくあります。これらのタイプは、Web API テーブルスキーマ操作サンプル (C#) で使用されます。

参照

Web API 基本操作のサンプル (C#)
Web API クエリデータのサンプル (C#)
Web API 条件付き演算サンプル (C#)
Web API 機能およびアクションのサンプル (C#)
Web API テーブルスキーマ操作サンプル (C#)
Web API WebApiService の並列演算のサンプル (C#)
TPL データフローコンポーネントを使用した Web API 並列演算のサンプル (C#)

注意

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

次の方法で共有

WebAPIService クラスライブラリ (C#)

コード

クラスリスト

Service クラス

サービスメソッド

SendAsync メソッド

SendAsync<T> メソッド

ParseError メソッド

Service プロパティ

BaseAddress プロパティ

Config クラス

EntityReference クラス

EntityReference コンストラクター

EntityReference(string entitySetName, Guid? ID)

EntityReference(string uri)

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

EntityReference プロパティ

EntityReference メソッド

エラークラス

ServiceException

拡張

HttpResponseMessage As<T>

[メッセージ]

*要求クラス

*応答クラス

バッチ

BatchRequest

Changeset

BatchResponse

メソッド

Types

Metadata

参照

その他のリソース

次の方法で共有

WebAPIService クラス ライブラリ (C#)

コード

クラス リスト

Service クラス

サービス メソッド

SendAsync メソッド

SendAsync<T> メソッド

ParseError メソッド

Service プロパティ

BaseAddress プロパティ

Config クラス

EntityReference クラス

EntityReference コンストラクター

EntityReference(string entitySetName, Guid? ID)

EntityReference(string uri)

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

EntityReference プロパティ

EntityReference メソッド

エラー クラス

ServiceException

拡張

HttpResponseMessage As<T>

[メッセージ]

*要求クラス

*応答クラス

バッチ

BatchRequest

Changeset

BatchResponse

メソッド

Types

Metadata

参照

その他のリソース

WebAPIService クラスライブラリ (C#)

クラスリスト

サービスメソッド

エラークラス