ワークフローの拡張機能

[アーティクル]
03/08/2023

Microsoft Dataverseで使用されるワークフローデザイナー内で使用可能なオプションを拡張することができます。これらの拡張機能は、CodeActivity クラスを拡張するクラスを含むアセンブリを追加することで追加されます。これらの拡張機能は一般的に、 ワークフローアセンブリ または ワークフロー活動 と呼ばれます。

ワークフローデザイナー、カスタムアクション、およびダイアログで使用されるデザイナー内のこれらカスタム拡張機能を使用できます (非推奨)。

重要

可能な限り、ビジネスロジックを定義するいくつかの宣言型オプションの 1 つを適用することを最初に検討する必要があります。詳細: Dataverse でビジネスロジックを適用する

宣言型プロセスが要件を満たさない場合、ワークフローの拡張機能を使用します。

ワークフローの拡張機能を作成するとき

ユーザーが既定のプロセス活動を使用して必要な機能を見出せない場合、ワークフロー、ダイアログ、およびアクションのプロセスを作成するために使用するエディターで使用できるように、カスタム活動を追加できます。

既定では、これらのプロセスには、次の表に示すとおりに実行できる活動の共通セットが含まれます。

活動	ワークフロー	目的	[ダイアログ]
データのクエリ			X
値の割り当て		X	X
[レコードの作成]	X	X	X
[レコードの更新]	X	X	X
レコードの割り当て	X	X	X
電子メールの送信	X	X	X
子ワークフローの開始	X	X	X
アクションの実行	X	X
子ダイアログのリンク			X
[状態の変更]	X	X	X
ワークフローの停止	X	X
ダイアログの停止			X

いずれかのユーザー定義アクションを実行するためにアクションの実行活動を使用するか、またはコマンドアクションと呼ばれる次のシステムメッセージを使用できます。

操作	アクション (続き)	アクション (続き)
AddToQueue	AddUserToRecordTeam	RemoveUserFromRecordTeam
SetProcess	SetWordTemplate

Dynamics 365 Sales または Service ソリューションがある場合、ソリューションに応じて他のコマンドアクションを見つけることができます。

操作	アクション (続き)	アクション (続き)
ApplyRoutingRule	CalculateActualValue	CloseOpportunity
GetQuoteProductsFromOpportunity	GetSalesOrderProductsFromOpportunity	LockInvoicePricing
LockSalesOrderPricing	QualifyLead	RemoveUserFromRecordTeam
ResolveIncident	ResolveQuote	Revise
UnlockInvoicePricing	UnlockSalesOrderPricing

詳細:

使用するテクノロジ

.NET Framework アクテビティライブラリを使用して構築したアセンブリを登録することができます。このアセンブリは、Webアプリケーションエディタ内に表示され、プロセスの実行時に呼び出されるカスタムアクティビティを定義します。

ユーザー定義ワークフロー活動では、抽象 CodeActivity クラスから派生した 1 つ以上のクラスを含む .NET Framework アセンブリの作成が必要です。このクラスは、活動実行時に Dataverse プラットフォームにより呼び出される Execute(CodeActivityContext) メソッドを提供します。アセンブリの各クラスは特定の活動を定義します。

ワークフロー活動では、プロセスの設計者に表示される入力パラメータと出力パラメータを定義する必要があり、、ワークフロー活動にデータを渡して、処理された出力を受け取れるように設定する必要があります。クラスを記述する際、これらのパラメーターのプロパティの追加して、.NET 属性で注釈を付けて、Dataverse がデザイナーのいずれかのパラメーターでカスタムワークフロー活動を公開するために使用するメタデータを提供します。

ユーザー定義ワークフロー活動の作成

これらは、Visual Studio を使用してユーザー定義ワークフロー活動を作成するために使用される一般的な手順です。完全な手順ごとの例については、チュートリアル: ワークフロー拡張の作成を参照してください。

