NotificationTransportClass.SendNotification メソッド

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

このメソッドを呼び出すと、MsnNotification オブジェクトを Microsoft® .NET Alerts ルーティングエンジンに送信することができます。

定義

Public Sub SendNotification(ByVal WaitForCompletion As Integer, _
    ByVal wszUsername As String, _
    ByVal wszPassword As String, _
    ByVal Notification As msnotify_interop.MsnNotification,  _
    ByVal Token As Integer)

パラメータ

WaitForCompletion
同期モード (1) または非同期モード (0) のどちらで操作するかを示す整数です。同期モードでは、トランスポートの送信メソッドは通知が送信されるまで復帰しません。送信に失敗すると、エラーコードが返されます。非同期モードでは、送信メソッドはすぐに復帰し、トランスポートオブジェクトは通知をいつ送信するかを決めます。トランスポートオブジェクトが非同期モードで通知の送信要求を処理すると、送信状態を示す OnCompletion イベントが呼び出されます。非同期モードでは通知の送信が正しい順序で行われない可能性があるため、送信メソッドの呼び出し時に指定された Token を使用して OnCompletion イベントが特定の送信にリンクされます。詳細については、「NotificationTransportClass.OnCompletion イベント」を参照してください。
wszUsername
.NET Alerts プロバイダの名前が含まれる文字列です。この名前は、登録時にプロバイダによって決められます。.NET Alerts プロバイダキーのインストールユーティリティを実行した場合は、このパラメータを NULL 文字列にします。
wszPassword
.NET Alerts プロバイダの秘密のパスワードが含まれる文字列です。このパスワードは、登録時に Microsoft によって提供されます。.NET Alerts プロバイダキーのインストールユーティリティを実行した場合は、このパラメータを NULL 文字列にします。
Notification
正しく初期化された、送信する MsnNotificationClass オブジェクトです。
Token
現在の送信に関連付けられるトークンの値が含まれる整数です。非同期送信モードが使用されている (WaitForCompletion が 0 である) 場合に、Token で指定した値が OnCompletion イベントに渡されて、どのメッセージ送信が完了したかが識別されます。

例外

次のエラー値が、System.Runtime.InteropServices.COMException オブジェクトとして、Component Object Model (COM) の相互運用層から返される場合があります。

0x00000008	送信キューに入っている通知の数が MaxQueueSize プロパティで指定した数を超えています。DrainNotifications を使用して送信キューに入っている通知の一部を処理してから、操作をやり直してください。
0x80000002	内部で使用するためのメモリを割り当てているときに問題が発生しました。可能であれば、一部のシステムリソースを解放してから操作をやり直してください。
0x80000003	wszUsername または wszPassword のいずれか (両方ではない) が NULL 文字列でした。wszUsername と wszPassword の両方を NULL 文字列に設定する (レジストリに格納されている credential を使用している場合) か、wszUsername と wszPassword の両方に NULL 文字列以外の値を指定します。
0x80004005	メソッドが同期モードで呼び出され、エラー (200 ～ 299 グループに含まれないもの) を示す HTTP 状態コードが生成されました。
0x80072AF9	配信先 URL で指定したホスト名を解決する際に問題が発生しました。配信先 URL が正しいことを確認し、通知を送信しているサーバーのネットワーク接続を調べてから、操作をやり直してください。
0x81fd0001	Microsoft Windows® レジストリから .NET Alerts プロバイダの credential を取り出す際に問題が発生しました。InstallSDKKey.exe ユーティリティをもう一度実行してください。それでも問題が解決しない場合は、Microsoft 製品サポートサービスに問い合わせてください。詳細については、「サポートを利用する」を参照してください。
0x81fd0002	DrainNotifications を待っているときに送信要求が出されました。DrainNotifications の呼び出しが復帰するのを待ってから、操作をやり直してください。
0x81fd0003	Notification で指定した通知を処理しているときに、.NET Alerts クライアントライブラリに内部エラーが発生しました。エラーを返したサーバーのリソースが不足していないことを確認し、通知のプロパティが適正な値に設定されていることを確かめてから、操作をやり直してください。
0x81fd0004	メモリまたはリソースの問題が原因で、HTTP トランスポートにエラーが発生しました。可能であれば、一部のシステムリソースを解放してから操作をやり直してください。
0x81fd0190	Notification で指定した通知オブジェクトに対して生成された通知パケットが長すぎる (2048 バイトを超えている) か、通知パケットを解析する際に .NET Alerts ルーティングエンジンに問題が発生しました。通知のプロパティが適正な値に設定されていることを確認してから、操作をやり直してください。AddToPID メソッドを使用して通知に複数の PUID を指定している場合は、1 つの通知に含まれる PUID の数を減らすようにしてください。
0x81fd0191	.NET Alerts プロバイダの認証に失敗しました。このエラーは、wszUsername で指定した .NET Alerts プロバイダ名または wszPassword で指定したパスワードが正しくない場合、あるいはレジストリに格納されている credential が正しくない場合に返されます。ユーザー名とパスワードを確認するか、InstallSDKKey.exe ユーティリティをもう一度実行してから、操作をやり直してください。それでも問題が解決しない場合は、Microsoft 製品サポートサービスに問い合わせてください。詳細については、「サポートを利用する」を参照してください。
0x81fd01f4	一般的な配信エラーが発生しました。1 つまたは複数の通知プロパティが正しくない場合、配信先 URL が正しくない場合、またはネットワークに一時的な問題が発生した場合に、このエラーが返されます。通知のプロパティと配信先 URL を確認してから、操作をやり直してください。
0x81fd01f5	.NET Alerts ルーティングエンジンに重い負荷がかかり、ビジー状態になっているため、通知を処理できませんでした。操作をやり直してください。
0x81fd0257	通知の SiteID プロパティで指定した Site ID が、wszUsername パラメータで指定した .NET Alerts プロバイダ名に関連付けられている Site ID と一致しませんでした。正しいプロバイダ名と Site ID を使用していることを確認してから、操作をやり直してください。
0x81fd0258	.NET Alerts ルーティングエンジンの内部エラーのため、この通知を配信できませんでした。操作をやり直してください。それでも問題が解決しない場合は、Microsoft 製品サポートサービスに問い合わせてください。詳細については、「サポートを利用する」を参照してください。
0x81fd02bc	指定された単位時間内に送信された通知の数が、Microsoft .NET Services 契約で指定された制限を超えました。通知の送信速度を低くして、操作をやり直してください。詳細については、NET Services 契約を参照してください。

