XML Web サービスでの例外の処理およびスロー

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

ASP.NET を使用して作成した XML Web サービスによってスローされる例外は、SOAP 違反の形式でクライアントに返信されます。SOAP 違反とは、エラーが発生する状況を指定する、SOAP メッセージ内の <Fault> XML 要素です。SOAP 違反を渡すときは、ASP.NET では、SOAP 仕様によって規定されているクライアントにエラーを返信するためのメソッドに従います。SOAP <Fault> XML 要素には、例外文字列、例外の発生元などの詳細が含まれています。SOAP 違反の詳細については、W3C Web サイト (http://www.w3.org/TR/SOAP) を参照してください。

ASP.NET を使用して作成した XML Web サービスとクライアントは両方とも、<Fault> XML 要素を直接指定または解析せず、例外をスローおよびキャッチするための NET Framework の共通デザインパターンを使用します。XML Web サービスでは、ArgumentOutOfRangeException または SoapException など、問題に固有の例外をスローすることもできます。いずれの方法でも、ASP.NET では、例外を SOAP 違反要素に配置することによって、その例外を有効な SOAP メッセージにシリアル化します。SOAP メッセージが ASP.NET クライアントで逆シリアル化されると、SOAP 違反は SoapException 例外に変換され、例外の詳細は Message プロパティに配置されます。これにより、クライアントが Try/Catch ブロックを設定して SoapException をキャッチできます。

Web アプリケーションは複数の XML Web サービスから構成できますが、Global.asax ファイル内の Application_Error イベントをグローバル例外の処理に使用することはできません。XML Web サービスの HTTPHandler は、XML Web サービスの実行中に発生した例外を処理し、その例外を Application_Error イベントを呼び出す前に SOAP 違反に変換します。SOAP 拡張機能を作成し、グローバル例外ハンドラで XML Web サービスの例外を処理します。SOAP 拡張機能では、ProcessMessage メソッドで例外の有無を確認できます。ProcessMessage メソッド内では、Stage プロパティが AfterSerialize に設定されるときに渡される SoapMessage の Exception プロパティをチェックします。SOAP 拡張機能の詳細については、「SOAP 拡張機能を使用した SOAP メッセージの変更」を参照してください。

ASP.NET を使用して作成した XML Web サービスからの例外のスロー

例外をスローすることによって、エラーをクライアントに反映させることができます。XML Web サービスから例外をスローする方法は 4 つあります。

SoapException 例外をスローします。
SoapHeaderException 例外をスローします。
問題に固有の例外をスローします。
ASP.NET が例外をスローできるようにします。

XML Web サービスで明示的にスローできる例外、および ASP.NET クライアントが各例外を受け取る方法を次の表に示します。

スローする例外の型	XML Web サービスの動作
SoapException および SoapHeaderException 以外の例外	XML Web サービスメソッドが、例外となる事態を検出して ArgumentOutOfRangeException などの特定の例外をスローし、クライアントに返します。ASP.NET クライアントは、詳細情報が Message プロパティのテキストにシリアル化されている SoapException を受け取ります。
SoapException	XML Web サービスメソッドが、例外となる事態を検出して SoapException をスローします。また、問題に関する追加の詳細情報も提供します。XML Web サービスメソッドは、Detail プロパティを指定することで、その追加情報を提供します。ASP.NET クライアントが、この追加情報を含む SoapException を受け取ります。
SoapHeaderException	XML Web サービスメソッドが、SOAP ヘッダーの処理時に例外となる事態を検出します。この XML Web サービスメソッドは、SOAP の指定に応じて、SoapHeaderException をスローしてクライアントに返す必要があります。ASP.NET クライアントが、SoapHeaderException を受け取ります。

XML Web サービスから例外をスローするには

上の表で説明した SoapException または SoapHeaderException など、問題に固有の例外をスローします。

SoapException をスローし、Detail プロパティを設定することによって例外の追加詳細を提供するコード例を次に示します。

<%@ WebService Language="VB" class="ThrowSoapException"%>

Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols
Imports System.Xml.Serialization
Imports System.Xml

Public Class ThrowSoapException
    Inherits WebService

    ' This XML Web service method throws a SOAP client fault code. 
    <WebMethod()> _
    Public Sub myThrow()

        ' Build the detail element of the SOAP fault.
        Dim doc As New System.Xml.XmlDocument()
        Dim node As System.Xml.XmlNode = _            doc.CreateNode(XmlNodeType.Element, _            SoapException.DetailElementName.Name, _            SoapException.DetailElementName.Namespace)

        ' Build specific details for the SoapException.
        ' Add first child of detail XML element.
        Dim details As System.Xml.XmlNode = _             doc.CreateNode(XmlNodeType.Element, _            "mySpecialInfo1", "http://tempuri.org/")

        ' Add second child of detail XML element with an attribute.
        Dim details2 As System.Xml.XmlNode = _            doc.CreateNode(XmlNodeType.Element, _            "mySpecialInfo2", "http://tempuri.org/")
        Dim attr As XmlAttribute = doc.CreateAttribute("t", _ 
            "attrName", "http://tempuri.org/")
        attr.Value = "attrValue"
        details2.Attributes.Append(attr)

        ' Append the two child elements to the detail node.
        node.AppendChild(details)
        node.AppendChild(details2)

        'Throw the exception.
        Dim se As New SoapException("Fault occurred", _            SoapException.ClientFaultCode, _            Context.Request.Url.AbsoluteUri, node)
        Throw se
        Return
    End Sub
End Class
[C#]
<%@ WebService Language="C#" class="ThrowSoapException"%>

using System;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Xml.Serialization;
using System.Xml;

public class ThrowSoapException : WebService 
{
    // This XML Web service method throws a SOAP client fault code.
    [WebMethod]
    public void myThrow(){

        // Build the detail element of the SOAP fault.
        System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
        System.Xml.XmlNode node = doc.CreateNode(XmlNodeType.Element,             SoapException.DetailElementName.Name,              SoapException.DetailElementName.Namespace);

        // Build specific details for the SoapException.
        // Add first child of detail XML element.
        System.Xml.XmlNode details =
          doc.CreateNode(XmlNodeType.Element, "mySpecialInfo1",
                         "http://tempuri.org/");
        System.Xml.XmlNode detailsChild =           doc.CreateNode(XmlNodeType.Element, "childOfSpecialInfo",                         "http://tempuri.org/");
        details.AppendChild(detailsChild);

        // Add second child of detail XML element with an attribute.
        System.Xml.XmlNode details2 =          doc.CreateNode(XmlNodeType.Element, "mySpecialInfo2",                         "http://tempuri.org/");
        XmlAttribute attr = doc.CreateAttribute("t", "attrName",
                            "http://tempuri.org/");
        attr.Value = "attrValue";
        details2.Attributes.Append(attr);

        // Append the two child elements to the detail node.
        node.AppendChild(details);
        node.AppendChild(details2);

        //Throw the exception            SoapException se = new SoapException("Fault occurred",          SoapException.ClientFaultCode,          Context.Request.Url.AbsoluteUri ,          node);

        throw se;
        return;
    }
}

XML Web サービスメソッドによってスローされた例外をキャッチするには

Try/Catch ブロック内で SoapException をキャッチします。XML Web サービスメソッドによってスローされる例外は、SoapException としてスローされます。

XML Web サービスメソッドを呼び出すクライアントが、その XML Web サービスメソッドによってスローされた例外をキャッチする例を次に示します。その後、クライアントはキャッチした SoapException のプロパティの値を HTML テーブルに読み込みます。

<%@ Import Namespace="System.Web.Services.Protocols" %>
<%@ Import Namespace="System.Xml" %>
<%@ Page Language="vb" %>
<html>
 <head>
 <script runat=server language=vb>
    Sub Page_Load(o As Object, e As EventArgs)
       ' Create a new instance of the XML Web service class.
       Dim ThrowsSoapException As ThrowSoapException = New _
                 ThrowSoapException()
       Try
         ThrowsSoapException.myThrow()
       Catch myerr As SoapException
            ' Populate the table with the exception details.
            ErrorTable.Rows.Add(BuildNewRow("Fault Code Namespace", _
                                myerr.Code.Namespace))
            ErrorTable.Rows.Add(BuildNewRow("Fault Code Name", _
                                myerr.Code.Name))
            ErrorTable.Rows.Add(BuildNewRow( _
              "SOAP Actor that threw Exception", myerr.Actor))
            ErrorTable.Rows.Add(BuildNewRow("Error Message", _
                                 myerr.Message))
            ErrorTable.Rows.Add(BuildNewRow("Detail", _
                HttpUtility.HtmlEncode(myerr.Detail.OuterXml) )) 
            Return
        End Try
    End Sub 'Page_Load

    Function BuildNewRow(Cell1Text As String, Cell2Text As String) _
             As HtmlTableRow
        Dim row As New HtmlTableRow()
        Dim cell1 As New HtmlTableCell()
        Dim cell2 As New HtmlTableCell()

        'Set the contents of the two cells.
        cell1.Controls.Add(New LiteralControl(Cell1Text))
        'Add the cells to the row.
        row.Cells.Add(cell1)

        cell2.Controls.Add(New LiteralControl(Cell2Text))

        'Add the cells to the row.
        row.Cells.Add(cell2)
        Return row
    End Function 'BuildNewRow 
 </script>
 <head>
 <body>
     <table id="ErrorTable" CellPadding=5 CellSpacing=0 Border="1" BorderColor="black" runat="server" />
 </body>
[C#]
<%@ Import Namespace="System.Web.Services.Protocols" %>
<%@ Import Namespace="System.Xml" %>
<%@ Page Language="C#" %>
<html>
 <head>
 <script runat=server language=c#>
 void Page_Load(Object o, EventArgs e){

   // Create a new instance of the XML Web service proxy class.
   ThrowSoapException throwSoapException = new ThrowSoapException();

   // Make a call to the XML Web service method, which throws an
   // exception.
    try
    {
       throwSoapException.myThrow();
    }
    catch (SoapException error)     {
       // Populate the table with the exception details.
       ErrorTable.Rows.Add(BuildNewRow("Fault Code Namespace",
                                        error.Code.Namespace));
       ErrorTable.Rows.Add(BuildNewRow("Fault Code Name",
                                        error.Code.Name)); 
       ErrorTable.Rows.Add(BuildNewRow(
          "SOAP Actor that threw Exception", error.Actor));
       ErrorTable.Rows.Add(BuildNewRow("Error Message",
           error.Message));
       ErrorTable.Rows.Add(BuildNewRow("Detail",
           HttpUtility.HtmlEncode(error.Detail.OuterXml)));

       return;
     }

 }
// This populates a row in an HtmlTable.
 HtmlTableRow BuildNewRow(string Cell1Text, string Cell2Text) {
     HtmlTableRow row = new HtmlTableRow();
     HtmlTableCell cell1 = new HtmlTableCell();
     HtmlTableCell cell2 = new HtmlTableCell();

     //Set the contents of the two cells.
     cell1.Controls.Add(new LiteralControl(Cell1Text));
     //Add a cell to the row.
     row.Cells.Add(cell1);

     cell2.Controls.Add(new LiteralControl(Cell2Text));

     //Add a cell to the row.
     row.Cells.Add(cell2);
     return row;

 }
 </script>
 <head>
 <body>
     <table id="ErrorTable" CellPadding=5 CellSpacing=0 Border="1" BorderColor="black" runat="server" />
 </body>

XML Web サービスメソッドによって処理されない例外

XML Web サービスメソッドがそのメソッド内に発生した例外をキャッチしない場合に、ASP.NET によって例外を処理する方法を次の表で説明します。

処理されない例外が発生した時期	ASP.NET の動作
XML Web サービスメソッドの実行中	例外は ASP.NET によってキャッチされ、クライアントに対してスローされます。.NET Framework を使用して作成した XML Web サービスクライアントは、特定の例外が InnerException プロパティに設定された SoapException を受け取ります。
SOAP ヘッダーの処理中	ASP.NET が SoapHeaderException をスローします。.NET Framework を使用して作成した XML Web サービスクライアントが、SoapHeaderException を受け取ります。

参照

SoapException クラス | SoapHeaderException クラス | 例外の処理とスロー | ASP.NET を使用した XML Web サービスの作成 | XML Web サービスクライアントの作成

次の方法で共有

XML Web サービスでの例外の処理およびスロー

ASP.NET を使用して作成した XML Web サービスからの例外のスロー

XML Web サービスメソッドによって処理されない例外

参照

その他のリソース

次の方法で共有

XML Web サービスでの例外の処理およびスロー

ASP.NET を使用して作成した XML Web サービスからの例外のスロー

XML Web サービス メソッドによって処理されない例外

参照

その他のリソース

XML Web サービスメソッドによって処理されない例外