ターゲットフレームワークとして .NET Framework 4.6.2 を使用して、クラスライブラリプロジェクトを作成します。

重要

エラーが発生後に 4.6.2 以降に導入された機能を使用する場合、アセンブリが後のバージョンを構築して使用するため一般的には機能します。
Microsoft.CrmSdk.WorkflowNuGet パッケージをインストールします。

このパッケージには、Microsoft.CrmSdk.CoreAssemblies パッケージが含まれています。
(オプション) 事前バインドテーブルクラスを使用する場合には、それらをプロジェクトに含めます。

詳細情報:
- .NET 用 SDK を使用した遅延バインドと事前バインドのプログラミング
- .NET 用 SDK の事前バインドクラスを生成する
パブリッククラスを追加します。クラスの名前は、活動により実行されるアクションに対応する必要があります。

次の using ディレクティブを追加する

using System.Activities;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Workflow;

いずれかの入力または出力パラメーターを表すためにプロパティをクラスの追加し、これらのプロパティをワークフロープロセスデザイナーに公開するために必要なメタデータを提供するため .NET 属性を使用します。

詳細: パラメーターの追加
クラスが CodeActivity クラスから派生し、活動が行う操作を含む Execute(CodeActivityContext) メソッドを実施するようにします。

詳細: Execute メソッドにコードを追加する
アセンブリにサインする
アセンブリを構築します。
プラグイン登録ツールを使用してアセンブリを登録し、 Name と WorkflowActivityGroupName プロパティを設定して、ワークフローデザイナーに表示されるテキストを定義します。

詳細: アセンブリの登録
ワークフロー活動を、ワークフロー、ダイアログ、またはアクションプロセス内から呼び出すことでテストします
(推奨) ソリューションにワークフロー活動を追加します。

パラメータを追加する

クラスのパラメーターを定義するとき、InArgument<T>、OutArgument<T>、またはInOutArgument<T>の種類として定義する必要があります。これらの種類は、パラメーターを取得または設定するために共通の引数クラスから継承したメソッドを提供します。コードは Execute メソッドでこれらのメソッドを使用します。詳細: Execute メソッドにコードを追加する

ユーザー定義ワークフロー活動が入力または出力パラメーターを使用する場合、定義するパブリッククラスのプロパティに適した .NET 属性を追加する必要があります。このデータはプロセスデザイナーによって読み取られ、プロセスデザイナーでどのようにパレメーターを設定できるかを定義します。

入力または出力パラメーターとしてプロパティの以下の種類を使用できます。

プロパティ	プロパティ (続き)	プロパティ (続き)
bool	DateTime	[小数]
Double	EntityReference	int
Money	OptionSetValue	string

入力および出力パラメーター

プロセスデザイナーの入力または出力パラメーターに表示するテキストを定義するには、.NET 属性を使用し、次のパターンを使用します。

[Input("Integer input")]
public InArgument<int> IntInput { get; set; }

[Output("Integer output")]
public OutArgument<int> IntOutput { get; set; }

クラスの 1 つのプロパティは、両方の属性を含めることにより、入力および出力パラメーターの両方とすることができます:

[Input("Int input")]  
[Output("Int output")]  
public InOutArgument<int> IntParameter { get; set; }

必要な値

ワークフロー活動をプロセスで使用するときに必要な入力パラメータを作成する場合は、[RequiredArgument] 属性を使用する必要があります。

既定値

入力パラメーターとして渡す値または出力パラメーターとして設定する値が定義されていない場合、既定値を指定できます。たとえば、ブール値プロパティの既定値を設定するには:

[Input("Bool input")]
[Default("True")]
public InArgument<bool> Bool { get; set; }

既定値の形式はプロパティの種類に応じて異なります。例が次の表にあります。

