How to customize SOAP fault code information when a SoapException occurs in Microsoft Web Services when a client provides bad data (833379)


The information in this article applies to:

  • Microsoft Web Services (included with the .NET Framework 1.1)
  • Microsoft Web Services (included with the .NET Framework) 1.0

IN THIS TASK

SUMMARY

This article describes how to customize SOAP fault code information when a SoapException occurs in Microsoft Web Services when a client provides bad data. If your application exposes Web Services through a WebService application layer, the server throws SoapExceptions to the client. When the client provides bad data, the fault code is set to the client fault code. This fault code indicates a client error. By default, the fault code is set to indicate a server error.

This article uses a DivideByZero sample to provide the custom stack trace information.

back to the top

Requirements

This article assumes that you are familiar with the following topics:
  • Programming with Web Services (included with the Microsoft .NET Framework)
  • SoapExceptions
back to the top

Create a Web service

  1. Start Microsoft Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.
  3. Under Project Types, click Visual Basic Projects.
  4. Under Templates, click ASP.NET Web Service.
  5. In the Location text box, type http://localhost/TestWebService, and then click OK.

    Note In this step, localhost is a placeholder for the name of your Web server.
  6. In Solution Explorer, right-click Service1.asmx, and then click View Code.
back to the top

Pass back the fault code information by using SoapExceptions


XML Web service methods can generate a SoapException by throwing an exception. An exception that ASP.NET creates and that an XML Web service method throws is sent back to the client as a SOAP fault. ASP.NET serializes the exception to a valid SOAP message by placing the exception in a SOAP fault element. When an ASP.NET client deserializes the SOAP message, the SOAP fault is converted to a SoapException, and the exception details are put in the Message property. You can set up a client to use the Try/Catch block to catch a SoapException, as follows:
  1. In Solution Explorer, replace the code in the Service1.asmx code view with the following code. The following code throws a SoapException to return client fault code that indicates a client error: 
    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 SOAP client fault code. 
    <WebMethod()> _
    Public Sub DivideByZero(ByVal num As Long)

        Try
            'Division by zero logic.
            Dim j As Integer
            j = 5 \ num
        Catch ex1 As Exception
            ' 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 details as the first child to the XML element that is already created.
            Dim details As System.Xml.XmlNode = _
                doc.CreateNode(XmlNodeType.Element, _
                "mySpecialInfo1", "http://tempuri.org/")

            ' Add details2 as the first child to the XML element that is already created.
            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("Error occurred at client", _
                SoapException.ClientFaultCode, _
                Context.Request.Url.AbsoluteUri, node)
            Throw se
        End Try
        Return
    End Sub



End Class
  2. On the Build menu, click Build TestWebService.
back to the top

Create a Microsoft Windows application

  1. Start Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.
  3. Under Project Type, click Visual Basic Project.
  4. Under Template, click Windows Application.
  5. In the Name text box, type ServiceConsumer, and then click OK.

    By default, the Form1 form is created.
back to the top

Add the Web service reference to the Windows application

  1. On the Project menu, click Add Web Reference.

    The Add Web Reference dialog box appears.
  2. On the Address bar, type the TestWebService URL, and then click GO.

    For example, if TestWebService is located in the root directory of a Web server, type the following address:

    http://localhost/TestWebService/Service1.asmx

    Note In this step, localhost is a placeholder for the name of your Web server.
  3. Click Add Reference.
back to the top

Catch the exception that the XML Web service method throws

When the client uses SOAP to access the method, the exception is caught on the server and is wrapped inside a new SoapException. The thrown SoapException has the following properties:
  • Message. Obtain a message that describes the current exception.
  • Code. Obtain the SOAP fault code type.
  • Actor. Obtain the code that caused the exception.
  • Details. Supplies application-specific error details that are related to the body element of the SOAP request.
The client populates the properties of the caught SoapException. The following code describes the client that is calling an XML Web service method and that catches the exception that is thrown by the XML Web service method. To use this code appropriately, follow these steps:
  1. Click Form1, click the View menu, and then click View Code.
  2. Replace the code with the following client code: 
    Imports System.Xml
Imports System.Web.Services.Protocols

Public Class Form1
    Inherits System.Windows.Forms.Form

