Execute メソッドでメッセージ (要求クラスおよび応答クラス) を使用する

[アーティクル]
03/04/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

IOrganizationService で最も一般的な操作を実行するためのメソッドを使用できます。共通メソッドに加え、IOrganizationService.Execute メソッドを使用して、メソッドとして公開されていないメッセージを実行できます。Execute メソッドは、メッセージ要求クラスをパラメーターとして使用し、メッセージ応答クラスを返します。メッセージ要求クラスは名前の最後が "Request" で、メッセージ応答クラスは "Response" です。Execute メソッドによってサポートされるブラウザーの詳細については、「組織サービスにおける xRM メッセージ、組織サービスにおける Dynamics 365 メッセージ」を参照してください。IDiscoveryService および IDeploymentService の Web サービスは、同様の実行要求と応答のパターンを使用します。

メッセージ実行フロー

OrganizationRequest は、すべてのメッセージ要求の基本クラスです。この基本クラスを使用すると、メッセージ名と要求のパラメーターコレクションを指定して、任意のメッセージを実行できます。ただし、AssociateRequest などの派生クラスを使用する場合は、要求クラスでプロパティを使用するときにパラメーターコレクションが読み込まれます。

Execute メソッドは、要求の対応する応答クラス、つまり、OrganizationResponse クラスの派生クラスを返します。要求クラスと同様、派生クラスは、結果のパラメーターコレクション内の値ごとにプロパティを持ちます。すべてのメッセージに応答はありますが、多くで応答にはプロパティはありません。 .

メッセージはメタデータで事前に定義され、SDK メッセージエンティティにレコードとして格納されます。メッセージごとに、これがサーバーに接続した状態で動作するか、オフラインアクセス対応 Microsoft Office Outlook 用 Microsoft Dynamics 365 から動作するかを判断できます。この情報は、SdkMessage.Availability 属性にあります。詳細については、「プラグイン登録エンティティ」を参照してください。

このトピックの内容

メッセージにオプションパラメーターを渡す

単一のデータベーストランザクションでメッセージを実行する

バックグラウンドのメッセージを実行する (非同期)

メッセージにオプションパラメーターを渡す

Parameters プロパティに値を追加することによって、オプションパラメーターをメッセージ要求に渡すことができます。一部のパラメーターは、要求クラスの公開プロパティではありません。このようなパラメーターを設定するためには、これらを、Parameters クラスの Request コレクションに設定する必要があります。

使用できるパラメーターを次の表に示します。

Parameter	説明	メッセージ
SolutionUniqueName	操作が適用されるソリューションの一意の名前を指定する String です。詳細については、「ソリューションコンポーネントの依存関係の追跡」を参照してください。	AddPrivilegesRoleRequest CreateRequest DeleteRequest MakeAvailableToOrganizationTemplateRequest UpdateRequest
CalculateMatchCodeSynchronously	このパラメーターを指定する必要はなくなりました。重複の検出に使用される一致コードは、このパラメーターに渡される値に関係なく同期的に計算されます。詳細については、「重複データ検出を実行する」を参照してください。	CreateRequest UpdateRequest
SuppressDuplicateDetection	作成操作または更新操作で、重複データの検出を無効にするために使用する Boolean です。詳細については、「重複データ検出を実行する」を参照してください。	CreateRequest UpdateRequest

次のサンプルは、オプションパラメーターを渡す方法を示しています。

Account target = new Account();
target.Name = "Fabrikam";
CreateRequest req = new CreateRequest();
req.Target = target;
req["SuppressDuplicateDetection"] = true;
req["CalculateMatchCodeSynchronously"] = true;
req["SolutionUniqueName"] = "MySolutionName";
CreateResponse response = (CreateResponse)_service.Execute(req);

単一のデータベーストランザクションでメッセージを実行する

