Dynamics CRM 2011 強化された Plug-in

みなさん、こんにちは。

今日は Dynamics CRM 2011 の強化された Plug-in を紹介します。また Dynamics CRM 2011 から
開発を始めた方も多いかと思いますので、 Plug-in の基本的な機能も合わせて紹介します。

Plug-in

Dynamics CRM 2011 はいくつかの拡張ポイントを提供しています。Plug-in はプラットフォームの
オペレーションパイプラインに登録できる、カスタムロジックです。また Plug-in はプラットフォームの
操作によって発生したイベントのハンドラーと捕らえることも可能です。

たとえば、取引先企業の作成時にカスタムロジックを実行したり、レコードのアサインのタイミングで
ロジックを実行することが可能です。

イベント実行パイプライン

Dynamics CRM 2011 の Web サービスやクライアントから、レコードの作成、更新、削除等の
操作が行われた場合に、それらの処理はイベント実行パイプラインで実行されます。パイプランは
5つのステージに分かれており、それぞれ以下のように定義されています。

ステージ 10 Pre-Validation
一番初めのステージで、メインのシステム処理外の前処理に位置します。基本的にデータベースの
トランザクション外に位置するステージで、Plug-in の登録が可能です。

ステージ 20 Pre-Operation
メインのシステム処理内の、前処理のステージになります。データベースのトランザクション内に
位置し、Dynamics CRM 2011 から Plug-in の登録が可能になりました。

ステージ 30 Main-Operation
メインのシステム処理です。システム内部で使用されるステージで、Plug-in は登録できません。

ステージ 40 Post-Operation
メインのシステム処理内の、後処理のステージになります。データベースのトランザクション内に
位置し、、Dynamics CRM 2011 から Plug-in の登録が可能になりました。

ステージ 50 Post-Operation
一番初めのステージで、メインのシステム処理外の前処理に位置します。基本的にデータベースの
トランザクション外に位置するステージで、Dynamics CRM 4.0 では Plug-in が登録できましたが
Dynamics CRM 2011 ではサポートされません。

以上のように、Dynamics CRM 4.0 では、ステージ10 と 50 への Plug-in 登録がサポートされ、
Dynamics CRM 2011 からは、ステージ 10、20、40 への Plug-in 登録がサポートされます。

トランザクションサポート

上記で紹介したように、 Dynamics CRM 2011 から、Plug-in をメインの操作内に登録することで、
トランザクション内でカスタムロジックを実行することが可能になりました。具体的なサンプルで
実際の動作を実験します。

準備

動作を検証するにあたり、まず以下の準備が必要です。

- Visual Studio 2010 のインストール
- Dynamics CRM 2011 SDK のダウンロード
- Plug-in Registration Tool のコンパイル
- サンプルの作成

Visual Studio 2010 はインストールされている前提で進めます。

Plug-in Registration Tool の準備

1. 以下の URL より Dynamics CRM 2011 SDK をダウンロードします。
https://www.microsoft.com/downloads/en/details.aspx?FamilyID=420f0f05-c226-4194-b7e1-f23ceaa83b69

2. ダウンロードしたモジュールを任意のフォルダに解凍します。

3. Visual Studio 2010 を起動します。

4. プロジェクトを開くメニューより、SDK を解凍したフォルダ\sdk\tools\pluginregistration 内の
PluginRegistrationTool ソリューションを開いてください。

5. プロジェクトを開いたら、ビルドメニューより、ソリューションのビルドを実行してください。

6. ビルドが正常に完了したら、ツールの準備は完了です。

サンプルの作成

1. Visual Studio 2010 より、新規のプロジェクトを作成します。
ファイル | 新規作成 | プロジェクトを選択してください。

2. 言語を選択し（ここでは C#）、種類を Windows のクラスライブラリを選択してください。
名称は CRMPluginSample とします。選択したら OK をクリックします。

3. ソリューション エクスプローラー内の参照設定を右クリックして、参照の追加を選択します。

4. 参照タブを選択して、SDK を解凍したフォルダ\sdk\bin フォルダより
Microsoft.Xrm.Sdk.dll を選択し、OK をクリックします。

同様に .NET タブをクリックし、System.Runtime.Serialization を選択し、OKをクリックします。

5. コードを以下の内容に置き換えます。このコードは、例外のみを発生させるクラスと、
ダミー取引先担当者を作成するクラスを含んでいます。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Xrm.Sdk;

