独自のアクションを作成する

2025-05-22

Dynamics 365 Customer Engagement (on-premises) の機能を拡張するには、 アクションと呼ばれるカスタムメッセージを作成します。これらのアクションには要求/応答クラスが関連付けられ、Web API アクションが生成されます。通常、アクションは、新しいドメイン固有の機能を組織の Web サービスに追加したり、複数の組織の Web サービスメッセージ要求を 1 つの要求に結合したりするために使用されます。たとえば、サポートコールセンターでは、Create、Assign、および Setstate メッセージを 1 つの新しいエスカレートメッセージに結合できます。

アクションのビジネスロジックは、ワークフローを使用して実装されます。アクションを作成すると、関連するリアルタイムワークフローが、実行パイプラインのステージ 30 (コア操作) で実行するように自動的に登録されます。リアルタイムワークフローの詳細については、「ワークフロータイプ」を参照してください。

アクションは Dynamics 365 for Customer Engagement の両方でサポートされていますが、コードでのアクションの作成 (XAML を使用) は、設置型と IFD の展開でのみサポートされています。オンラインのお客様は、Web アプリケーションで対話式にアクションを作成する必要があります。

アクション定義について

アクションは、リアルタイムワークフローと同様に、 Workflow エンティティレコードを使用して定義されます。アクションとは何か、どのように機能するかについて、いくつかの重要なポイントを次のリストに示します。

単一のエンティティに関連付けることも、グローバル (特定のエンティティに関連付けられない) にすることもできます。
イベント実行パイプラインのコア操作ステージ30で実行されます。
イベント実行パイプラインの操作前ステージと操作後ステージに登録されたプラグインの呼び出しをサポートします。
操作前または操作後のステージでプラグインを登録できるのは、アクションのステータスが「アクティブ化」のときだけです。
Web API または organization.svc エンドポイントと organization.svc/web エンドポイントを通じて利用できます。
JavaScript Web リソースを使用して実行できます。詳細: JavaScript Web リソースを使用してアクションを実行する
常に呼び出し元のユーザーのセキュリティコンテキストで実行されます。
アクションにプラグインステップが登録されている間は、レコードを削除できません。
オプションで、構成設定を使用して、現在のデータベース・トランザクションに参加できます。
実行がユーザー、部署、または組織に制限されているスコープはサポートされていません。アクションは常に組織のスコープで実行されます。
入力引数と出力引数をサポートします。
データ変更の監査をサポートします。
オフラインクライアントではサポートされていません。
Web サービス・メソッド呼び出しによって呼び出すことができます。
ワークフローから直接呼び出すことができます。

必要なアクセス許可

アクションのリアルタイムワークフローをアクティブ化して実行できるようにするには、Activate Real-time Processes (prvActivateSynchronousWorkflow) という名前のセキュリティ権限が必要です。これは、ワークフローの作成に必要な権限に加えて行われます。

コードを使用してアクションを作成する

通常、アクションは、Web アプリケーションの対話型ワークフローデザイナーを使用してカスタマイザーによって実装されます。ただし、開発者は SDK 呼び出しを使用してアクションを実装し、必要に応じてオンプレミスまたは IFD サーバーにデプロイできます。

アクションに使用されるワークフローエンティティ属性については、次の表で説明します。リアルタイムワークフローのサンプルコードについては、「コードでリアルタイムワークフローを作成する」を参照してください。

ワークフロー属性	説明
`Category`	`WorkflowCategory.CustomOperation` に設定します。
`SyncWorkflowLogOnError`	`true`すると、エラーは `ProcessSession` レコードに記録されます。非同期ワークフローとは異なり、リアルタイムのワークフロー実行は `System Job` レコードに記録されません。
`Mode`	使用されません。
`IsTransacted`	アクションがデータベーストランザクションに参加する場合は `true` に設定し、それ以外の場合は `false`に設定します。既定値は `true` です。
`UniqueName`	操作の一意の名前です。名前は、発行元のプレフィックス + "_" + 一意の名前で構成されます。
`Xaml`	アクションのリアルタイムワークフローを定義する XAML コードに設定します。別の既存のリアルタイムワークフローを参照する方法はありません。

入力引数と出力引数を追加する

アクションは、 DynamicActivityProperty 型を使用してワークフローに追加できる入力引数と出力引数をサポートします。これらの引数をアクションのワークフローに追加すると、そのアクションに関連付けられたメッセージ要求クラスと応答クラスのプロパティになります。たとえば、次の例は、2 つの入力引数と 1 つの出力引数の C# コードと XAML コードを示しています。

DynamicActivityProperty inputProperty1 = new DynamicActivityProperty     { Name = "Subject", Type = typeof(InArgument<string>) };  
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty     { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };  
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty     { Name = "Output", Type = typeof(OutArgument<string>) };  
  
inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));  
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));  
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));  
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));  
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));  
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));  
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));

<x:Property Name="Subject"  
            Type="InArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="True" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The subject " />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="EntityCollection"  
            Type="InArgument(mxs:EntityCollection)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The entity collection" />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="Output"  
            Type="OutArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The output" />  
  <mxsw:ArgumentDirectionAttribute Value="Output" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>

プロパティに使用する名前は、コード生成でこれらの名前が要求または応答のプロパティとして定義されるため、引数の名前と一致している必要があります。

入力引数と出力引数でサポートされている引数の型を次の表に示します。