#Region " Windows Form Designer generated code "

    Public Sub New()
        MyBase.New()

        'The Windows Form Designer requires this call.
        InitializeComponent()

        'Add any initialization after the InitializeComponent() call.

    End Sub

    'Form overrides dispose to clean up the component list.
    Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
        If disposing Then
            If Not (components Is Nothing) Then
                components.Dispose()
            End If
        End If
        MyBase.Dispose(disposing)
    End Sub

    'The Windows Form Designer requires this call. 
    Private components As System.ComponentModel.IContainer

    'NOTE: The Windows Form Designer requires the following procedure. 
    'You can use the Windows Form Designer to modify this procedure.  
    'Do not modify this procedure by using the Code editor.
    Friend WithEvents TextBox1 As System.Windows.Forms.TextBox
    Friend WithEvents TextBox2 As System.Windows.Forms.TextBox
    Friend WithEvents TextBox3 As System.Windows.Forms.TextBox
    Friend WithEvents TextBox4 As System.Windows.Forms.TextBox
    Friend WithEvents TextBox5 As System.Windows.Forms.TextBox
    Friend WithEvents Label1 As System.Windows.Forms.Label
    Friend WithEvents Label2 As System.Windows.Forms.Label
    Friend WithEvents Label3 As System.Windows.Forms.Label
    Friend WithEvents Label4 As System.Windows.Forms.Label
    Friend WithEvents Label5 As System.Windows.Forms.Label
    <System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent()
        Me.TextBox1 = New System.Windows.Forms.TextBox
        Me.TextBox2 = New System.Windows.Forms.TextBox
        Me.TextBox3 = New System.Windows.Forms.TextBox
        Me.TextBox4 = New System.Windows.Forms.TextBox
        Me.TextBox5 = New System.Windows.Forms.TextBox
        Me.Label1 = New System.Windows.Forms.Label
        Me.Label2 = New System.Windows.Forms.Label
        Me.Label3 = New System.Windows.Forms.Label
        Me.Label4 = New System.Windows.Forms.Label
        Me.Label5 = New System.Windows.Forms.Label
        Me.SuspendLayout()
        '
        'TextBox1
        '
        Me.TextBox1.Location = New System.Drawing.Point(0, 56)
        Me.TextBox1.Multiline = True
        Me.TextBox1.Name = "TextBox1"
        Me.TextBox1.ReadOnly = True
        Me.TextBox1.Size = New System.Drawing.Size(280, 56)
        Me.TextBox1.TabIndex = 0
        Me.TextBox1.Text = ""
        '
        'TextBox2
        '
        Me.TextBox2.Location = New System.Drawing.Point(0, 162)
        Me.TextBox2.Multiline = True
        Me.TextBox2.Name = "TextBox2"
        Me.TextBox2.ReadOnly = True
        Me.TextBox2.Size = New System.Drawing.Size(280, 56)
        Me.TextBox2.TabIndex = 1
        Me.TextBox2.Text = ""
        '
        'TextBox3
        '
        Me.TextBox3.Location = New System.Drawing.Point(0, 268)
        Me.TextBox3.Multiline = True
        Me.TextBox3.Name = "TextBox3"
        Me.TextBox3.ReadOnly = True
        Me.TextBox3.Size = New System.Drawing.Size(280, 56)
        Me.TextBox3.TabIndex = 2
        Me.TextBox3.Text = ""
        '
        'TextBox4
        '
        Me.TextBox4.Location = New System.Drawing.Point(0, 374)
        Me.TextBox4.Multiline = True
        Me.TextBox4.Name = "TextBox4"
        Me.TextBox4.ReadOnly = True
        Me.TextBox4.Size = New System.Drawing.Size(280, 56)
        Me.TextBox4.TabIndex = 3
        Me.TextBox4.Text = ""
        '
        'TextBox5
        '
        Me.TextBox5.Location = New System.Drawing.Point(0, 480)
        Me.TextBox5.Multiline = True
        Me.TextBox5.Name = "TextBox5"
        Me.TextBox5.ReadOnly = True
        Me.TextBox5.Size = New System.Drawing.Size(280, 56)
        Me.TextBox5.TabIndex = 4
        Me.TextBox5.Text = ""
        '
        'Label1
        '
        Me.Label1.Location = New System.Drawing.Point(8, 16)
        Me.Label1.Name = "Label1"
        Me.Label1.Size = New System.Drawing.Size(272, 23)
        Me.Label1.TabIndex = 5
        Me.Label1.Text = "Label1"
        '
        'Label2
        '
        Me.Label2.Location = New System.Drawing.Point(8, 122)
        Me.Label2.Name = "Label2"
        Me.Label2.Size = New System.Drawing.Size(272, 23)
        Me.Label2.TabIndex = 6
        Me.Label2.Text = "Label2"
        '
        'Label3
        '
        Me.Label3.Location = New System.Drawing.Point(8, 228)
        Me.Label3.Name = "Label3"
        Me.Label3.Size = New System.Drawing.Size(272, 23)
        Me.Label3.TabIndex = 7
        Me.Label3.Text = "Label3"
        '
        'Label4
        '
        Me.Label4.Location = New System.Drawing.Point(8, 334)
        Me.Label4.Name = "Label4"
        Me.Label4.Size = New System.Drawing.Size(272, 23)
        Me.Label4.TabIndex = 8
        Me.Label4.Text = "Label4"
        '
        'Label5
        '
        Me.Label5.Location = New System.Drawing.Point(8, 440)
        Me.Label5.Name = "Label5"
        Me.Label5.Size = New System.Drawing.Size(272, 23)
        Me.Label5.TabIndex = 9
        Me.Label5.Text = "Label5"
        '
        'Form1
        '
        Me.AutoScaleBaseSize = New System.Drawing.Size(5, 13)
        Me.ClientSize = New System.Drawing.Size(288, 549)
        Me.Controls.Add(Me.Label5)
        Me.Controls.Add(Me.Label4)
        Me.Controls.Add(Me.Label3)
        Me.Controls.Add(Me.Label2)
        Me.Controls.Add(Me.Label1)
        Me.Controls.Add(Me.TextBox5)
        Me.Controls.Add(Me.TextBox4)
        Me.Controls.Add(Me.TextBox3)
        Me.Controls.Add(Me.TextBox2)
        Me.Controls.Add(Me.TextBox1)
        Me.Name = "Form1"
        Me.Text = "Form1"
        Me.ResumeLayout(False)

    End Sub

