プラグインを記述する

  • [アーティクル]

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

プラグインは、IPlugin インターフェイスを実装したカスタム クラスです。 プラグインの記述には、.NET Framework 4.5.2 や Microsoft Visual C# など、Microsoft Visual Basic .NET CLR に準拠した任意の言語が使用できます。 プラグイン コードをコンパイルするためには、Microsoft.Xrm.Sdk.dll および Microsoft.Crm.Sdk.Proxy.dll アセンブリ参照をプロジェクトに追加する必要があります。 これらのアセンブリは、SDK の SDK\Bin フォルダーにあります。Microsoft Dynamics CRM SDK パッケージをダウンロードします。

このトピックの内容

プラグインの設計

基本的なプラグインを記述する

プラグイン コンストラクターを記述する

オフラインでの実行をサポートする

分離された (サンドボックスでセキュリティ保護された) プラグインの Web アクセス

事前バインド型の使用

プラグイン アセンブリ

プラグインの設計

プラグインの設計では、Microsoft Dynamics 365 (オンラインおよび設置型) で導入された自動保存機能と呼ばれる Web アプリケーションを考慮する必要があります。 自動保存は、既定で有効ですが、組織レベルで無効にできます。 自動保存を有効にすると、[保存] ボタンはありません。 Web アプリケーションは、保存されていない変更の 30 秒後にフォームのデータを自動的に保存します。 フォーム レベルで自動保存の動作を無効にするために、フォーム スクリプトを適用できます。 プラグインの登録方法によっては、自動保存により、すべての変更に対し 1 回プラグインが起動されるのではなく、フィールドの個々の変更に対しもっと頻繁にプラグインが呼び出される結果となることがあります。Ctrl+S を使用する、保存ボタンを押す、または自動的に自動保存が機能するなどいずれの方法でも、ユーザーがいつでもレコードを保存すると仮定する必要があります。

最も重要なエンティティや特定のフィールドにおいてプラグインまたはワークフローを登録することをお勧めします。 すべてのエンティティ フィールドに対する変更にプラグインまたはワークフローを登録しないでください。 自動保存機能が使用できる前に実装された既存のプラグインまたはワークフローを使用している場合は、コードを再テストしてそれが適切に動作するかを確認する必要があります。 詳細については、「TechNet: 自動保存の管理」を参照してください。

基本的なプラグインを記述する