ビジネスアプリケーションでは、システム内の複数のレコードの変更を調整して、すべてのデータの変更が成功したか失敗したかのいずれかになるようにすることが一般的な要件です。データベースの用語では、どれか一つの操作が失敗したときにすべてのデータの変更をロールバックする機能を持つ単一のトランザクションで、複数の操作を実行することとして知られています。

ExecuteTransactionRequest メッセージ要求を使用して、1 つのデータベーストランザクションで、組織のサービス要求を 2 つ以上実行できます。このメッセージを使用するには、Requests コレクションに、トランザクションで実行される組織の要求を 2 つ以上設定します。Responses コレクションで、実行したメッセージ要求ごとに 1 つ、応答のコレクションを戻す場合は、ReturnResponses を true に設定します。Requests コレクションのメッセージ要求は、コレクションに表示されている順序で実行されます。この場合、インデックス 0 の要素が最初に実行されます。この同じ順序は、Responses コレクションで維持されます。

要求のいずれかが失敗し、トランザクションがロールバックされた場合、トランザクション中に完了したデータの変更は取り消されます。また、ExecuteTransactionFault が返されて、エラーを発生した要求メッセージの要求コレクションのインデックスを特定します。

ExecuteMultipleRequest には、1 つまたは複数の ExecuteTransactionRequest インスタンスが格納されていることがあります。ExecuteTransactionRequest インスタンスに、ExecuteTransactionRequest または ExecuteMultipleRequest を含むことはできません。ExecuteMultipleRequest の詳細については、「大量データ負荷でパフォーマンスを向上させる ExecuteMultiple を使用する」を参照してください。

ExecuteTransactionRequest を実行するサンプルコードについては、Sample: Execute multiple requests in transaction を参照してください。

バックグラウンドのメッセージを実行する (非同期)

メッセージ要求の即時実行に加え、Execute を呼び出して、メッセージ要求を渡す場合と同様に、バックグラウンドでメッセージ要求を実行することもできます (非同期)。これにより、サーバーの負荷が少なくなった後までメッセージ実行を延期し、システムのパフォーマンスを改善します。対話型ユーザーは、対象メッセージの実行を、続行可能になるまで待つ必要はありません。これは、実行に数分以上かかるメッセージを処理する場合に特に有効です。

注意

現在、ImportSolutionRequest メッセージのみ ExecuteAsync メッセージで使用できます。

ExecuteAsyncRequest メッセージは、メッセージを非同期で実行する場合に使用します。要求を構成して、引数として要求インスタンスを Execute へ渡します。ExecuteAsyncResponse は、非同期ジョブの ID を返します。 (オプション) ID を使用してジョブをクエリし、現在の状態を確認できます。

また ExecuteMultipleRequest メッセージを使用して複数メッセージを同時に実行できます。これを行うには、ExecuteMultiple のメッセージ要求に 1 つ以上の ExecuteAsync メッセージ要求を追加します。システム全体のパフォーマンスを向上させる調整制限により、非同期に実行する 1 つのメッセージのみを、組織ごとに 1 度に実行できます。ExecuteAsync のメッセージ要求から ExecuteMultiple のメッセージ要求を実行することはできません。ExecuteMultiple メッセージ要求の詳細については、「大量データ負荷でパフォーマンスを向上させる ExecuteMultiple を使用する」を参照してください。

Execute メソッドでメッセージ (要求クラスおよび応答クラス) を使用する

このトピックの内容

メッセージにオプションパラメーターを渡す

単一のデータベーストランザクションでメッセージを実行する

バックグラウンドのメッセージを実行する (非同期)

関連項目

その他のリソース

Execute メソッドでメッセージ (要求クラスおよび応答クラス) を使用する

このトピックの内容

メッセージにオプション パラメーターを渡す

単一のデータベース トランザクションでメッセージを実行する

バックグラウンドのメッセージを実行する (非同期)

関連項目

その他のリソース

メッセージにオプションパラメーターを渡す

単一のデータベーストランザクションでメッセージを実行する