.NET 型	引数の型
System.Int32	整数
System.String	糸
EntityReference	EntityReference
Entity	エンティティ
EntityCollection	エンティティコレクション
System.DateTime	日付と時間
System.Double	浮く
System.Decimal (システム・デシマル)	10 進法
Money	お金
System.Boolean	ボーリアン
OptionSetValue	ピックリスト

サポートされている引数属性を次の表に示します。

引数属性	説明
ArgumentRequiredAttribute	引数が必須かどうかを示します。
ArgumentDirectionAttribute	引数の方向が入力か出力かを示します。
ArgumentDescriptionAttribute	引数の説明を指定します。
ArgumentEntityAttribute	エンティティを渡したい場合に使用します。
ArgumentTargetAttribute	この属性は、自動的に生成または追加されます。これは、ワークフローが実行されるプライマリエンティティを指します。この属性は、グローバルアクションではオプションです。

配布用のアクションをパッケージ化する

アクションを配布して Dynamics 365 Customer Engagement (on-premises) 組織にインポートできるようにするには、アクションを Customer Engagement ソリューションに追加します。これは、Web アプリケーションを使用して Settings>Customizations>Solutions に移動することで簡単に実行できます。また、ソリューションを作成するコードを記述することもできます。ソリューションの詳細については、「拡張機能をパッケージ化して配布する」を参照してください。

操作用の事前バインド型を生成する

CrmSvcUtil ツールを使用すると、アクションの要求クラスと応答クラスを生成して、アプリケーションコードに含めることができます。ただし、これらのクラスを生成する前に、必ずアクションをアクティブにしてください。

CrmSvcUtil.exeをダウンロードするには、 Dataverse 開発ツールを参照してください。

次のサンプルは、Customer Engagement のオンプレミスインストールのコマンドラインからツールを実行するための形式を示しています。インストール・システムのパラメーター値を指定します。

CrmSvcUtil.exe /url:https://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

次のサンプルは、Dynamics 365 for Customer Engagement を使用してコマンドラインからツールを実行するための形式を示しています。アカウントとサーバーに適したパラメータ値を指定します。

CrmSvcUtil.exe /url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

/generateActions パラメーターの使用に注意してください。詳細: コード生成ツールを使用した事前バインドエンティティクラスの作成 (CrmSvcUtil.exe)

事前バインド型または遅延バインド型を、アクションに対して生成された要求クラスと応答クラスと共に使用できます。

Web API を使用してアクションを実行する

新しいアクションは、作成時に Web API に作成されます。アクションがエンティティのコンテキストで作成されている場合、アクションはそのエンティティにバインドされます。それ以外の場合は、バインドされていないアクションです。詳細: Web API アクションの使用を参照してください。

JavaScript Web リソースを使用してアクションを実行する

アクションは、システムアクションと同様にWeb APIを使用して実行できます。詳細: Xrm.WebApi.online.execute

組織サービスを使用してアクションを実行する

マネージドコードを使用して組織の Web サービスを使用してアクションを実行するには、次の手順に従います。

CrmSvcUtil ツールを使用して生成した事前バインド型ファイルをアプリケーションのプロジェクトに含めます。
アプリケーションコードで、アクションの要求をインスタンス化し、必要なプロパティを設定します。
Execute を呼び出し、リクエストを引数として渡します。

アプリケーションコードを実行する前に、アクションがアクティブになっていることを確認してください。そうしないと、実行時エラーが発生します。

プロセスを使用してアクションを実行する

アクションは、ワークフロー、ダイアログ、またはその他のプロセスアクションから実行できます。アクティブ化されたカスタムアクションは、Webアプリケーションプロセスフォームの「ステップの追加」ドロップダウンで「アクションの実行」項目を選択することで、プロセスで使用できます。ステップがプロセスに追加されたら、ステップに用意されている 「アクション 」リストから新しいカスタムアクション (または任意のアクション) を選択できます。ステップで [プロパティの設定 ] を選択して、カスタムアクションに必要な入力パラメーターを指定します。

注

カスタムアクションにサポートされていないパラメータタイプ (ピックリスト、エンティティ、エンティティコレクションなど) がある場合、カスタムアクションは アクション リストに表示されません。

プロセスからアクションを実行する機能は、Dynamics CRM Online 2015 更新プログラム 1 で導入されました。

既存の Depth プラットフォームチェックにより、無限ループが発生しないことが保証されます。深さの制限の詳細については、「 MaxDepth」を参照してください。

長時間実行されるアクションに注意する

アクションのリアルタイムワークフローのステップの 1 つがカスタムワークフローアクティビティである場合、そのカスタムワークフローアクティビティは分離されたサンドボックスランタイム環境内で実行され、サンドボックスプラグインの管理方法と同様に 2 分間のタイムアウト制限が適用されます。ただし、アクション自体にかかる時間に制限はありません。さらに、アクションがトランザクションに参加している場合、ロールバックが有効になっている場合は、SQL Server のタイムアウトが適用されます。

ヒント

ベストプラクティスの推奨事項は、実行時間の長い操作は、.NET の非同期プロセスまたはバックグラウンドプロセスを使用して Dynamics 365 Customer Engagement (on-premises) の外部で実行することです。

こちらも参照ください

リアルタイムワークフローの作成
 ガイド付きプロセスにダイアログを使用する
 イベント実行パイプライン
 ビジネスプロセスを自動化するワークフローの記述
 システムのカスタマイズ