Dynamics CRM 2011 Developer Toolkit (ベータ版) の紹介 - プラグイン開発

  • Article

みなさん、こんにちは。

今回は前回紹介した Developer Toolkit for Microsoft Dynamics CRM を
実際に使って、プラグイン開発をしてみたいと思います。

またツールキットをインストールされていない方は、前回記事を参照してください。

ソリューションの作成

開発を始めるにあたり、以下の手順でソリューションを作成します。

Dynamics CRM 2011 上のソリューション
※既定のソリューションで開発を行う場合には、この手順は不要です。

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

2. 設定 | カスタマイズ | ソリューション を開きます。

3. 新規をクリックして、新しいソリューションを作成します。ここでは
Toolkit Sample Solution としました。

Visual Studio 2010 上のソリューション

1. ツールキットインストール後に、Visual Studio 2010 を起動します。

2. 新しいプロジェクトを選択します。

3. New Visual Studio Solution Template for Dynamics CRM 2011 を
選択します。

image

4. ここでは既定の名前を利用しました。

5. OK をクリックすると、Dynamics CRM サーバーへの接続作成ダイアログが
表示されます。今回は Dynamics CRM オンラインを接続先に選択しています。

探索サービスのサーバー名、ポートおよびプロトコルを選択して Connect をクリックします。

image

6. Authentication Details 欄が有効になるので認証の入力を行い、Logon を
クリックします。組織が取得されるので、接続先の組織、および作成したソリューションを
選択して、OK をクリックします。

image

7. 今回選択したテンプレートには、Silverlight 開発プロジェクトも含まれるため、
ASP.NET ホストを作成するか聞かれますが、今回は必要ないため、キャンセルを
クリックします。

8. 表示メニューより CRM Explorer をクリックします。

image

9. 以下のように情報が取得できていれば、準備完了です。

image

プラグインプロジェクト

ソリューションエクスプローラーより、プラグインプロジェクトを確認します。
開発に必要な参照設定は全て完了しており、また Plugin クラスが存在します。

CRM Explorere より作成されたプラグインは、全てこの Plugin クラスを
継承しますので、中身を確認しておきます。

Plugin クラス

Plugin クラスでは、開発に欠かせないサービス類の作成やコンテキストの
取得用メソッドを提供します。

‐ Execution Context の取得
‐ トレースサービスの取得
‐ 組織サービスプロキシの生成

また、プラグインが実行されるべきイベントの検査を行い、一致しない場合は
実行しない機能があります。これにより誤ったステップ登録からのプラグイン
実行を防ぐことが可能です。

プラグインの署名

プラグインは署名されている必要があるため、以下の手順でプロジェクトの
プロパティを変更してください。

1. プラグインプロジェクトを右クリックし、プロパティをクリックします。

2. 左のタブより、署名タブをクリックします。

3. アセンブリの署名にチェックを入れて、厳密な名前のキーファイルの
選択から、新規をクリックします。
※既存のキーを利用する場合には、参照を選択してください。

4. 今回は以下のようにキーを設定しました。必要に応じて変更してください。

image

以上でプロジェクトの署名は完了です。

プラグインの作成

ではプラグインを開発してみます。今回は以下のプラグインを開発します。

‐ 対象エンティティ : 取引先企業
‐ ステージ : Post-operation
‐ 処理: メモの追加

以下の手順でプラグインの作成を行ってください。

1. CRM Explorer の Entities より、取引先企業を探して、右クリックします。

image

2. Create Plug-in をクリックします。

3. Create Plug-in ダイアログが出ますので、以下のように設定し、OK をクリックします。
※このダイアログの Class の部分に入っている名称が、作成されるファイル名と
クラス名に利用されるため、必要に応じて変更してください。

image

4. このタイミングで、自動的に CRM Package プロジェクトの RegisterFile.crmregister
ファイルも更新されます。

5. 今回は事前バインディングを利用したいので、CRM Explorer の Entities を右クリック
して、Generate Wrapper をクリックします。

image

6. 生成ファイルの保存先として、Plugin プロジェクトを指定し、Generate ボタンを
クリックします。完了まで少し時間がかかります。

