Microsoft DynamicsCRM-プラグイン
プラグインは、Microsoft Dynamics CRMと統合して、プラットフォームの標準的な動作を変更または拡張するカスタムビジネスロジックです。プラグインはイベントハンドラーとして機能し、CRMの特定のイベントで実行するように登録されています。プラグインはC＃またはVBで記述されており、同期モードまたは非同期モードで実行できます。
プラグインを作成するいくつかのシナリオは次のとおりです。
CRMレコードを作成または更新するときに、レコードの特定のフィールドの更新や関連レコードの更新など、いくつかのビジネスロジックを実行する必要があります。
レコードの保存や更新などの特定のイベントで外部Webサービスを呼び出す必要があります。
レコードが開かれたときにフィールド値を動的に計算する必要があります。
CRMの特定のイベントで顧客に電子メールを送信するなどのプロセスを自動化する必要があります。
イベントフレームワーク
CRMのイベント処理フレームワークは、同期および非同期のプラグイン要求をイベント実行パイプラインに渡すことで処理します。イベントがプラグインロジックをトリガーするたびに、メッセージがCRM組織Webサービスに送信され、そこで他のプラグインまたはプラットフォームのコア操作によって読み取りまたは変更できます。
プラグインパイプラインステージ
プラグインパイプライン全体は、カスタムビジネスロジックを登録できる複数の段階に分かれています。指定されたパイプラインステージは、プラグイン実行サイクルのどのステージでプラグインコードが実行されるかを示します。次の表で指定されているすべてのパイプラインステージのうち、カスタムプラグインはプレイベントとポストイベントでのみ登録できます。Platform Core MainOperationsにプラグインを登録することはできません。
| イベント | 芸名 | 説明 |
|---|---|---|
| プレイベント | 事前検証 | メインシステムの操作の前に実行されるプラグインのパイプラインのステージ。この段階で登録されたプラグインは、データベーストランザクションの外部で実行される場合があります。 |
| プレイベント | 術前 | メインシステムの操作の前に実行されるプラグインのパイプラインのステージ。この段階で登録されたプラグインは、データベーストランザクション内で実行されます。 |
| プラットフォームコアオペレーション | MainOperation | 非トランザクション、作成、更新、削除などのシステムの主な操作。この段階では、カスタムプラグインを登録することはできません。内部使用のみ。 |
| イベント後 | 術後 | メイン操作の後に実行されるプラグインのパイプラインのステージ。この段階で登録されたプラグインは、データベーストランザクション内で実行されます。 |
CRMアプリケーションがイベント（レコードの保存や更新など）を呼び出すたびに、次の一連のアクションが実行されます-
イベントはWebサービス呼び出しをトリガーし、実行はイベントパイプラインステージ（イベント前、プラットフォームコア操作、イベント後）を通過します。
情報はOrganizationRequestメッセージとして内部的にパッケージ化され、最終的に内部のCRMWebサービスメソッドとプラットフォームのコア操作に送信されます。
OrganizationRequestメッセージは、イベント前のプラグインによって最初に受信されます。プラグインは、プラットフォームのコア操作に渡す前に情報を変更できます。プラットフォームのコア操作の後、メッセージはOrganizationResponseとしてパッケージ化され、操作後のプラグインに渡されます。ポストオペレーションプラグインは、オプションで、非同期プラグインに渡す前にこの情報を変更できます。
プラグインは、この情報をコンテキストオブジェクトの形式で受け取ります。このオブジェクトは、Executeメソッドに渡され、その後、さらに処理が行われます。
すべてのプラグイン処理が完了すると、実行はイベントをトリガーしたアプリケーションに戻されます。
プラグインメッセージ
メッセージは、プラグイン（またはビジネスロジック）が登録されているイベントです。たとえば、Create Message ofContactエンティティにプラグインを登録できます。これにより、新しい連絡先レコードが作成されるたびにビジネスロジックが起動します。
カスタムエンティティの場合、エンティティがユーザー所有か組織所有かに基づいてサポートされるメッセージは次のとおりです。
| メッセージ名 | 所有権の種類 |
|---|---|
| 割当 | ユーザー所有のエンティティのみ |
| 作成する | ユーザー所有および組織所有のエンティティ |
| 削除 | ユーザー所有および組織所有のエンティティ |
| アクセス許可 | ユーザー所有のエンティティのみ |
| ModifiedAccess | ユーザー所有のエンティティのみ |
| 取得 | ユーザー所有および組織所有のエンティティ |
| RetrieveMultiple | ユーザー所有および組織所有のエンティティ |
| RetrievePrincipalAccess | ユーザー所有のエンティティのみ |
| RetrieveSharedPrincipalsAndAccess | ユーザー所有のエンティティのみ |
| アクセス権を取り消す | ユーザー所有のエンティティのみ |
| SetState | ユーザー所有および組織所有のエンティティ |
| SetStateDynamicEntity | ユーザー所有および組織所有のエンティティ |
| 更新 | ユーザー所有および組織所有のエンティティ |
デフォルトのすぐに使用可能なエンティティの場合、100を超えるサポートされているメッセージがあります。これらのメッセージの一部はすべてのエンティティに適用できますが、一部は特定のエンティティに固有です。サポートされているメッセージの完全なリストは、SDK内のExcelファイルにあります。SDK\Message-entity support for plug-ins.xlsx
プラグインを書く
このセクションでは、プラグインの作成の基本を学びます。新しい顧客がシステムに追加されるたびに、つまりCRMで新しいContactrecordが作成されるたびに、顧客をフォローアップするためのタスクアクティビティを作成するサンプルプラグインを作成します。
まず第一に、あなたはへの参照を含める必要があります Microsoft.Xrm.Sdk名前空間。CRM SDKには、必要なすべてのSDKアセンブリが含まれています。第2章でSDKを既にダウンロードしてインストールしていると仮定して、VisualStudioを開きます。クラスライブラリタイプの新しいプロジェクトを作成します。プロジェクトにSamplePluginsという名前を付けて、[OK]をクリックします。
の参照を追加します Microsoft.Xrm.Sdkプロジェクトへのアセンブリ。アセンブリはに存在しますSDK/Bin。
次に、という名前のクラスを作成します PostCreateContact.cs からクラスを拡張します IPlugin。これまでのところ、コードは次のようになります。
System.Runtime.Serializationへの参照も追加する必要があります。必要な参照を追加したら、次のコードをPostCreateContact クラス。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;
namespace SamplePlugins {
public class PostCreateContact:IPlugin {
/// A plug-in that creates a follow-up task activity when a new account is created.
/// Register this plug-in on the Create message, account entity,
/// and asynchronous mode.
public void Execute(IServiceProviderserviceProvider) {
// Obtain the execution context from the service provider.
IPluginExecutionContext context =(IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
// The InputParameters collection contains all the data
passed in the message request.
if(context.InputParameters.Contains("Target")&&
context.InputParameters["Target"]isEntity) {
// Obtain the target entity from the input parameters.
Entity entity = (Entity)context.InputParameters["Target"];
try {
// Create a task activity to follow up with the account customer in 7 days
Entity followup = new Entity("task");
followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
"Follow up with the customer. Check if there are any new issues
that need resolution.";
followup["scheduledstart"] = DateTime.Now;
followup["scheduledend"] = DateTime.Now.AddDays(2);
followup["category"] = context.PrimaryEntityName;
// Refer to the contact in the task activity.
if(context.OutputParameters.Contains("id")) {
Guid regardingobjectid = new Guid(context.OutputParameter
s["id"].ToString());
string regardingobjectidType = "contact";
followup["regardingobjectid"] =
new EntityReference(rega rdingobjectidType,regardingobjectid);
}
// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory =
(IOrganizationSer viceFactory)serviceProvider.GetService
(typeof(IOrganizationServiceFactory));
IOrganizationService service =
serviceFactory.CreateOrganizationService(context.UserId);
// Create the followup activity
service.Create(followup);
} catch(Exception ex) {
throw new InvalidPluginExecutionException(ex.Message);
}
}
}
}
}以下は、このコードが何をするかについての段階的な説明です-
Step 1− IServiceProviderオブジェクトをパラメーターとして使用して、Executeメソッドを実装します。サービスプロバイダーには、プラグイン内で使用する予定の多くの便利なオブジェクトへの参照が含まれています。
Step 2 −IServiceProviderのGetServiceメソッドを使用してIPluginExecutionContextオブジェクトを取得します。
Step 3−コンテキストオブジェクトのInputParametersコレクションからターゲットエンティティのオブジェクトを取得します。このエンティティクラスオブジェクトは、プラグインが登録されるContactエンティティレコードを参照します。
Step 4−次に、タスクエンティティのオブジェクトを作成し、適切な件名、説明、日付、カテゴリ、および関連オブジェクトIDを設定します。aboutobjectidは、このアクティビティレコードが作成されている連絡先レコードを示します。コードがcontext.OutputParametersを使用して親の連絡先レコードのIDを取得し、それを作成したタスクエンティティレコードに関連付けていることがわかります。
Step 5 −IServiceProviderオブジェクトを使用してIOrganizationServiceFactoryのオブジェクトを作成します。
Step 6 −IOrganizationServiceFactoryオブジェクトを使用してIOrganizationServiceのオブジェクトを作成します。
Step 7−最後に、このサービスオブジェクトのCreateメソッドを使用します。CRMに保存されるフォローアップ活動を作成します。
プラグインアセンブリへの署名
このセクションは、プラグインアセンブリを初めて登録する場合にのみ適用されます。プラグインをデプロイできるようにするには、キーを使用してアセンブリにサインインする必要があります。ソリューションを右クリックし、[プロパティ]をクリックします。
左側のオプションから[署名]タブを選択し、[アセンブリに署名する]オプションをオンにします。次に、[厳密な名前のキーファイルを選択してください]オプションから[新規]を選択します。
キーファイル名をsamplepluginsとして入力します（これは他の任意の名前にすることができます）。[キーファイルをパスワードで保護する]オプションをオフにして、[OK]をクリックします。[保存]をクリックします。
最後に、ソリューションを構築します。右クリック→ビルド。ソリューションをビルドすると、アセンブリDLLが生成されます。これは、次の章でこのプラグインを登録するために使用します。
プラグインでの例外処理
多くの場合、プラグインロジックは実行時の例外を処理する必要があります。同期プラグインの場合、InvalidPluginExecutionException例外。ユーザーにエラーダイアログボックスが表示されます。エラーダイアログには、例外オブジェクトのメッセージオブジェクトに渡すカスタムエラーメッセージが含まれます。
コードを見ると、catchブロックでInvalidPluginExecutionException例外がスローされています。
throw new InvalidPluginExecutionException(ex.Message);結論
プラグインは、カスタムCRMの実装にとって間違いなく重要です。この章では、イベントフレームワークモデル、パイプラインステージ、メッセージの理解、およびサンプルプラグインの作成に焦点を当てました。次の章では、このプラグインをCRMに登録し、エンドツーエンドのシナリオで機能することを確認します。