チュートリアル: プラグインを更新する

このチュートリアルは、プラグインを操作する方法を示すシリーズの 3 番目です。

• チュートリアル: プラグインを書き込み登録する
• チュートリアル: プラグインをデバッグする
• チュートリアル: プラグインを更新する (このチュートリアル)

サポートの概念と技術的な詳細の詳細については、次を参照してください。

• ビジネス プロセスを拡張するためのプラグインの使用
• プラグインを記述する
• プラグインの登録
• プラグインのデバッグ

目標

このチュートリアルでは、プラグインで実行する一般的なタスクについて説明します。このチュートリアルでは、次の操作を行います。

• プラグイン アセンブリを更新する
• 同期プラグインの作成と登録
• プラグインで組織データを使用する
• エラーを発生させてユーザーに表示する
• コードでプレ エンティティ イメージを設定して使用する
• アセンブリ、プラグイン、またはステップの登録を解除する

このチュートリアルの目的は次のとおりです。

• アカウント テーブルの更新メッセージの事前検証段階で登録された同期プラグインを作成します。
• プラグインの登録時に構成データとして渡される文字列値のセットを評価します。
• 取引先企業の名前がこれらの値の 1 つに変更され、以前の値に新しい名前が含まれていなかった場合は、操作を取り消して、ユーザーにエラー メッセージを戻します。

前提条件

• 完全な チュートリアル: プラグインを記述して登録します。
• チュートリアル: プラグインをデバッグするをお勧めしますが、必須ではありません。

新しいプラグイン クラスの作成

1. Visual Studioで、ValidateAccountName.csという名前の BasicPlugin プロジェクトに新しいクラスを追加します。

   注

   アセンブリに大幅な変更を加えた場合は、アセンブリのバージョンを更新します。 この手順は、マネージド ソリューションの一部であるアセンブリを更新する場合に特に重要です。 バージョンは、アセンブリの完全修飾名の一部であり、この完全修飾名はアセンブリの一意の識別子です。 ソリューションの更新プロセスでは、アセンブリの完全修飾名が変更されない場合にアセンブリが変更されたことを認識できない場合があります。

2. クラスに次のコードを追加し、アセンブリを再構築します。

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

namespace BasicPlugin
{
  public class ValidateAccountName : IPlugin
  {
    //Invalid names from unsecure configuration
    private List<string> invalidNames = new List<string>();

    // Constructor to capture the unsecure configuration
    public ValidateAccountName(string unsecure)
    {
      // Parse the configuration data and set invalidNames
      if (!string.IsNullOrWhiteSpace(unsecure))
        unsecure.Split(',').ToList().ForEach(s =>
        {
          invalidNames.Add(s.Trim());
        });
    }
    public void Execute(IServiceProvider serviceProvider)
    {

      // Obtain the tracing service
      ITracingService tracingService =
      (ITracingService)serviceProvider.GetService(typeof(ITracingService));
      try
      {

        // Obtain the execution context from the service provider.  
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // Verify all the requirements for the step registration
        if (context.InputParameters.Contains("Target") && //Is a message with Target
            context.InputParameters["Target"] is Entity && //Target is an entity
            ((Entity)context.InputParameters["Target"]).LogicalName.Equals("account") && //Target is an account
            ((Entity)context.InputParameters["Target"])["name"] != null && //account name is passed
            context.MessageName.Equals("Update") && //Message is Update
            context.PreEntityImages["a"] != null && //PreEntityImage with alias 'a' included with step
            context.PreEntityImages["a"]["name"] != null) //account name included with PreEntityImage with step
        {
          // Obtain the target entity from the input parameters.  
          var entity = (Entity)context.InputParameters["Target"];
          var newAccountName = (string)entity["name"];
          var oldAccountName = (string)context.PreEntityImages["a"]["name"];

          if (invalidNames.Count > 0)
          {
            tracingService.Trace("ValidateAccountName: Testing for {0} invalid names:", invalidNames.Count);

            if (invalidNames.Contains(newAccountName.ToLower().Trim()))
            {
              tracingService.Trace("ValidateAccountName: new name '{0}' found in invalid names.", newAccountName);

              // Test whether the old name contained the new name
              if (!oldAccountName.ToLower().Contains(newAccountName.ToLower().Trim()))
              {
                tracingService.Trace("ValidateAccountName: new name '{0}' not found in '{1}'.", newAccountName, oldAccountName);

                string message = string.Format("You can't change the name of this account from '{0}' to '{1}'.", oldAccountName, newAccountName);

                throw new InvalidPluginExecutionException(message);
              }

              tracingService.Trace("ValidateAccountName: new name '{0}' found in old name '{1}'.", newAccountName, oldAccountName);
            }

            tracingService.Trace("ValidateAccountName: new name '{0}' not found in invalidNames.", newAccountName);
          }
          else
          {
            tracingService.Trace("ValidateAccountName: No invalid names passed in configuration.");
          }
        }
        else
        {
          tracingService.Trace("ValidateAccountName: The step for this plug-in is not configured correctly.");
        }
      }
      catch (Exception ex)
      {
        tracingService.Trace("BasicPlugin: {0}", ex.ToString());
        throw;
      }
    }
  }
}