ここに示すリターンコードの他に、.NET Alerts クライアントライブラリのメソッドによって、標準の Microsoft Win32® または COM の結果コードがシステムの下位層から返される場合があります。Microsoft Visual Studio® のエラー照合ツールを使用すると、これらの標準結果コードに関連付けられたヘルプテキストを表示できます。

例外が発生しない場合は、呼び出しが正常に行われました。非同期モードでは、通知がトランスポートの送信用配信キューに格納されたことを意味します。同期モードでは、通知が .NET Alerts ルーティングエンジンによって処理のために受け入れられたことを意味します。

例

次の例は、SendNotification メソッドの使い方を示しています。

Sub DemoSendNotification(ByRef Transport As msnotify_interop.NotificationTransportClass, _
    ByRef Alert As msnotify_interop.MsnNotificationClass)

    Dim Username As String = vbNullString
    Dim Password As String = vbNullString
    ' WaitForCompletion is used as the first argument to the following SendNotification call.
    ' If it is set to 1, as it is here, the call will be synchronous. If this parameter is set to 0, this
    ' sample code will send alerts asynchronously. If you send alerts asynchronously, be sure to specify an
    ' event handler for the OnCompletion event. For more information, see NotificationTransportClass.OnCompletion Event.

    Dim WaitForCompletion As Integer = 1
    Dim Token As Integer

    ' 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"
    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"
    Catch
        ' If writing to the property raises an exception, assume the transport has been
        ' previously initialized and continue.
    End Try

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

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

    ' You should always include some retry logic in your alert-sending code. Sometimes a transient
    ' network problem will cause a SendNotification call to fail. The send operation will often
    ' succeed upon another attempt.  The following series of try/catches tries to send the alert up
    ' to three times and accepts failure only if the send operation raises an exception three times
    ' in a row.
    Try

        ' First try.
        Transport.SendNotification(WaitForCompletion, Username, Password, Alert, Token)

    Catch e1 As System.Runtime.InteropServices.COMException ' Non-COM exceptions will propagate to Main().

        ' Wait a second to allow transient network problems to resolve.
        Thread.Sleep(1000)
        Try

            ' Second try.
            Transport.SendNotification(WaitForCompletion, Username, Password, Alert, Token)

        Catch e2 As System.Runtime.InteropServices.COMException

            Thread.Sleep(1000)
            Try

                ' Third try.
                Transport.SendNotification(WaitForCompletion, Username, Password, Alert, Token)

            Catch hr As System.Runtime.InteropServices.COMException

    ' Custom error codes by the .NET Alerts SDK match 0x81fdxxxx.
    If (Not (hr.ErrorCode & &HFFFF0000) = &H81FD0000) Then

                    Console.WriteLine("A COM error occurred while calling SendNotification: 0x{0} {1}", _
                        hr.ErrorCode.ToString("x"), _
                        hr.Message)

                Else

                    Dim ErrorMessage As String

                    Select Case (hr.ErrorCode)

                        Case (&H81FD0001)
                            ErrorMessage = _
                            "There was a problem retreiving the .NET " + _
                            "Alerts provider credentials from the registry."

                        Case (&H81FD0002)

                            ErrorMessage = _
                            "A send request was made while waiting for DrainNotifications."

                        Case (&H81FD0004)

                            ErrorMessage = _
                            "Memory or resource issues caused a failure in the HTTP transport."

                        Case (&H81FD0191)

                            ErrorMessage = _
                            "Authentication of the .NET Alerts provider failed."

                        Case (&H81FD01F4)

                            ErrorMessage = _
                            "There was a general delivery failure."

                        Case Else

                            ErrorMessage = _
                            "An unexpected error occurred."

                    End Select

                    Console.WriteLine("A COM error occurred while calling SendNotification: 0x{0} {1}", _
                        hr.ErrorCode.ToString("x"), _
                        ErrorMessage)

                End If

                Return

            End Try
        End Try
    End Try

    Console.WriteLine("Alert transmitted successfully.")
    Console.WriteLine("")

    ' After SendNotification has been called, the properties on the transport
    ' object become read-only. The following call set operation will always fail
    ' with a catastrophic error.
    Try
        Transport.DestinationUrl = "http://some-other-url/nrouter/nrouter.dll"
    
    Catch hr As System.Runtime.InteropServices.COMException ' Non-COM exceptions will propagate to Main().

        Console.WriteLine("This call to put_DestiationUrl will alway fail, because the property")
        Console.WriteLine("becomes READ-ONLY after the first time SendNotification is called.")

        Console.WriteLine("A COM error occurred while calling SendNotification: 0x{0} {1}", _
            hr.ErrorCode.ToString("x"), _
            hr.Message)

    End Try

    End Sub