型	例
bool	[既定値("True")]
DateTime	[既定値("2004-07-09T02:54:00Z")]
小数	[既定値("23.45")]
Double	[既定値("23.45")]
Money	[既定値("23.45")]
EntityReference	[既定値("3B036E3E-94F9-DE11-B508-00155DBA2902", "取引先企業")]
int	[既定値("23")]
OptionSetValue	[既定値("3")]
string	[既定値("文字列既定")]

EntityReference パラメーター

EntityReference パラメーターのプロパティを定義するとき、ReferenceTarget 属性を使用する必要があります。これによって、許可されるテーブルの種類が確立されます。例:

[Input("EntityReference input")]
[Output("EntityReference output")]
[ReferenceTarget("account")]
public InOutArgument<EntityReference> AccountReference { get; set; }

OptionSetValue パラメーター

OptionSetValue パラメーターのプロパティを定義するとき、AttributeTarget 属性を使用する必要があります。この属性は、パラメータの値を有効なセットを含むテーブルと列を定義します。例:

[Input("Account IndustryCode value")]
[AttributeTarget("account", "industrycode")]
[Default("3")]
public InArgument<OptionSetValue> IndustryCode { get; set; }

Execute メソッドへのコードの追加

CodeActivity.Execute(CodeActivityContext) メソッドメソッドに含めるロジックはワークフロー活動の内容を定義します。

重要

Execute メソッド内のコードはステートレスとして記述される必要があります。 1 つ呼び出しから次にデータを渡すためにグローバルまたはメンバー変数を使用することは推奨されていません。パフォーマンスを向上させるため、Dataverse では、ユーザー定義のワークフロー活動インスタンスをキャッシュしています。このため、コンストラクターは、ユーザー定義のワークフロー活動のすべての呼び出しでは呼び出されません。また、ユーザー定義のワークフロー活動を複数のシステムのスレッドが同時に実行する可能性があります。 CodeActivityContext パラメーターを介して Execute メソッドに渡される情報のみを使用する必要があります。

Reference パラメーター

クラスに対して定義されたパラメーターを参照するには、Execute メソッドに渡される CodeActivityContext インスタンスを必要とし、それらが提供する Argument.Get または Argument.Set(ActivityContext, Object) メソッドを使用します。次の例では、入力パラメーターの値へのアクセスおよび出力パラメーターの値の設定を示しています。

using Microsoft.Xrm.Sdk.Workflow;
using System.Activities;

namespace SampleWorkflowActivity
{
  public class IncrementByTen : CodeActivity
  {
    [RequiredArgument]
    [Input("Decimal input")]
    public InArgument<decimal> DecInput { get; set; }

    [Output("Decimal output")]
    public OutArgument<decimal> DecOutput { get; set; }

    protected override void Execute(CodeActivityContext context)
    {
      decimal input = DecInput.Get(context);
      DecOutput.Set(context, input + 10);
    }
  }
}

コンテキスト情報を取得する

コードにコンテキスト情報が必要な場合、IWorkflowContext インターフェイスで CodeActivityContext.GetExtension<T> メソッドを使用してこれにアクセスできます。このオブジェクトは、操作のコンテキストを記述する多くの読み取り専用プロパティにアクセスできる IExecutionContext インターフェイスから派生しています。 IWorkflowContext では、ワークフローアセンブリを使用している実行中のワークフロー特有の類似したコンテキスト情報を提供します。

IWorkflowContext にアクセスするには Execute 関数の次のコードを使用します。

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...

重要

コンテキスト情報に基づくロジックの依存関係を一切含めてはいけません。ユーザー定義のワークフロー活動をワークフローで使用すると、すべての関連する入力パラメータはデザイナー内に設定されます。カスタム活動の出力値または動作は、動作を変更する非表示要素がないように、常に入力パラメータのみにより定義される必要があります。カスタム活動をデザイナーで使用すると、その動作は常に予測可能になります。

.NET 用 SDK を使用する

