プラグインを記述する

[アーティクル]
07/06/2017

公開日: 2016年11月

対象: Dynamics CRM 2015

プラグインは、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 CRM 2015 および Microsoft Dynamics CRM Online 2015 更新プログラムで導入された自動保存機能と呼ばれる 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 CRM を使用した場合、Outlook 用 Dynamics CRM がオフラインのときは、セキュリティで保護された文字列は実行されるプラグインに渡されません。

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

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

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

オンライン実行とオフライン実行の両方で登録されるプラグインを設計するときは、プラグインが 2 回実行される可能性があることに留意してください。 1 回目は、オフラインアクセス対応 Microsoft Office Outlook 用 Microsoft Dynamics CRM がオフラインのときです。さらに、Outlook 用 Dynamics CRM がオンラインになって、Outlook 用 Dynamics CRM と 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);

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

サンドボックスプラグインで外部 Web サービスにアクセスできるようにするには、処理サービスロールがインストールされているサーバーをインターネットに公開する必要があり、サンドボックスサービスを実行するアカウントにインターネットへのアクセス権が必要です。ポート 80 および 443 での送信接続のみが必要です。受信接続アクセスは必要ありません。 %PROGRAMFILES%\Microsoft Dynamics CRM\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 実行時イベントへの応答として所定の操作を実行できます。

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

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

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

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

次の方法で共有

プラグインを記述する

このトピックの内容

プラグインの設計

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

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

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

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

事前バインド型の使用

プラグインアセンブリ

関連項目

その他のリソース

次の方法で共有

プラグインを記述する

このトピックの内容

プラグインの設計

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

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

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

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

事前バインド型の使用

プラグイン アセンブリ

関連項目

その他のリソース

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

プラグインアセンブリ