namespace CRMPluginSample
{
    public class RaiseException : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // エラーのみを返す
            throw new InvalidPluginExecutionException();
        }
    }

    public class CreateDummyContact : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // context を取得
            IPluginExecutionContext context =
                (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            // organization サービスを取得
            IOrganizationServiceFactory factory =
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = factory.CreateOrganizationService(context.UserId);
           
            try
            {
                // ダミー取引先担当者を作成
                Entity myContact = new Entity("contact");
                myContact["lastname"] = "DummyContact";

                service.Create(myContact);
            }
            catch (Exception ex)
            {
                // Handle the exception.
            }
        }

    }
}

6. ソリューション エクスプローラーより、CRMPluginSample を右クリックして、プロパティを
クリックします。

7. 署名タブをクリックして、アセンブリ署名にチェックし、新規作成を選択します。

8. 任意のキーファイル名を入力し、任意のパスワードを入力します。OK をクリックします。

9. ビルドより、ソリューションのビルドを実行します。これで準備完了です。

実験 1

準備が完了しましたので、実験を開始します。まずは取引先企業の作成操作に対して
ダミー取引先担当者作成の Plug-in を ステージ 10 に、例外発生を、ステージ 40 に登録してみます。
これでダミー取引先担当者の作成はトランザクション外に、例外発生がトランザクション内に登録されます。

Plug-in 登録

1. SDK を解凍したフォルダ\sdk\tools\pluginregistration\bin\Debug より
PluginRegistration.exe を実行します。

2. 起動した画面から、 Create New Connection をクリックします。

3. Connection Information が画面左下に開きます。 Dynmics CRM 2011 の URL と
システム管理者権限のあるユーザー情報を入力して、Connect をクリックします。

4. 画面左上に組織の一覧が出ます。検証で使いたい組織をダブルクリックします。

5. 画面右側に組織の詳細が出ます。Register メニューより Register New Assembly を
クリックします。

6. ファイルとして先ほどコンパイルした CRMPluginSample.dll を指定します。

7. 後は既定のまま、Register Selected ボタンをクリックします。

8. 登録に成功すると以下のメッセージが出ます。OK をクリックします。

9. 元の画面に戻り、新しく登録したアセンブリが表示されます。

10. まず CRMPluginSample.CreateDummyContact を右クリックして、
Register New Step をクリックし、以下の情報で登録します。

Message: Create
Primary Entity: account
Pipeline Stage (画面左下): Pre-Validation

他は既定値のままで、Register New Step をクリックします。

11. 同様に CRMPluginSample.RaiseException を右クリックして、
Register New Step をクリックし、以下の情報で登録します。

Message: Create
Primary Entity: account
Pipeline Stage (画面左下): Post-Operation (Dynamics CRM 2011 Only)

以上で準備が完了しました。現在ダミー取引先担当者の作成はトランザクション外、
エラーの発生はトランザクション内に登録されています。

取引先企業の作成を結果確認

では、取引作業企業を作成してみましょう。

1. Internet Explorer で Dynamics CRM 2011 に接続し、取引先企業を作成。

2. 必須フィールドを入力後保存して閉じるをクリックすると、以下のエラー発生。

3. OK をクリックしてエラーを閉じた後、[x] で新規作成画面を閉じる。

4. 取引先担当者のグリッドに移動。レコードができている。

よって、エラーの発生によってダミー取引先担当者の作成はロールバックされませんでした。

実験 2

次に、ダミー取引先担当者の作成を、ステージ 20 に移して実験します。これで両方の操作が
トランザクション内に登録されます。

Plug-in 登録更新

1. Plug-in Registration Tool に戻ります。

2. CRMPluginSample.CreateDummyContact を展開して、作成されたステップを
ダブルクリックします。ステップの登録画面が開きます。

3. Pipeline Stage を Pre-Validation から Pre-Operation (Dynamics CRM 2011 Only) に
変更して、Update をクリックします。

取引先企業の作成を結果確認

1. Internet Explorer に戻り、まず作成されたダミーの取引先担当者を削除します。

2. レコードが削除されたことを確認したら、新規に取引先企業を作成します。

3. 必須フィールドを入力して、保存して閉じるをクリックすると、先ほどと同じ
エラーが確認できます。

4. OK をクリックして、[x] で閉じてから、取引先担当者のグリッドに移動します。