解説

Microsoft では、Microsoft Windows レジストリに .NET Alerts プロバイダの credential をインストールするユーティリティを提供しています。セキュリティ保護に役立つように、このユーティリティは credential の一部分を暗号化します。通常の (Production) 環境のもとでは、SendNotification メソッドは必要な credential をレジストリから取り出します。パスワードとユーザー名のパラメータは、NULL 文字列 (vbNullString) にする必要があります。SendNotification の呼び出しにユーザー名とパスワードを指定すると、レジストリに格納されている credential が使用できなくなります。この作業は、テストの場合にのみ行ってください。Production システムでは、レジストリに格納されている credential を使用するようにします。詳細については、「InstallSDKKey.exe を使用する」を参照してください。

注 InstallSDKKey.exe のコピーが .NET Alerts Developer Edition に含まれています。このコピーには、.NET Alerts Developer Edition でのみ使用するよう意図されたダミーの credential が含まれています。InstallSDKKey.exe のこのコピーによってインストールされる credential は、実際の .NET Alerts ルーティングエンジンでは機能しません。このため、Preproduction (PREP) または Production 環境の .NET Alerts ルーティングエンジンに通知を送信するには、自分が .NET Alerts プロバイダになるように登録して、自分の credential を取得する必要があります。詳細については、「アプリケーションを登録する」を参照してください。

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

通知送信コードには、必ず再試行ロジックを組み込むようにしてください。ネットワークに一時的な問題が発生すると、SendNotification 呼び出しが失敗することがあります。このような場合、再試行によって送信操作がうまくいくことがよくあります。

.NET Alerts クライアントライブラリは、SendNotification の呼び出しが失敗するたびに、エラーログエントリを Windows のアプリケーションイベントログに書き出します。このログエントリには、メソッド呼び出しからのリターンコード、HTTP 状態コード、およびエラーを生成した呼び出しの Token パラメータの値が含まれています。イベントビューアを使用すると、アプリケーションイベントログに含まれるこれらのエントリを調べることができます。

SendNotification の同期呼び出しに対して例外が発生しなかった場合は、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 を受信者が呼び出すかどうかを調べることです。通知の配信先を調べる方法については、「MsnNotificationClass.ActionURL プロパティ」を参照してください。

次の方法で共有

NotificationTransportClass.SendNotification メソッド

その他のリソース