Microsoft KB Archive/833379

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

Article ID: 833379

Article Last Modified on 4/29/2007

-

APPLIES TO


 * Microsoft Web Services Enhancements for Microsoft .NET 1.1
 * Microsoft Web Services Enhancements for Microsoft .NET 2.0

-





IN THIS TASK

 * SUMMARY
 * Requirements
 * Create a Web service
 * Pass back the fault code information by using SoapExceptions
 * Create a Microsoft Windows application
 * Add the Web service reference to the Windows application
 * Catch the exception that the XML Web service method throws
 * Verify that your application works
 * REFERENCES



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:// /TestWebService, and then click OK.

Note In this step,  is a placeholder for the name of your Web server.
 * 1) 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:   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.  _ 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, _               &quot;mySpecialInfo1&quot;, &quot;http://tempuri.org/&quot;)

' Add details2 as the first child to the XML element that is already created. Dim details2 As System.Xml.XmlNode = _ doc.CreateNode(XmlNodeType.Element, _               &quot;mySpecialInfo2&quot;, &quot;http://tempuri.org/&quot;) Dim attr As XmlAttribute = doc.CreateAttribute(&quot;t&quot;, _               &quot;attrName&quot;, &quot;http://tempuri.org/&quot;) attr.Value = &quot;attrValue&quot; 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(&quot;Error occurred at client&quot;, _               SoapException.ClientFaultCode, _                Context.Request.Url.AbsoluteUri, node) Throw se       End Try Return End Sub

End Class  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
 On the Project menu, click Add Web Reference.

The Add Web Reference dialog box appears. 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:// /TestWebService/Service1.asmx

Note In this step,  is a placeholder for the name of your Web server. Click Add Reference.</li></ol>

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:  Click Form1, click the View menu, and then click View Code.</li>  Replace the code with the following client code: Imports System.Xml Imports System.Web.Services.Protocols

Public Class Form1 Inherits System.Windows.Forms.Form


 * 1) Region &quot; Windows Form Designer generated code &quot;

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 = &quot;TextBox1&quot; Me.TextBox1.ReadOnly = True Me.TextBox1.Size = New System.Drawing.Size(280, 56) Me.TextBox1.TabIndex = 0 Me.TextBox1.Text = &quot;&quot; '       'TextBox2 '       Me.TextBox2.Location = New System.Drawing.Point(0, 162) Me.TextBox2.Multiline = True Me.TextBox2.Name = &quot;TextBox2&quot; Me.TextBox2.ReadOnly = True Me.TextBox2.Size = New System.Drawing.Size(280, 56) Me.TextBox2.TabIndex = 1 Me.TextBox2.Text = &quot;&quot; '       'TextBox3 '       Me.TextBox3.Location = New System.Drawing.Point(0, 268) Me.TextBox3.Multiline = True Me.TextBox3.Name = &quot;TextBox3&quot; Me.TextBox3.ReadOnly = True Me.TextBox3.Size = New System.Drawing.Size(280, 56) Me.TextBox3.TabIndex = 2 Me.TextBox3.Text = &quot;&quot; '       'TextBox4 '       Me.TextBox4.Location = New System.Drawing.Point(0, 374) Me.TextBox4.Multiline = True Me.TextBox4.Name = &quot;TextBox4&quot; Me.TextBox4.ReadOnly = True Me.TextBox4.Size = New System.Drawing.Size(280, 56) Me.TextBox4.TabIndex = 3 Me.TextBox4.Text = &quot;&quot; '       'TextBox5 '       Me.TextBox5.Location = New System.Drawing.Point(0, 480) Me.TextBox5.Multiline = True Me.TextBox5.Name = &quot;TextBox5&quot; Me.TextBox5.ReadOnly = True Me.TextBox5.Size = New System.Drawing.Size(280, 56) Me.TextBox5.TabIndex = 4 Me.TextBox5.Text = &quot;&quot; '       'Label1 '       Me.Label1.Location = New System.Drawing.Point(8, 16) Me.Label1.Name = &quot;Label1&quot; Me.Label1.Size = New System.Drawing.Size(272, 23) Me.Label1.TabIndex = 5 Me.Label1.Text = &quot;Label1&quot; '       'Label2 '       Me.Label2.Location = New System.Drawing.Point(8, 122) Me.Label2.Name = &quot;Label2&quot; Me.Label2.Size = New System.Drawing.Size(272, 23) Me.Label2.TabIndex = 6 Me.Label2.Text = &quot;Label2&quot; '       'Label3 '       Me.Label3.Location = New System.Drawing.Point(8, 228) Me.Label3.Name = &quot;Label3&quot; Me.Label3.Size = New System.Drawing.Size(272, 23) Me.Label3.TabIndex = 7 Me.Label3.Text = &quot;Label3&quot; '       'Label4 '       Me.Label4.Location = New System.Drawing.Point(8, 334) Me.Label4.Name = &quot;Label4&quot; Me.Label4.Size = New System.Drawing.Size(272, 23) Me.Label4.TabIndex = 8 Me.Label4.Text = &quot;Label4&quot; '       'Label5 '       Me.Label5.Location = New System.Drawing.Point(8, 440) Me.Label5.Name = &quot;Label5&quot; Me.Label5.Size = New System.Drawing.Size(272, 23) Me.Label5.TabIndex = 9 Me.Label5.Text = &quot;Label5&quot; '       '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 = &quot;Form1&quot; Me.Text = &quot;Form1&quot; Me.ResumeLayout(False)

End Sub


 * 1) 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 = &quot;Fault Code Namespace : &quot; TextBox1.Text = myerr.Code.Namespace Label2.Text = &quot;Fault Code Name : &quot; TextBox2.Text = myerr.Code.Name Label3.Text = &quot;SOAP Actor that threw Exception : &quot; TextBox3.Text = myerr.Actor Label4.Text = &quot;Error Message : &quot; TextBox4.Text = myerr.Message Label5.Text = &quot;Detail : &quot; TextBox5.Text = myerr.Detail.OuterXml Return End Try End Sub End Class </li></ol>

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:
 * 4) * Fault Code Namespace
 * 5) * Fault Code Name
 * 6) * SOAP actor that threw Exception
 * 7) * Error Message
 * 8) * Detail

back to the top

<div class="references_section">