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

[アーティクル]
02/23/2023

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

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

関連する概念と技術的詳細については、以下を参照してください。

目標

このチュートリアルでは、プラグインで行う追加の一般的な操作について説明します。このチュートリアルでは、以下のことを行います。

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

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

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

前提条件

チュートリアル: プラグインを書き込み登録するを完了する
チュートリアル: プラグインをデバッグするをお勧めしますが、必須ではありません。

注意

多くの基本的な手順がは、チュートリアル: プラグインを作成して登録するで詳しく説明されています。同じレベルの詳細は、このチュートリアルの同じ手順には含まれていません。

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

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

注意

アセンブリに大幅な変更を加える場合は、アセンブリのバージョンを更新する必要があります。これは、管理ソリューションの一部であるアセンブリを更新する場合に特に重要です。バージョンは、アセンブリの一意の識別子であるアセンブリの完全修飾名の一部です。ソリューション更新プロセスは、アセンブリの完全修飾名が変更されていない場合、アセンブリが変更されたことを認識しない場合があります。
次のコードをクラスに追加して、アセンブリを再作成します。

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 プラグインを追加するには、それを更新する必要があります。

(アセンブリ) 基本的なプラグイン を選択し、更新を選択します。
更新アセンブリ: 基本的なプラグイン ダイアログで、省略記号 (…) をクリックしてアセンブリの場所を指定すると、アセンブリが読み込まれます。
アセンブリとの両方のプラグインが選択されていることを確認し、選択したプラグインの更新をクリックします。

新しい手順の構成

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

設定	値
メッセージ	更新プログラム
主エンティティ	取引先企業
フィルタリング属性	名前
実行のイベントパイプラインステージ	事前検証
実行モード	同期
[セキュリティで保護されていない構成]	test、 foo、 bar

新しいステップの登録。

画像の追加

先ほど登録したステップを右クリックし、新しいイメージの登録 を選択します。
新しいイメージの登録 ダイアログで、次の設定を持つイメージを構成します。

設定 Value

イメージの種類プレイメージ

Name アカウント

エンティティエイリアス am

パラメーター名前
イメージが登録されると、プラグイン登録ツールに表示されます。

設定	Value
イメージの種類	プレイメージ
Name	アカウント
エンティティエイリアス	am
パラメーター	名前

重要

エンティティイメージを作成する際の既定動作では、すべての列を選択します。ただし、これは Web サービスのパフォーマンスを低下させる可能性があります。開発者は必要な列のみを含める必要があります。

プラグインのテスト

アプリケーションを開き、既存の取引先企業名を test、 foo、または bar に更新します。
保存しようとすると、次のメッセージが表示されます。
test、foo、bar を含む名前を持つ既存の取引先企業を更新した場合、取引先企業を test、foo、または bar に更新するとメッセージが表示されることはありません。

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

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

アセンブリの登録解除。

注意

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

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

目標

前提条件

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

コードについて

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

新しい手順の構成

画像の追加

プラグインのテスト

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

フィードバック

その他のリソース

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

目標

前提条件

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

コードについて

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

新しい手順の構成

画像の追加

プラグインのテスト

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

フィードバック

その他のリソース

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

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