Azure 対応のカスタム プラグインの記述

Azure で動作するプラグインの記述は、他の Dataverse プラグインの記述と似ています。 ただし、必要な Web サービス メソッドを呼び出すだけでなく、プラグインには、現在のトランザクションの実行コンテキストを Azure Service Bus に投稿するコードを含める必要があります。

プラグインの設計に関する考慮事項

同期的に実行されるプラグインの場合、プラグインがリスナー アプリケーションまたはその他の外部サービスから情報を取得するためのメッセージを Azure に送信することをお勧めします。 Azure Service Bus エンドポイントで双方向または REST コントラクトを使用すると、データ文字列をプラグインに返すことができます。

同期プラグインで Azure Service Bus を使用して外部サービスでデータを更新することはお勧めしません。 外部サービスが使用できなくなった場合や、更新するデータが多い場合は、問題が発生する可能性があります。 同期プラグインは、時間の長い操作が実行されている間、組織のすべてのログイン ユーザーを保持せず、高速に実行する必要があります。 さらに、プラグインを呼び出した現在のコア操作のロールバックが発生した場合、プラグインによって行われたデータの変更は元に戻されます。 このロールバックによって、Dataverse と外部サービスが同期されていない状態になる可能性があります。

同期登録済みプラグインは、現在のトランザクションの実行コンテキストを Azure Service Bus にポストできます。

プラグイン コードを記述する

次のサンプル プラグインでは、Azure サービス プロバイダーを取得し、 Execute(EntityReference, IExecutionContext)を呼び出して Service Bus への実行コンテキストの投稿を開始するコードが追加されています。 プラグインをサンドボックスで実行する必要があるため、プラグインのデバッグを容易にするためにトレース コードが追加されました。

注

このコードのコンストラクターに渡されるserviceEndpointIdは、「チュートリアル: Dataverse との統合のために Azure (SAS) を構成する」で説明されているように、サービス エンドポイントの作成から得られるものです。

ブラウザーと次のようなクエリを使用して、Web API への GET 要求を使用して、環境で使用可能なサービス エンドポイントに対してクエリを実行できます。 [organization Uri]/api/data/v9.0/serviceendpoints?$select=name,description,serviceendpointid

using System;
using System.Diagnostics;
using System.Threading;
using System.Runtime.Serialization;

using System.ServiceModel;
using System.ServiceModel.Channels;
using System.ServiceModel.Description;

using Microsoft.Xrm.Sdk;

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A custom plug-in that can post the execution context of the current message to the Windows
    /// Azure Service Bus. The plug-in also demonstrates tracing which assist with
    /// debugging for plug-ins that are registered in the sandbox.
    /// </summary>
    /// <remarks>This sample requires that a service endpoint be created first, and its ID passed
    /// to the plug-in constructor through the unsecure configuration parameter when the plug-in
    /// step is registered.</remarks>
    public sealed class SandboxPlugin : IPlugin
    {
        private Guid serviceEndpointId; 

        /// <summary>
        /// Constructor.
        /// </summary>
        public SandboxPlugin(string config)
        {
            if (String.IsNullOrEmpty(config) || !Guid.TryParse(config, out serviceEndpointId))
            {
                throw new InvalidPluginExecutionException("Service endpoint ID should be passed as config.");
            }
        }

        public void Execute(IServiceProvider serviceProvider)
        {
            // Retrieve the execution context.
            IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            // Extract the tracing service.
            ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
            if (tracingService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the tracing service.");

            IServiceEndpointNotificationService cloudService = (IServiceEndpointNotificationService)serviceProvider.GetService(typeof(IServiceEndpointNotificationService));
            if (cloudService == null)
                throw new InvalidPluginExecutionException("Failed to retrieve the service bus service.");

            try
            {
                tracingService.Trace("Posting the execution context.");
                string response = cloudService.Execute(new EntityReference("serviceendpoint", serviceEndpointId), context);
                if (!String.IsNullOrEmpty(response))
                {
                    tracingService.Trace("Response = {0}", response);
                }
                tracingService.Trace("Done.");
            }
            catch (Exception e)
            {
                tracingService.Trace("Exception: {0}", e.ToString());
                throw;
            }
        }
    }
}

プラグイン コードでは、投稿を開始する前に、コンテキスト内の書き込み可能なデータを更新できます。 たとえば、コンテキスト内の共有変数にキーと値のペアを追加できます。

プラグイン登録

Azure 対応のカスタム プラグインを登録する場合、いくつかの制限があります。 サンドボックスで実行するには、プラグインを登録する必要があります。 サンドボックスの登録により、プラグインは、 IOrganizationService メソッド、Azure ソリューション メソッドの呼び出し、または Web クライアントを使用したネットワークへのアクセスに制限されます。 ローカル ファイル システムへのアクセスなど、他の外部アクセスは許可されません。

プラグインが非同期モードで実行されるように登録されている場合、他の非同期プラグインと比較したプラグインの実行順序は保証されません。 さらに、非同期プラグインは、常に Dataverse コア操作の後に実行されます。

失敗した Service Bus ポストを処理する

失敗した Service Bus ポストからの予期される動作は、プラグインが同期実行と非同期実行のどちらに登録されたかによって異なります。 非同期プラグインの場合、実際に実行コンテキストをサービス バスにポストするシステム ジョブは、ポストを再試行します。 同期登録済みプラグインの場合は、例外が返されます。 詳細情報 : 実行時エラーの管理と通知

Important

非同期登録済みプラグインの場合のみ、Azure Service Bus にポストする非同期ジョブが障害発生後に再試行されると、プラグイン ロジック全体が再度実行されます。 このため、コンテキストを変更して Service Bus に投稿する以外に、カスタム Azure 対応プラグインに他のロジックを追加しないでください。

プラグインが非同期的に実行されるように登録されている場合、Service Bus 経由で送信されるメッセージの本文に含まれる RemoteExecutionContext には、 OperationId プロパティと OperationCreatedOn プロパティが含まれます。 これらのプロパティには、関連するシステム ジョブ (AsyncOperationId) レコードのCreatedOn列およびAsyncOperation列と同じデータが含まれます。 これらの追加プロパティにより、Azure Service Bus のポストを再試行する必要がある場合のシーケンス処理と重複検出が容易になります。

こちらも参照ください

Azure 統合
Azure ソリューションで Microsoft Dataverse データを操作する
サンプル: Azure 対応カスタム プラグイン
プラグインを記述する
イベント実行パイプライン
プラグインの登録と展開