.NET 用 SDK でメッセージを使用する
Dataverse のすべてのデータ操作は メッセージ として定義され、これらのメッセージの定義は Dataverse に保存されることを理解することが重要です。
すべてのメッセージには次のものがあります。
- 一意の名前
- 入力パラメーターのコレクション
- 出力パラメーターのコレクション
次のセクションで説明するように、SDK for .NET でメッセージを使用する方法は 3 つあります。
メソッド | Description |
---|---|
OrganizationRequest クラスと OrganizationResponse クラス | SDK の Request クラスと Response クラスがない場合は、これらのクラスを使用します。 メッセージ名と入力および出力パラメーターの詳細がわかっている場合は、SDK要求および応答クラスを生成するよりも、この方法を使用することをお勧めします。 |
SDK リクエストおよびレスポンス クラス | これらのクラスを使用することは、メッセージを使用する最も一般的な方法です。 多くのメッセージには、SDK for .NET で既にクラスが定義されています。 カスタムアクションの場合、クラスを生成できます。 |
IOrganizationService メソッド | IOrganizationService は、一般的なデータ操作のメソッドをいくつか提供します。 これらのメソッドは、最も一般的なデータ操作を実行するための最も迅速で簡単な方法です。 |
OrganizationRequest クラスと OrganizationResponse クラス
注意
OrganizationRequest クラスと OrganizationResponse クラスは、Dataverse でメッセージを使う最も一般的な方法ではありません。 ただし、これらのクラスは、メッセージがどのように実装されるかを示しています。 これを理解することは、 Dataverse 作業のその他の部分がどのように機能するかを理解するために重要です。
SDK Request クラスと Response クラスなしでメッセージを使用できます。
OrganizationRequest クラスを使用します。
- OrganizationRequest.RequestName の設定
- OrganizationRequest.Parameters コレクション内の項目を設定します
IOrganizationService.Execute メソッドを使用してリクエストを送信すると、OrganizationResponse インスタンスが返されます。
OrganizationResponse.Results コレクションの項目には結果が含まれています。
たとえば、アカウント レコードを作成する場合は、次のようにします。
public static Guid OrganizationRequestExample(IOrganizationService service) {
// Instantiate an Entity instance of type 'account'
var account = new Entity("account");
account["name"] = "Test account";
// Instantiate a collection of parameters with one item 'Target',
// set to the account entity instance
ParameterCollection parameters = new ParameterCollection
{
{ "Target", account }
};
// Instantiate an OrganizationRequest instance setting the
// RequestName and Parameters
OrganizationRequest request = new OrganizationRequest()
{
RequestName = "Create",
Parameters = parameters
};
// Send the request using the IOrganizationService.Execute method
OrganizationResponse response = service.Execute(request);
// Parse the output parameter 'id' from the Results
return (Guid)response.Results["id"];
}
この方法を使用してアカウント レコードを作成するには、次のことを知っておく必要があります。
- メッセージの名前:
Create
。 - 各入力パラメータの名前とデータ型:
Target
という名前の単一パラメータで、エンティティ です。 - 各出力パラメータの名前とデータ型:
id
という名前の単一パラメータで、Guid です。
この情報は Dataverse に保存されます。 SdkMessage テーブル には、すべてのメッセージに関する情報が含まれています。
Dataverse 入力パラメータと出力パラメータに関する情報をプライベート テーブルで管理します。 SDK の Request クラスと Response クラスを使用するという簡単な方法があるため、取得する必要はありません。
SDK リクエストおよびレスポンス クラス
SDK Request クラスと Response クラスは、OrganizationRequest クラスと OrganizationResponse クラスを使用する複雑さを軽減します。 メッセージの名前と入力パラメータと出力パラメータはクラスに含まれているため、それらを知る必要はありません。
SDK for .NET には、次の名前空間に共通の Dataverse メッセージの定義が含まれています。
Namespace | Description |
---|---|
Microsoft.Xrm.Sdk.Messages | 一般的なデータ操作のメッセージと、メタデータとも呼ばれるスキーマ データの作成と変更に使用されるメッセージ。 |
Microsoft.Crm.Sdk.Messages | アプリケーション ライフサイクル管理 (ALM) とアプリをサポートする特別な機能をサポートするビジネス ロジックと操作のメッセージ。 この名前空間の一部のメッセージは、Microsoft Dynamics 365 ビジネス アプリケーションでのみ見られる機能をサポートしています。 |
これらのクラスには、すべての入力パラメーターと出力パラメーターのプロパティが含まれています。
*Request
で終わるクラスには、入力パラメータのプロパティが含まれています。これらのクラスは OrganizationRequest クラスから継承されます。
*Response
で終わるクラスには、出力パラメータのプロパティが含まれています。これらのクラスは OrganizationResponse クラスから継承されます。
たとえば、レコードを作成するには、Microsoft.Xrm.Sdk.Messages.CreateRequest クラスを使用して要求を準備できます。 IOrganizationService.Execute を使用してリクエストを送信すると、結果は Microsoft.Xrm.Sdk.Messages.CreateResponse クラスインスタンスの形式になります。
次の例では、Microsoft.Xrm.Sdk.Messages.CreateRequest クラスを、アカウント エンティティ用に生成された事前バインド クラスと共に使用します。
public static Guid CreateRequestExample(IOrganizationService service)
{
// Instantiate an Account using generated early-bound class
var account = new Account
{
Name = "Test account"
};
// Instantiate a CreateRequest
var request = new CreateRequest
{
// Set the Target property
Target = account
};
// Send the request using the IOrganizationService.Execute method
// Cast the OrganizationResponse into a CreateResponse
var response = (CreateResponse)service.Execute(request);
// Return the id property value
return response.id;
}
カスタムアクションのクラスの生成
SDK にクラスがない他のメッセージがあります。 たとえば、頻繁にインストールされるソリューションには、カスタム アクション (カスタム API またはカスタム プロセス アクション) として定義された新しいメッセージ定義が含まれています。 独自のメッセージを作成することを学習します
開発者は、Power Platform CLI pac modelbuilder ビルド コマンド を使用して、環境内で見つかったメッセージの *Request
クラスや *Response
クラスを生成できます。 --generateActions パラメータを使用して、*Request
クラスと *Response
クラスを生成します。 .NET 用 SDK のアーリーバウンド クラスの生成についての詳細を学習します
要求のオプション パラメーターを渡す
メッセージへの地区別な動作を適用するために渡すことができるいくつかのオプションのパラメーターがあります。 オプションのパラメーターを使用する場合、IOrganizationService メソッドは使用できません。 SDK Request クラスまたは OrganizationRequest クラスを使用する必要があります。
詳細: レポートでパラメーターを使用する
IOrganizationService メソッド
IOrganizationService.Execute メソッドに加えて、IOrganizationService インターフェイス は次のメソッドも実装する必要があることを指定します。 これらのメソッドは、対応する Request クラスと Response クラスをカプセル化します。
これらのメソッドを使用すると、これらの操作をより少ないコード行で簡単に実行できます。 次の例は、IOrganizationService.Create メソッドを使って取引先企業レコードを作成します。
public static Guid CreateMethodExample(IOrganizationService service)
{
// Instantiate an Account using generated early-bound class
var account = new Account
{
Name = "Test account"
};
// Use the Create method to get the id of the created account.
return service.Create(account);
}
ご覧のとおり、一般的なデータ操作は、IOrganizationService メソッドやその他のメッセージは、SDK アセンブリの Request クラスと Response クラスで使いやすくなったり、ツールで生成されたりすることができます。 ほとんどの場合、基礎となる OrganizationRequest と OrganizationResponse クラスを使用する必要はありませんが、特にカスタム API とプラグインを使用する場合は、メッセージを使用するために使用できるさまざまなオプションを理解することが重要です。
プラグインのメッセージの操作
プラグインでの操作を記述するデータは、IExecutionContext.InputParameters と IExecutionContext.OutputParameters の形式です。
イベント パイプラインの main
操作前の PreValidation
と PreOperation
ステージで、IExecutionContext.InputParameters は、OrganizationRequest.Parameters を含みます。
カスタム API を使用すると、プラグインは、IExecutionContext.InputParameters を読み込んで、main
操作段階の一環として IExecutionContext.OutputParameters を設定するロジックを含めます。
main
操作ステージの後に、PostOperation
ステージの、IExecutionContext.OutputParameters は OrganizationResponse.Results を含みます。
メッセージの構造を知ることはプラグイン内で確認や変更が必要なデータがどこにあるか理解するのに役立ちます。
詳細情報:
プライベート メッセージ
Microsoft Dataverse には、非 Microsoft の開発者が使用することを意図していないいくつかのメッセージが含まれています。 これらのメッセージは通常、機能機能を有効にするためにマイクロソフトによって追加されますが、カスタム API 機能を備えた 非 Microsoft のソリューションによって追加することもできます。 プライベート メッセージは、SdkMessage.IsPrivate プロパティによって示されます。
注意事項
カスタム API として作成した場合を除き、プライベート メッセージを使用しないでください。 メッセージを非公開としてマークすることにより、ソリューションの発行者は、メッセージを使用する他のアプリをサポートしていないことを明示的に呼びかけています。 ソリューション発行者は、いつでもメッセージを削除したり、重大な変更を導入したりする場合があります。 ソリューション発行者以外によるこれらのメッセージの使用はサポートされていません。 プラグインからのプライベート メッセージの呼び出しはサポートされていません。
詳細: カスタム API の作成と使用
メッセージのテーブル サポート
一部のメッセージは、複数のテーブルで使用できます。 たとえば、Create
、Update
、Delete
のメッセージはほとんどのテーブルで使用できますが、テーブルによってはすべての共通メッセージをサポートしていない場合があります。
この情報は、SdkMessageFilter テーブル に保存されています。 このテーブルを照会して、テーブルにメッセージを使用できるかどうかを判断できます。
この静的メソッドを使用して、テーブルを操作できるメッセージの名前のリストを取得します。
/// <summary>
/// Write the names of messages for a table to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="tableName">The logical name of the table</param>
static void OutputTableMessageNames(IOrganizationService service, string tableName)
{
var query = new QueryExpression(entityName: "sdkmessagefilter")
{
Criteria =
{
Conditions =
{
new ConditionExpression(
attributeName:"primaryobjecttypecode",
conditionOperator: ConditionOperator.Equal,
value: tableName)
}
},
// Link to SdkMessage to get the names
LinkEntities =
{
new LinkEntity(
linkFromEntityName:"sdkmessagefilter",
linkToEntityName: "sdkmessage",
linkFromAttributeName: "sdkmessageid",
linkToAttributeName: "sdkmessageid",
joinOperator: JoinOperator.Inner)
{
EntityAlias = "sdkmessage",
Columns = new ColumnSet("name"),
LinkCriteria =
{
Conditions =
{
// Don't include private messages
new ConditionExpression("isprivate", ConditionOperator.Equal, false)
}
}
}
}
};
EntityCollection results = service.RetrieveMultiple(query);
foreach (var entity in results.Entities)
{
Console.WriteLine(((AliasedValue)entity["sdkmessage.name"]).Value);
}
}
このメソッドの設定を使用する場合、tableName
パラメータを account
に設定すると、次のメッセージ名を含む結果が得られます。
出力:
Assign
Create
Delete
GrantAccess
Merge
ModifyAccess
Retrieve
RetrieveMultiple
RetrievePrincipalAccess
RetrieveSharedPrincipalsAndAccess
RevokeAccess
SetState
SetStateDynamicEntity
Update
注意
これらのメッセージの一部は非推奨です。 SetState
と SetStateDynamicEntity
はまだ存在しますが、代わりに Update
を使用する必要があります。
テーブルのメッセージ サポート
一部のメッセージは、特定のテーブルでのみ使用できます。 たとえば、RetrieveUnpublishedMultiple
メッセージは、公開できるデータを含む特定のテーブル セットでのみ使用できます。
この情報は、SdkMessageFilter テーブル に保存されています。 このテーブルを照会して、テーブルが特定のメッセージに対して使用できるかどうかを判断できます。
この静的メソッドを使用して、メッセージと使用できるテーブルの名前のリストを取得します。
/// <summary>
/// Write the names of tables for a message to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="messageName">The name of the message</param>
static void OutputTablesForMessage(IOrganizationService service, string messageName) {
var query = new QueryExpression(entityName: "sdkmessage")
{
Criteria = {
Conditions =
{
new ConditionExpression(
attributeName: "name",
conditionOperator: ConditionOperator.Equal,
value: messageName)
}
},
LinkEntities = {
new LinkEntity(
linkFromEntityName:"sdkmessage",
linkToEntityName: "sdkmessagefilter",
linkFromAttributeName: "sdkmessageid",
linkToAttributeName: "sdkmessageid",
joinOperator: JoinOperator.Inner)
{
EntityAlias = "sdkmessagefilter",
Columns = new ColumnSet("primaryobjecttypecode"),
}
}
};
EntityCollection results = service.RetrieveMultiple(query);
List<string> names = new List<string>();
foreach (var entity in results.Entities)
{
names.Add(((AliasedValue)entity["sdkmessagefilter.primaryobjecttypecode"]).Value as string);
}
names.Distinct().ToList().ForEach(name => Console.WriteLine(name));
}
このメソッドの設定を使用する場合、messageName
パラメータを RetrieveUnpublishedMultiple
に設定すると、次のテーブル名を含む結果が得られます。
出力:
organizationui
systemform
savedquery
savedqueryvisualization
sitemap
hierarchyrule
appmodule
appconfig
appconfiginstance
webresource
mobileofflineprofile
mobileofflineprofileitem
mobileofflineprofileitemassociation
navigationsetting
appelement
appsetting
teammobileofflineprofilemembership
usermobileofflineprofilemembership
注意
特定のメッセージでは、
DeletedEntity for objectTypeCode=11478
やnew_system_donotuseentity_rp53fd1p1ekxpa_t12_b71d6344c5
などのプレースホルダー値が返される場合があります。 これらは有効なテーブル名ではありません。 これらの値を無視します。このクエリは、プライベート テーブル も返します。 前の例では:
organizationui
、hierarchyrule
、appelement
、そしてappsetting
はプライベート テーブルであるため、使用はサポートされていません。
参照
.NET 用 SDK を使用したテーブル操作
メッセージを非同期に実行するために ExecuteAsync を使用します
単一のデータベース トランザクションでメッセージを実行する
.NET 用 SDK を使用して複数の要求を実行する
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。