次のサンプルはプラグインに含まれる一般的なコードの一部を示します。 このサンプルのコードでは、プラグイン本来のタスクを実行するカスタム ビジネス ロジックは省略しています。 しかし、IPlugin インターフェイスおよび必須の Execute メソッドを実装したプラグイン クラスを示しています。

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

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

        // The InputParameters collection contains all the data passed in the message request.
        if (context.InputParameters.Contains("Target") &&
            context.InputParameters["Target"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference which you will need for
            // web service calls.
            IOrganizationServiceFactory serviceFactory = 
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

Execute メソッドの IServiceProvider パラメーターは、プラグイン内でアクセスできるいくつかの有用なサービス オブジェクトのコンテナーです。 サービス プロバイダーには、実行コンテキスト、IOrganizationServiceFactory、ITracingService などへのインスタンス参照が含まれます。 このサンプル コードは、サービス プロバイダー パラメーターから実行コンテキスト、IOrganizationService、および ITracingService への参照を取得する方法を示しています。 トレース サービスに関する詳細については、「プラグインのデバッグ」を参照してください。

実行コンテキストには、プラグインの実行を引き起こしたイベントおよびパイプラインで現在処理されているメッセージ内のデータに関する多くの情報が含まれます。 データ コンテキストの詳細については、「プラグインに渡されるデータ コンテキストについて」を参照してください。

サービス プロバイダーから組織 Web サービス参照を取得するときに、プラットフォームによって適切な Web サービス URL とネットワーク資格情報が提供されます。 独自の Web サービス プロキシをインスタンス化すると、デッドロックおよび認証の問題が生じるので、このインスタンス化はサポートされていません。 組織サービス参照が得られたら、それを使用して組織 Web サービスに対するメソッド呼び出しを行うことができます。 Web サービスに対して 1 つ以上のメッセージ要求を発行することにより、単一の Microsoft Dynamics 365 組織のビジネス データを取得または変更できます。 このメッセージ要求の詳細については、「Execute メソッドでメッセージ (要求クラスおよび応答クラス) を使用する」を参照してください。

典型的なプラグインは、実行コンテキスト内の情報にアクセスし、必要なビジネス操作を実行し、例外を処理する必要があります。 プラグインでの例外の処理に関する詳細については、「プラグインでの例外の処理」を参照してください。 より完全なプラグインのサンプルは、「サンプル: 基本プラグインの作成」で示します。

重要

パフォーマンスを向上させるため、Microsoft Dynamics 365 ではプラグイン インスタンスをキャッシュしています。 プラグインの Execute メソッドはステートレスになるように記述する必要があります。プラグインの起動のたびにコンストラクターが呼び出されるわけではないためです。 また、プラグインを複数のシステムのスレッドが同時に実行する可能性があります。 各起動状態に関する情報はすべてコンテキストに格納されるので、データがコンストラクターで提供する構成パラメーターから取得されている場合を除き、グローバル変数を使用したり、次のプラグイン起動時に使用するデータをメンバー変数に格納するのは避けてください。 プラグイン登録を変更すると、そのプラグインは再初期化されます。

プラグイン コンストラクターを記述する

Microsoft Dynamics 365 は、1 つまたは 2 つの文字列パラメーターを受け付けるオプションのプラグイン コンストラクターをサポートしています。 このようなコンストラクターを記述する場合、実行時にプラグインに任意の文字列情報を渡すことができます。

次の例は、コンストラクターの形式を示しています。 この例では、プラグイン クラスの名前が SamplePlugin になっています。

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

コンストラクターの最初の文字列パラメーターには公開 (セキュリティで保護されていない) 情報が含まれます。 2 番目の文字列パラメーターには非公開 (セキュリティで保護された) 情報が含まれます。 ただし、ここでの "セキュリティで保護された" とは、暗号化された値を指します。また、"セキュリティで保護されていない" とは、暗号化されていない値を指します。オフライン アクセス対応 Microsoft Office Outlook 用 Microsoft Dynamics 365 を使用した場合、Outlook 用 Dynamics 365 がオフラインのときは、セキュリティで保護された文字列は実行されるプラグインに渡されません。

これらの文字列でプラグイン コンストラクターに渡される情報は、Microsoft Dynamics 365 へのプラグインの登録時に指定します。 プラグイン登録ツールを使用してプラグインを登録する場合、セキュリティで保護された情報とセキュリティで保護されていない情報を、[新しいステップの登録] フォームの [セキュリティで保護された構成] フィールドと [セキュリティで保護されていない構成] フィールドに入力できます。Microsoft Dynamics 365 SDK を使用してプラグインをプログラムで登録する場合、SdkMessageProcessingStep.Configuration にセキュリティで保護されていない値が含まれ、SdkMessageProcessingStep.SecureConfigId はセキュリティで保護された値が含まれる SdkMessageProcessingStepSecureConfig レコードを指します。

オフラインでの実行をサポートする

プラグインは、オンライン モード、オフライン モード、または両方のモードで実行されるように登録できます。 オフライン モードは オフライン アクセス対応 Microsoft Office Outlook 用 Microsoft Dynamics 365 でのみサポートされます。 プラグイン コードで、プラグインがオフライン モードで実行されているかどうかをチェックできます。それには、IsExecutingOffline プロパティをチェックします。

オンライン実行とオフライン実行の両方で登録されるプラグインを設計するときは、プラグインが 2 回実行される可能性があることに留意してください。 1 回目は、オフライン アクセス対応 Microsoft Office Outlook 用 Microsoft Dynamics 365 がオフラインのときです。 さらに、Outlook 用 Dynamics 365 がオンラインになって、Outlook 用 Dynamics 365 と Microsoft Dynamics 365 サーバーの間で同期が行われるときに再び実行されます。IsOfflinePlayback プロパティを調べると、この同期に起因してプラグインが実行されているかどうかを確認できます。

分離された (サンドボックスでセキュリティ保護された) プラグインの Web アクセス

プラグインをサンドボックスに登録する予定だとしても、プラグイン コードから Web アドレスにアクセスできます。 Web アクセス制限の範囲内で Web アクセスを提供する任意の .NET Framework クラスをプラグイン コード内で使用できます (これについては「プラグイン分離、信頼、および統計」で概説します)。 たとえば、次のプラグイン コードは Web ページをダウンロードします。


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security セキュリティ メモ

サンドボックス プラグインで外部 Web サービスにアクセスできるようにするには、処理サービス ロールがインストールされているサーバーをインターネットに公開する必要があり、サンドボックス サービスを実行するアカウントにインターネットへのアクセス権が必要です。 ポート 80 および 443 での送信接続のみが必要です。 受信接続アクセスは必要ありません。 %PROGRAMFILES%\Microsoft Dynamics 365\Server\bin フォルダー内のサーバーにある Microsoft.Crm.Sandbox.WorkerProcess アプリケーションに対して送信接続を有効にするには、コントロール パネルの [Windows ファイアウォール] を使用します。

事前バインド型の使用

Microsoft Dynamics 365 の事前バインド型をプラグインで使用するには、CrmSvcUtil プログラムで生成される型ファイルを単に Microsoft Visual Studio のプラグイン プロジェクトに含めます。

遅延バインド エンティティから事前バインド型エンティティへの変換は次のように処理されます。

Account acct = entity.ToEntity<Account>();

上記のコードでは、acct 変数が事前バインド型です。Entity に代入されるすべての IPluginExecutionContext 値は遅延バインド型でなければなりません。 事前バインド型がコンテキストに代入された場合、SerializationException が発生します。 詳細については、「プラグインに渡されるデータ コンテキストについて」を参照してください。 型を混合して使用し、次のコードのように遅延バインド型が呼び出されるところで事前バインド型を使用するのは避けてください。

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

上記の例では、遅延バインド インスタンスのためのプラグイン コンテキストに事前バインド インスタンスを格納してはなりません。 これは、プラグインを呼び出す前とプラグインからプラットフォームに復帰するときにプラットフォームが事前バインド型と遅延バインド型の間の変換を行わなければならなくなるのを避けるためです。

プラグイン アセンブリ

アセンブリには 1 種類以上のプラグインが存在できます。 プラグイン アセンブリの登録および展開が終われば、プラグインは Microsoft Dynamics 365 実行時イベントへの応答として所定の操作を実行できます。

System_CAPS_security セキュリティ メモ

Microsoft Dynamics 365 で、プラグイン アセンブリが正しく機能するには、プラグイン アセンブリをすべてのユーザーに対して読み取り可能にする必要があります。 したがって、セキュリティ上、システム ログオン情報、機密情報、または企業秘密を含むプラグイン コードを開発しないことを強くお勧めします。

Microsoft Dynamics 365 に登録して展開する前に、各プラグイン アセンブリに署名する必要があります。それには、Microsoft Visual Studio のプロジェクトのプロパティ シートの [署名] タブまたは Strong Name ツールを使用します。 Strong Name ツールの詳細を確認するには、Microsoft Visual Studio コマンド プロンプト ウィンドウから、引数を指定しないで sn.exe プログラムを実行します。

Outlook 用 Dynamics 365 がオフラインのときに実行できるプラグインがアセンブリに含まれる場合、Microsoft Dynamics 365 プラットフォームがアセンブリに課す追加のセキュリティがあります。 詳細については、「チュートリアル: オフライン プラグインのアセンブリ セキュリティの構成」を参照してください。

関連項目

プラグインの開発
プラグインに渡されるデータ コンテキストについて
Azure 対応のカスタム プラグインの記述
プラグインの登録および展開
プラグインでの例外の処理
サンプル: 基本プラグインの作成
サンプル: 隔離されたプラグインからの Web アクセス
コード生成ツールの実行
ブログ: Using Plug-Ins To Modify Views (プラグインを使用してビューを変更する)

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権