チュートリアル: プラグインを更新する
このチュートリアルでは、プラグインの使用方法を説明するシリーズの 3 番目のチュートリアルです。
- チュートリアル: プラグインを書き込み登録する
- チュートリアル: プラグインをデバッグする
- チュートリアル: プラグインを更新する (このチュートリアル)
関連する概念と技術的詳細については、以下を参照してください。
目標
このチュートリアルでは、プラグインで行う追加の一般的な操作について説明します。このチュートリアルでは、以下のことを行います。
- プラグイン アセンブリを更新する
- 同期プラグインの作成と登録
- プラグインで組織データを使用する
- ユーザーに表示するエラーをスローする
- コードでプレ エンティティ イメージを設定して使用する
- アセンブリ、プラグイン、またはステップの登録解除
このチュートリアルの目標は次のとおりです。
- アカウント テーブルの更新メッセージの事前検証段階で登録された同期プラグインを作成します。
- プラグインは、プラグインの登録時に構成データとして渡された一連の文字列値を評価します。
- アカウント名がこれらの値のいずれかに変更され、以前の値に新しい名前が含まれていなかった場合は、操作を キャンセル し、ユーザーにエラー メッセージを返します。
前提条件
- チュートリアル: プラグインを書き込み登録するを完了する
- チュートリアル: プラグインをデバッグするをお勧めしますが、必須ではありません。
注意
多くの基本的な手順がは、チュートリアル: プラグインを作成して登録するで詳しく説明されています。同じレベルの詳細は、このチュートリアルの同じ手順には含まれていません。
新しいプラグイン クラスの作成
- 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 パラメーター 名前 ![[新しいイメージの登録] ダイアログ。](media/tutorial-update-plug-in-register-new-image-dialog.png)
イメージが登録されると、プラグイン登録ツールに表示されます。
重要
エンティティ イメージを作成する際の既定動作では、すべての列を選択します。 ただし、これは Web サービスのパフォーマンスを低下させる可能性があります。 開発者は必要な列のみを含める必要があります。
プラグインのテスト
アプリケーションを開き、既存の取引先企業名を
test、foo、またはbarに更新します。保存しようとすると、次のメッセージが表示されます。
test、foo、barを含む名前を持つ既存の取引先企業を更新した場合、取引先企業をtest、foo、またはbarに更新するとメッセージが表示されることはありません。
アセンブリ、プラグイン、ステップの登録解除
プラグイン登録ツールを使用して、アセンブリ、プラグイン、ステップを登録解除 (削除) します。 アセンブリを削除すると、そのアセンブリのすべてのプラグインと手順が削除されます。
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。