5. レコードができていないことを確認します。

今回はエラーの発生によって、ダミー取引先担当者の作成もロールバックされました。

以上のようにステージ 20 および 40 に登録された Plug-in は同じトランザクションのスコープで
処理が実施されます。これにより、 Plug-in 内で行った作業とメインのオペレーションの整合性が
取れることとなります。

Azure 連携

Dynamics CRM 2011 は、 Plug-in を利用した Azure 連携機能を提供しています。
Azure 用の機能は Registration Tool に含まれており、またセキュリティ設定なども
容易に行えるよう、機能が提供されています。

詳細を紹介するには、Azure 側の手順紹介なども必要なため今回のブログでは紹介が
できませんが、英語の資料でも問題ないよという方は、以下の URL より Training Kit を
入手していただくか、SDK の Step By Step を見て概要を掴んでいただければと思います。

https://www.microsoft.com/downloads/en/details.aspx?FamilyID=78498c29-28ac-440b-9c20-ec5da6ee6e98

尚、現在ダウンロードできる SDK に含まれる Plug-in Registration Tool には不具合が
あり、そのままでは Azure 連携用の Plug-in にステップが登録できません。

※以下のようなエラーが出ます。

対処方法は現在確認中ですので、確認出来次第アップデートしたいと思います。

(更新) SDK 5.0.3 で修正されました！

ステップの無効化 (非アクティブ化)

登録済みのステップを、一時的に無効化することが可能です。該当の Plug-in を停止したい
場合に、ステップを削除するより簡単で、後で有効化ができます。無効化したいステップを
右クリックして、Disable をクリックしてください。また無効化後に、有効に戻したい場合には
Enable をクリックしてください。

※下記赤のビックリマークが無効になったステップです。

またステップの有効化/無効化 (アクティブ化/非アクティブ化) は、ソリューションの内部からも操作が可能です。

1. Internet Explorer で Dynamics CRM 2011 に接続します。

2. 設定 | カスタマイズ | システムのカスタマイズを開きます。

3. プラグイン アセンブリを確認すると、登録されたアセンブリの情報が確認できます。

4. SDK メッセージ処理手順からは、ステップのアクティブ化、非アクティブ化が行えます。
状態列の値で、有効/無効を確認してください。

非同期 Plug-in 完了時のログ

Plug-in はステージ 40 に登録した場合、非同期処理にすることが可能です。非同期で
登録された Plug-in は非同期サービスによって処理が行われ、その結果はシステムジョブに
出力されます。多数の非同期 Plug-in がある場合には、システムジョブの結果レコードが
多くなり、テーブルが肥大化するため、処理成功時にはログを削除するオプションが
あります。

上記画面一番下のチェックボックスにチェックを入れることで、処理が成功したら
完了ログは削除され、テーブルの肥大化を抑えることが可能です。

※ Plug-in の処理を非同期にした場合には、ステージ 40 であってもトランザクションの対象になりません。

処理のタイムアウト

Plug-in は同期、非同期にかかわらず、2分間で処理が終わらない場合にはタイムアウト
するよう設定されています。パフォーマンスを考慮した対応のため、2分以上かかるような
ロジックは、ワークフローでの対処を検討してください。

サンドボックスサービス

よりセキュアな環境で Plug-in が実行できるよう、通常の非同期サービスに加えて、
サンドボックスサービスが提供されます。サンドボックスサービス上に登録された Plug-in は
ファイルシステムやイベントログ、レジストリなどのアクセスが行えません。

また、Dynamics CRM オンラインは サンドボックスへの登録のみサポートしていますので
設置型、オンラインともに利用したい場合には、サンドボックス内でのみ動作する Plug-in を
作成するようにしてください。

ソリューション対応

Dynamics CRM 2011 より、Plug-in もソリューション対応となり、他組織への移行が容易です。
以前は、手動でアセンブリをコピーして、Plugin Registration Tool で再登録する必要があったため
多くの Plug-in がある場合、その作業は非常に煩雑でした。

ソリューション対応したことで、Plug-in のコピーや再登録は不要になり、作業の短縮や移行
し忘れるといった問題が解消されます。

今回は Dynamics CRM 2011 で拡張された Plug-in の機能を紹介しました。いかがだったでしょうか。
他にも Plug-in で気になることがあれば、是非ご連絡ください。

- Dynamics CRM サポート 中村 憲一郎