.NET 用 SDK を使用してデータ操作の実行が必要になる場合、IOrganizationServiceFactory インターフェイスで CodeActivityContext.GetExtension<T> メソッドを使用してこれにアクセスできます。そこから、CreateOrganizationService(Nullable<Guid>) メソッドを使用して、データ操作を実行するために使用できるサービスプロキシのインスタンスにアクセスできます。 IWorkflowContext.InitiatingUserId 操作が電話プロセスと同じコンテキストで行われるようにする場合、使用するユーザーコンテキストを特定するために使用できます。組織サービスにアクセスするには Execute 関数の次のコードを使用します。

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
 IOrganizationServiceFactory serviceFactory = context.GetExtension<IOrganizationServiceFactory>();

 // Use the context service to create an instance of IOrganizationService.             
 IOrganizationService service = serviceFactory.CreateOrganizationService(workflowContext.InitiatingUserId);
...

アセンブリの登録

ユーザー定義のワークフロー活動を含むアセンブリを登録するには、プラグイン登録ツール (PRT) を使用します。これは、プラグインを登録するために使用するツールと同じです。プラグインとユーザー定義のワークフロー活動の両方で、環境にアップロードするアセンブリを登録する必要があります。ただし、ユーザー定義のワークフロー活動のステップは登録しません。

ユーザー定義のワークフロー活動の場合、ワークフロープロセスデザイナーでの表示をコントロールするために、次のプロパティを指定する必要があります。

フィールド	説明
`Description`	プロセスデザイナーの UI に表示されませんが、この情報を格納する PluginType テーブルから取得されたデータからドキュメントを生成するときに便利な場合があります。
`FriendlyName`	プラグインのユーザーフレンドリ名です。
`Name`	表示されたメニューの名前
`WorkflowActivityGroupName`	Dataverse プロセスデザイナーのメインメニューに追加されるサブメニューの名前。

説明のプロパティの設定。

注意

これらの値は、ワークフロー活動をテストするときにアンマネージドソリューションに表示されません。ただし、このワークフロー活動を含む管理ソリューションをエクスポートする場合、これらの値はプロセスデザイナーに表示されます。

ワークフロー活動のデバッグ

Dataverse に展開されるユーザー定義のワークフロー活動では、プロファイルの取得、ローカルデバッグ向けの再生、さらに情報をテーブルに作成するトレースサービスの使用ができます。

次の例は、次のメッセージ: Add your message. を記述するためにトレースサービスを使用することを示しています。

protected override void Execute(CodeActivityContext context)
{
//Create the tracing service
ITracingService tracingService = context.GetExtension<ITracingService>();

//Use the tracing service
tracingService.Trace("{0} {1} {2}.", "Add", "your", "message");
...

詳細:

ソリューションへの追加

既定のソリューションに追加されるプラグイン登録ツールを使用してアセンブリを登録するとき、Common Data Service既定のソリューションと混同しないでください。 既定のソリューション には環境に適用されるすべてのアンマネージドカスタマイズが含まれているため、ソリューションを使用してユーザー設定ワークフロー活動を配布する前にアンマネージドソリューションに追加する必要があります。たとえばそれを、Common Data Service 既定のソリューション または作成した任意のアンマネージドソリューションに追加できます。

ユーザー定義のワークフロー活動への変更の管理

ユーザー定義のワークフロー活動のコードを保守する必要があります。コード変更には大きな変更が含まれる場合があるため、この変更を管理する必要があります。ユーザー定義のワークフローアセンブリを更新またはアップグレードするには、さまざまな手順を使用します。

ユーザー定義のワークフロー活動を含むアセンブリの登録時には、アセンブリのバージョンが含まれています。この情報はアセンブリからのリフレクションを使用して得られます。 Visual Studio プロジェクトの AssemblyInfo.cs ファイルを使用してバージョン番号を管理できます。

下部のセクションはこのように表示されます:

// Version information for an assembly consists of the following four values:
//
//      Major Version
//      Minor Version 
//      Build Number
//      Revision
//
// You can specify all the values or you can default the Build and Revision Numbers 
// by using the '*' as shown below:
//[assembly: AssemblyVersion("1.0.0.*")]
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]