image

7. 新規に作成された Post取引先企業Create.cs を開き、名前空間配下で生成された
ファイルを利用するために using 句を追加します。

using Entities;

8. TODO コメント以下に実際のコードを記述します。事前バインドが利用可能です。

// TODO: Implement your custom Plug-in business logic.
// IPluginExecutionContext を localContext より取得
IPluginExecutionContext context = localContext.PluginExecutionContext;

// InputParameters に Target が存在し、Entity であるか確認
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{ 
    // InputParameter より Target を取得
    Entity entity = (Entity)context.InputParameters["Target"];

    // id が含まれているか確認
    if (!context.OutputParameters.Contains("id"))
    return;

    try
    {
        // メモを作成します。
        Annotation memo = new Annotation();
        memo.Subject = "プラグインで作成されたメモ";
        memo.ObjectId = new EntityReference(entity.LogicalName.ToString(), new Guid(context.OutputParameters["id"].ToString()));

        // localContext のトレースサービスより Trace を実行
        localContext.TracingService.Trace("メモの作成を実行");

        // localContext の組織サービスより Create を実行
        localContext.OrganizationService.Create(memo);
    }
    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("メモ作成プラグインでエラーが発生.", ex);
    }
    catch (Exception ex)
    {
        localContext.TracingService.Trace("メモ作成プラグイン: {0}", ex.ToString());
        throw;
    }
} 

9. ビルドメニューよりビルドを実行します。

プラグインの展開と動作確認

無事プラグインの開発が終了したので、次は展開して見ます。

1. CRM Package プロジェクトを右クリックして、「配置」 をクリックします。
配置を実行することで、実際の環境にアセンブリを展開できます。

image

2 . 配置が完了したら、 CRM Explorer より、Plug-in Assemblies を
右クリックして、Refresh をクリックした後、展開して登録状況を確認します。

image

3. CRM Explorer より imageボタンをクリックして、Dynamics CRM を開きます。

4. ワークプレース | 取引先企業より、レコードを 1 件作成してみます。

5. レコード保存後、再度開いてメモが作成されていれば成功です。

image

ステップの追加

次に開発したプラグインを、取引先担当者の作成時にも実行するよう変更します。

1. CRM Explorer より Plug-in Assemblies を展開し、(Plugin)Post取引先企業Create
を右クリックします。Add Step を選択します。

image

2. 以下のように設定を行い、OK をクリックします。

image

3. 以下のようにステップが追加されていれば成功です。

image

4. Post取引先企業Create.cs ソースにも、取引先担当者でこのプラグインを
実行するという情報を追加します。これを忘れると、ステップに追加されていても
プラグインは実行されません。以下の箇所を探して、コードを追加してください。

public Post取引先企業Create()
    : base(typeof(Post取引先企業Create))
{
    base.RegisteredEvents.Add(new Tuple<int, string, string, Action<LocalPluginContext>>(40, "Create", "account", new Action<LocalPluginContext>(ExecutePost取引先企業Create)));
    // ここに取引先担当者の Create、Post Operation の情報を追加。
    // 上の行の第 3 引数の account を contact に変更します。
    base.RegisteredEvents.Add(new Tuple<int, string, string, Action<LocalPluginContext>>(40, "Create", "contact", new Action<LocalPluginContext>(ExecutePost取引先企業Create)));

    // Note : you can register for more events here if this plugin is not specific to an individual entity and message combination.
    // You may also need to update your RegisterFile.crmregister plug-in registration file to reflect any change.
}

5. ソリューションコンパイル後、再度 CRM Package プロジェクトより、配置を行います。

6. 配置完了後、動作確認を行ってください。

まとめ

Plugin クラスを継承していることや、実行するステップの情報をソース側にも
追加する等、若干のなれが必要ですが、短時間での開発、展開が可能でした。
事前バインド用クラスの作成も数クリックで実行できますが、特定エンティティ
のみ出力等の機能はまだ無いようです。

是非色々触って使い勝手を確認してください。

次回はツールキットを利用したカスタムアクティビティの開発を紹介します。

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