NotificationTransportClass.OnCompletion イベント

[アーティクル]
03/19/2008

SendNotification メソッドを使用して非同期モードで送信された通知は、処理のためにキューに入れられ、メソッド呼び出しはすぐに復帰します。次に、トランスポートオブジェクトは、キューに入っている通知をできるだけ早く処理して、.NET Alerts ルーティングエンジンに配信しようとします。キューに入っている通知が処理され、キューから削除されるたびに、トランスポートオブジェクトは配信状態に関する情報を含む OnCompletion イベントを呼び出します。非同期モードで通知を送信する場合は、OnCompletion イベントのイベントハンドラを実装する必要があります。

シグネチャ

void MethodName(int hr, short HttpStatus, int Token)

パラメータ

hr
long 型整数 (HRESULT)。送信状態を示します。hr が成功状態を示す場合は、通知が Microsoft® .NET Alerts ルーティングエンジンに正常に配信されました。
HttpStatus
整数。.NET Alerts ルーティングエンジンから返された HTTP 状態コードを示します。
Token
long 型整数。このイベントが呼び出される送信の識別に使用されるトークンを示します。通知の送信時に指定された SendNotification メソッドの Token パラメータと一致します。

例

次のサンプルコードは、OnCompletion イベントを処理するクラスの実用的な実装を示しています。

class OnCompletionEventHandler
{
    public OnCompletionEventHandler(NotificationTransportClass Transport)
    {
        // The constructor connects the local event handler (ProcessOnCompletion)
        // to the OnCompletion event for the transport object.
        this.Transport = Transport;

        // If you used Visual Studio .NET to generate a COM interop assembly, the top-
        // level qualifier for the new object is MSNOTIFYLib.
        Transport.OnCompletion +=
            new MSNOTIFYLib._INotificationTransportEvents_OnCompletionEventHandler(
                ProcessOnCompletion);

        // If you used TlbImp to generate a COM interop DLL, the top-level qualifier will
        // be the same as the base file name you chose for the DLL. In this example,
        // the DLL is named msnotify_interop.dll. For more information, see NotificationTransportClass.SendNotification Method.
        // Transport.OnCompletion +=
        //    new msnotify_interop._INotificationTransportEvents_OnCompletionEventHandler(
        //        ProcessOnCompletion);

    } // End constructor.

    // The OnCompletion event handler must conform to this signature.
    void ProcessOnCompletion(int hr, short HttpStatus, int Token)
    {

        Console.WriteLine("An alert has been processed.");
        Console.WriteLine("hr         = 0x{0}", hr.ToString("x"));
        Console.WriteLine("HttpStatus = {0}", HttpStatus);
        Console.WriteLine("Token      = {0}", Token);
    
    } // End ProcessOnCompletion.

    NotificationTransportClass  Transport;

} // End OnCompletionEventHandler class.

OnCompletion イベントハンドラをトランスポートオブジェクトに接続するには、OnCompletion イベントハンドラオブジェクトを作成するときに、トランスポートオブジェクトをコンストラクタの引数として渡します。次の例では、トランスポートオブジェクトとそのトランスポートに接続される OnCompletion ハンドラオブジェクトを宣言して作成します。このコードでは、Transport が送信キューに入っている通知を処理して OnCompletion イベントを呼び出すたびに、このイベントは Handler によって処理されます。

NotificationTransportClass   Transport   = new NotificationTransportClass();
OnCompletionEventHandler    Handler = new OnCompletionEventHandler(Transport);

次のサンプルコードは、非同期で初期化されて送信される通知を示しています。このコードと SendNotification トピックのサンプルコードとの違いは、WaitForCompletion の値だけです。このサンプルコードでは、SendNotification の呼び出しはすぐに復帰し、通知はトランスポートオブジェクトの送信キューに格納されます。トランスポートが通知を処理すると、OnCompletion イベントが呼び出され、前述の OnCompletion イベントハンドラの ProcessOnCompletion メソッドで指定したコードが実行されます。前の例では、ProcessOnCompletion はメッセージとそのメッセージに渡されるパラメータの値を出力します。次のコードでは、SendNotification に渡されるトークンを通知 ID (この場合は "12345") と同じ値に設定します。この通知に対して OnCompletion イベントが発生すると、ProcessOnCompletion メソッドは Token の値 12345 と、操作に対する HTTP 状態および HRESULT を受信して出力します。