このバージョン情報は、新しい機能を含めるときに、更新を展開されたアセンブリまたはアップグレードアセンブリに適用できるので重要です。

ユーザー定義のワークフロー活動アセンブリの更新

パブリッククラスやメソッドシグネチャを大幅に変更しないバグまたはリファクターコードを修正するために変更する場合、実行中のすべてのプロセスが自動的に新しいバージョンのアセンブリを使用して開始するようにアセンブリを更新できます。

アセンブリを更新する方法

AssemblyInfo.cs AssemblyVersion 属性のビルド番号とリビジョンの値のみを変更します。たとえば、1.0.0.0 から 1.0.10.5 に変更します。
アセンブリを更新するには、プラグイン登録ツールを使用します。詳細: アセンブリの更新

ユーザー定義のワークフロー活動アセンブリの更新

パブリッククラスやメソッドシグネチャへの大幅な変更を含む変更を行う場合、パラメーターの変更など、元のシグネチャを使用するように定義されたすべての現在実行中のプロセスを切断します。この場合、アセンブリをアップグレードする必要があります。これによって、プロセスデザイナーで適用するバージョンを定義するオプションを公開する新しいユーザー定義のワークフロー活動が作成されます。これによって、活動を使用する各プロセスを新しいアセンブリに含まれる変更に適応するように再構成することができます。元のアセンブリを使用するすべてプロセスがアップグレードされたアセンブリを使用して更新された後、古いアセンブリの登録を取り消すことができます。

アセンブリを更新する方法

新しいアセンブリには、既存のアセンブリと同じ Name、PublicKeyToken、および Culture があることを確認してください。
AssemblyInfo.cs AssemblyVersion 属性のメジャーバージョンおよび/またはマイナーバージョンの値を変更します。たとえば、1.0.0.0 から 2.0.0.0 に変更します。
新しいアセンブリとしてアセンブリを登録するには、プラグイン登録ツールを使用します。詳細: アセンブリの登録
ユーザー定義のワークフロー活動を使用した各プロセスの場合、プロセスを非アクティブ化してユーザー定義のワークフロー活動を使用する手順を編集する必要があります。

使用するアセンブリのバージョンを選択するために使用できるプロセスデザイナーでバージョンを検索します。

新しいアセンブリを使用するようにすべてのプロセスが変換されるとき、もう使用できないようにするために、アセンブリの登録解除にプラグイン登録ツールを使用できます。詳細: コンポーネントの登録解除

操作ガイド

ワークフロー拡張の操作に関する考慮事項は、通常のプラグインのものと同じです。詳細: プラグイン操作の分析

通常のプラグインとは違い、現在のワークフロー拡張で明示的に特定の手順用のコードを登録することはありません。これは、ワークフロー拡張のコードが同期的または非同期的に実行されるかどうかを制御しないことを意味します。同期的に実行すると考えられているコードでは特に注意が必要です。理由は、アプリケーションのユーザーエクスペリエンスに直接に影響を与るためです。

再利用可能なコンポーネントとして、ワークフロー拡張をすべてのワークフローまたはカスタム定義のアクションに追加できます。ワークフローは、同期的に実行されることを意味する リアルタイム ワークフローとして構成されていることがあります。ユーザー定義アクションは常に同期しますが、一意の 有効なロールバック を行わない限り、データベーストランザクションに関与しません。

重要

ワークフロー拡張が、同期的なワークフロー、またはユーザー定義のアクションで使用されているとき、コードの実行に費やした時間は、ユーザーエクスペリエンスに直接に影響します。したがって、ワークフロー拡張は同期的に使用されているとき、2秒以内に完了する必要があります。同期拡張にこれより多くの時間が必要な場合は、これを文書で記録して、同期的なワークフローまたはユーザー定義のアクションで拡張を使用するのを止めてください。

