Gestion et levée d'exceptions dans les services Web XML

Les exceptions levées par une méthode de service Web XML créée à l'aide d'ASP.NET sont renvoyées au client sous la forme d'une erreur SOAP. Une erreur SOAP est un élément XML <Fault> dans un message SOAP qui spécifie qu'une erreur s'est produite. Lors du passage d'une erreur SOAP, ASP.NET suit la méthode prescrite par la spécification SOAP pour répercuter les erreurs vers un client. L'élément XML <Fault> SOAP contient des détails tels que la chaîne d'exception et la source de l'exception. Pour plus d'informations sur les erreurs SOAP, consultez le site Web du W3C (http://www.w3.org/TR/SOAP).

Heureusement, les clients et les services Web XML créés à l'aide d'ASP.NET ne remplissent ou n'analysent pas directement l'élément XML <Fault> mais utilisent plutôt le modèle de design commun pour lever et intercepter les exceptions dans le .NET Framework. Un service Web XML peut lever une exception spécifique au problème telle que ArgumentOutOfRangeException ou SoapException. De toute façon, ASP.NET sérialise l'exception dans un message SOAP valide en plaçant l'exception dans un élément d'erreur SOAP. Lorsque le message SOAP est désérialisé sur un client ASP.NET, l'erreur SOAP est convertie en une exception SoapException, les détails de l'exception étant placés dans la propriété Message. Un client peut alors définir un bloc Try/Catch pour intercepter SoapException.

Une application Web peut être constituée de plusieurs services Web XML, cependant l'événement Application_Error dans le fichier Global.asax ne peut pas être utilisé pour la gestion globale des exceptions. Le gestionnaire HTTP, HttpHandler, des services Web XML consomme toute exception qui survient lors de l'exécution d'un service Web XML et la transforme en une erreur SOAP avant que l'événement Application_Error ne soit appelé. Créez une extension SOAP pour traiter les exceptions de services Web XML dans un gestionnaire d'exceptions global. Une extension SOAP peut contrôler la présence d'une exception dans la méthode ProcessMessage. Dans la méthode ProcessMessage, vérifiez la propriété Exception du SoapMessage qui est passé lorsque la propriété Stage est définie à AfterSerialize. Pour plus d'informations sur les extensions SOAP, consultez Modification du message SOAP à l'aide des extensions SOAP.

Levée d'exceptions à partir d'un service Web XML créé à l'aide d'ASP.NET

La répercussion des erreurs vers un client est effectuée par la levée d'exceptions. Une méthode de service Web XML peut y parvenir de quatre façons :

1. Lever une exception SoapException.
2. Lever une exception SoapHeaderException.
3. Lever une exception spécifique au problème.
4. Autoriser ASP.NET à lever l'exception.

Le tableau suivant décrit les exceptions qu'un service Web XML peut lever de manière explicite et la façon dont un client ASP.NET reçoit chaque exception.

Pour lever une exception à partir d'un service Web XML

• Levez l'exception spécifique au problème, telle que SoapException, ou SoapHeaderException, comme cela est décrit dans le tableau précédent.

  L'exemple de code suivant lève SoapException et fournit des détails supplémentaires concernant l'exception en définissant la propriété 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;
      }
  }
  

Pour intercepter une exception levée par une méthode de service Web XML

• Dans un bloc Try/Catch, interceptez SoapException (les exceptions levées par une méthode de service Web XML sont levées comme SoapException).

  L'exemple de code suivant d'un client appelant une méthode de service Web XML intercepte l'exception levée par la méthode. Le client remplit alors un tableau HTML avec les propriétés du SoapException intercepté.

  <%@ 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>
  

Exceptions non gérées par une méthode de service Web XML

Si une méthode de service Web XML n'intercepte pas d'exception se produisant dans la méthode, le tableau suivant décrit comment l'exception est gérée par ASP.NET.

Voir aussi

SoapException, classe | SoapHeaderException, classe | Gestion et levée des exceptions | Création de services Web XML à l'aide d'ASP.NET | Création de clients de service Web XML