#End Region


    Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        ' Create a new instance of the XML Web service class.
         'Replace 'localhost' with the actual name of the your WebService that is added  
        Dim ThrowsSoapException As localhost.ThrowSoapException = New localhost.ThrowSoapException
        
        Try
            'Call the Web Service method.
            ThrowsSoapException.DivideByZero(0)
        Catch myerr As SoapException
            ' Populate with the exception details.
            Label1.Text = "Fault Code Namespace : "
            TextBox1.Text = myerr.Code.Namespace
            Label2.Text = "Fault Code Name : "
            TextBox2.Text = myerr.Code.Name
            Label3.Text = "SOAP Actor that threw Exception : "
            TextBox3.Text = myerr.Actor
            Label4.Text = "Error Message : "
            TextBox4.Text = myerr.Message
            Label5.Text = "Detail : "
            TextBox5.Text = myerr.Detail.OuterXml
            Return
        End Try
    End Sub
End Class
back to the top

Verify that you application works

  1. On the Build menu, click Build Solution.
  2. On the Debug menu of the client, click Start to run the application.
  3. After you run the client application, the following terms appear on the form:
    • Fault Code Namespace
    • Fault Code Name
    • SOAP actor that threw Exception
    • Error Message
    • Detail
back to the top

REFERENCES

For more information, visit the following Microsoft Web sites:

SoapException class
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemWebServicesProtocolsSoapExceptionClassTopic.asp

SoapException.ClientFaultCode field
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwebservicesprotocolssoapexceptionclassclientfaultcodetopic.asp

Using SOAP faults
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnservice/html/service09172002.asp

Handling and throwing exceptions in XML Web Services
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconhandlingraisingexceptionsinxmlwebservices.asp

Throwing SoapExceptions
http://www.microsoft.com/belux/nl/msdn/community/columns/jtielens/soapexceptions.mspx



back to the top
Modification Type:MajorLast Reviewed:1/13/2004
Keywords:kbenvelope kbExceptHandling kbXML kbWebServices kbHOWTOmaster KB833379 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.