.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 クラスなしでメッセージを使用できます。

  1. OrganizationRequest クラスを使用します。

  2. 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 クラスをカプセル化します。

メソッド Request/Response クラス
Create CreateRequest / CreateResponse
Retrieve RetrieveRequest / RetrieveResponse
RetrieveMultiple RetrieveMultipleRequest / RetrieveMultipleResponse
Update UpdateRequest / UpdateResponse
Delete DeleteRequest / DeleteResponse
Associate AssociateRequest / AssociateResponse
Disassociate DisassociateRequest / DisassociateResponse

これらのメソッドを使用すると、これらの操作をより少ないコード行で簡単に実行できます。 次の例は、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 分かかります。 個人データは収集されません (プライバシー ステートメント)。