static void DemoSendNotification(
            MsnNotificationClass Alert,
            NotificationTransport Transport)
{
    string UserName = null;
    string Password = null;
                // WaitForCompletion is used as the first argument to the following SendNotification
                // call. If it is set to 0, as it is here, the call will be asynchronous. If this parameter
                // is set to 1, this sample code will send alerts synchronously.
                // If you send alerts asynchronously, be sure to specify an event
                // handler for the OnCompletion event.
    int    WaitForCompletion = 0;
    int    Token;

    // Initialize the alert.
    Alert.ID            = "12345";
    Alert.ToPID     = "0x01234567:0x89abcdef";
    Alert.MessageID     = "0";
    Alert.Priority      = "1";
    Alert.SiteURL       = "https://www.adventure-works.com";
    // The relative path to the action URL page, including two custom parameters, param1 and param2.
    // Note that the ampersand is XML-encoded.
    Alert.ActionURL     = "/action.asp?param1=data1&param2=data2";
    // Specifies the user PUID as an argument to the subscription URL.
    Alert.SubscribeURL          = "/subscr.asp";
    Alert.BodyIcon      = "/aw_logo.png";
    Alert.BodyLanguage          = "1033";
    Alert.Body          = "<TEXT>Your Adventure Works order has been shipped!</TEXT>";
    // Do not specify the site ID if you have used InstallSDKKey.exe.
    // Alert.SiteID     = "114001000";

    // Initialize the transport.  If the transport has previously been used to send an alert,
    // the destination URL property has become read-only. Writing to it will cause a
    // catastrophic failure.
    //
    // This code attempts to send the alert to a .NET Alerts routing engine emulator on the local computer.
    // The URL for the PREP .NET Alerts routing engine will be provided when you register to become a .NET Alerts provider.
    try
    {
        Transport.DestinationUrl = "https://localhost/MSAlertsSDKServer/MSAlertsSDKServer.dll";
    } // end try

    // If writing to the property raises an exception, assume the transport has been
    // previously initialized and continue.
    catch {}

    Token = System.Convert.ToInt32(Alert.ID);

    Console.Write("Sending the alert...  ");

    // Send the alert.
    try
    {
        Transport.SendNotification(WaitForCompletion,UserName, Password, Alert, Token);
    } // End try.

    catch (COMException hr) // Non-COM exceptions will propagate to Main().
    {
        Console.WriteLine("A COM error occurred while calling SendNotification: 0x{0} {1}",
            hr.ErrorCode.ToString("x"),
            hr.Message);

        return;
    } // End catch.

    Console.WriteLine("Alert transmitted successfully.\n");

} // End DemoSendNotification.

解説

hr が成功状態を示す場合は、Microsoft .NET Alerts ルーティングエンジンによって通知が処理のために受け入れられました。結果コードは、.NET Alerts ルーティングエンジンによって通知が処理のために受け入れられたかどうかのみを示します。通知が最終的な配信先に配信されたかどうかは示しません。最初に処理のために受け入れられた通知は、その後 .NET Alerts ルーティングエンジンによって削除 (サイレントで破棄) される場合があります。

通知の送信は、次のいずれかの理由で .NET Alerts ルーティングエンジンによって拒否される場合があります。その場合は、送信者にエラーが返されます。

credential が不足しているか正しくないため、トランスポートが .NET Alerts ルーティングエンジンで認証されません。
配信先 URL が正しくありません。
通知のプロパティの形式に誤りがあるか、プロパティが正しくありません。
一時的なネットワークエラーのために、通知が .NET Alerts ルーティングエンジンに到達できません。

.NET Alerts ルーティングエンジンは、次のいずれかの理由で、受け入れた後に通知を削除する場合があります。その場合は、送信者にエラーは返されません。

受信者の PUID が無効か、または存在しません。
受信者の PUID に、通知を送信する .NET Alerts プロバイダとのサブスクリプションがありません。
受信者が、通知を送信する .NET Alerts プロバイダからの通知の配信設定で、[この通知を受信しない] オプションを選択しました。
.NET Alerts ルーティングエンジンに内部エラーが発生しました。

現時点では、通知が配信されたことを確認する唯一の方法は、通知に埋め込まれているアクション用 URL を受信者が呼び出すかどうかを調べることです。

NotificationTransportClass の MaxQueueSize プロパティを使用すると、通知を非同期で送信するために使用するトランスポートオブジェクトのパフォーマンスを調整することができます。詳細については、「NotificationTransportClass クラス」を参照してください。

トランスポートオブジェクトを使用して通知を非同期で送信した場合は、DrainNotifications を呼び出して送信キューに通知が存在しないことを確認してから、トランスポートオブジェクトを破棄するようにしてください。複数のスレッドから通知を送信する場合は、現在通知を送信しようとしているスレッドが他にないことを確認してから DrainNotifications を呼び出してください。詳細については、「NotificationTransportClass.DrainNotifications メソッド」を参照してください。

次の方法で共有

NotificationTransportClass.OnCompletion イベント

その他のリソース