また、同期ワークフローまたはトランザクションに参加するカスタムアクションでは、ワークフロー拡張が投げたエラーによってトランザクション全体がロールバックされますが、これはパフォーマンスに影響を与えるコストのかかる処理です。

IWorkflowContextの値を使用できます。WorkflowMode ワークフローが同期的に実行しているかどうかを判断するためのプロパティ。

リアルタイムワークフローステージ

ワークフロー拡張がリアルタイム (同期) のワークフローで使用される場合、ワークフロー拡張は The following table に示されるように、イベント実行パイプラインステージで呼び出されます。詳細: イベント実行パイプライン

メッセージ	[段階]
作成	PostOperation
削除	事前操作
Update	事前操作または PostOperation

IWorkflowContext の値を使用できます。StageName ステージを検出するプロパティ。

更新操作については、ステージは、ワークフローデザイナーの前または後オプションを使用して構成できます。詳細: 「リアルタイムワークフローの使用」

ワークフロー拡張が実行コンテキストで渡されたデータに依存するとき、データがIWorkflowContextで使用可能かどうかに関して、それを実行するステージが制御します。InputParameters および IWorkflowContext、OutputParameters。

注意

InputParameters および OutputParameters に基づいてロジックの依存関係を含むことはお勧めしません。ワークフロー拡張は、ワークフロー拡張機能を使用している担当者がそこで非表示なしで所定の動作を理解できるように、構成済みの入力および出力パラメーターに依存します。

ワークフロー拡張に関するエンティティイメージ

ワークフロー拡張に関するエンティティのイメージを構成する方法はありません。理由は、使用者はアセンブリを登録するのみで、ワークフロー活動はワークフローのコンテキストで実行されるためです。ワークフロー拡張エンティティイメージはエンティティ前後のキー値の PreBusinessEntity かつ PostBusinessEntity の使用でそれぞれ有効です。詳細: エンティティイメージ

ワークフローの拡張機能

ワークフローの拡張機能を作成するとき

使用するテクノロジ

ユーザー定義ワークフロー活動の作成

パラメータを追加する

入力および出力パラメーター

必要な値

既定値

EntityReference パラメーター

OptionSetValue パラメーター

Execute メソッドへのコードの追加

Reference パラメーター

コンテキスト情報を取得する

.NET 用 SDK を使用する

アセンブリの登録

ワークフロー活動のデバッグ

ソリューションへの追加

ユーザー定義のワークフロー活動への変更の管理

ユーザー定義のワークフロー活動アセンブリの更新

アセンブリを更新する方法

ユーザー定義のワークフロー活動アセンブリの更新

アセンブリを更新する方法

操作ガイド

リアルタイムワークフローステージ

ワークフロー拡張に関するエンティティイメージ

関連項目

フィードバック

その他のリソース

ワークフローの拡張機能

ワークフローの拡張機能を作成するとき

使用するテクノロジ

ユーザー定義ワークフロー活動の作成

パラメータを追加する

入力および出力パラメーター

必要な値

既定値

EntityReference パラメーター

OptionSetValue パラメーター

Execute メソッドへのコードの追加

Reference パラメーター

コンテキスト情報を取得する

.NET 用 SDK を使用する

アセンブリの登録

ワークフロー活動のデバッグ

ソリューションへの追加

ユーザー定義のワークフロー活動への変更の管理

ユーザー定義のワークフロー活動アセンブリの更新

アセンブリを更新する方法

ユーザー定義のワークフロー活動アセンブリの更新

アセンブリを更新する方法

操作ガイド

リアルタイム ワークフロー ステージ

ワークフロー拡張に関するエンティティ イメージ

関連項目

フィードバック

その他のリソース

リアルタイムワークフローステージ

ワークフロー拡張に関するエンティティイメージ