コードについて

• このクラスには、ステップを構成するときに設定したセキュリティで保護されていない構成をキャプチャするコンストラクターが含まれています。
• このクラスには、正しく機能するために特定のステップ構成が必要となります:
  • 更新メッセージ
  • アカウントテーブル上で
  • 属性にアカウント名が含まれている
  • 特定のエイリアス 'a' を使用した PreEntityImage
  • 名前列を含む PreEntityImage を使用。
• ステップ構成が正しくない場合、プラグインは正しく構成されていないことをトレースに書き込みます。
• 構成設定で無効な名前を設定しない場合、プラグインは、無効な名前が構成設定に渡されなかったことをトレースに書き込みます。
• 新しい名前が構成を使用して設定した無効な名前のいずれかに一致 し 、元の名前に新しい名前が含まれていない場合、プラグインは、この操作が許可されていないというメッセージを含む InvalidPluginExecutionException をスローします。

プラグイン アセンブリ登録の更新

既存のアセンブリは、「 チュートリアル: プラグインの作成と登録」から既に登録されています。 既存のアセンブリの登録を解除せずに新しい ValidateAccountName プラグインを追加するには、それを更新します。

1. (アセンブリ) 基本的なプラグイン を選択し、更新 を選択します。

   

2. [ アセンブリの更新: 基本プラグイン ] ダイアログで、省略記号 (...) を選択してアセンブリの場所を指定します。 アセンブリが読み込まれます。

   

3. アセンブリと両方のプラグインが選択されていることを確認し、[ 選択したプラグインの更新] を選択します。

新しい手順の構成

これらの設定を使って、ValidateAccountName プラグインを構成します。

画像の追加

1. 先ほど登録したステップを右クリックし、新しいイメージの登録 を選択します。

   

2. 新しいイメージの登録 ダイアログで、次の設定を持つイメージを構成します。

   設定	値
   イメージの種類	事前イメージ
   Name	アカウント
   エンティティの別名	a
   パラメーター	名前

   

3. イメージを登録すると、プラグイン登録ツールに表示されます。

   

プラグインのテスト

1. アプリケーションを開き、既存の取引先企業名を test、 foo、または bar に更新します。

2. 保存しようとすると、次のメッセージが表示されます。

   

3. test、foo、bar を含む名前を持つ既存の取引先企業を更新した場合、取引先企業を test、foo、または bar に更新するとメッセージが表示されることはありません。

アセンブリ、プラグイン、ステップの登録解除

プラグイン登録ツールを使用して、アセンブリ、プラグイン、またはステップの 登録を解除 (削除) します。 アセンブリを削除すると、そのアセンブリのすべてのプラグインとステップが削除されます。