Handling Errors That Occur While Processing a SOAP Header
This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.
When a Web service detects an error specific to the processing of a SOAP header, a SoapHeaderException should be thrown. Using this exception class allows Web services to correctly format the response. An example invocation follows:
throw new SoapHeaderException("invalid user",SoapException.ClientFaultCode);
Throw New SoapHeaderException("invalid user", SoapException.ClientFaultCode)
If the client is created using the .NET Framework, it will receive the SoapHeaderException with its contents, including the InnerException property, placed in the Message property. The InnerException property of the SoapHeaderException caught by the client will be null. This is a programming model supported by the .NET Framework, as the exception is sent over the network in a SOAP <Fault> XML element, as prescribed by the SOAP specification. For more details on exceptions, see Handling and Throwing Exceptions in XML Web Services.
Note: The .NET Framework version 1.0 includes the SoapHeaderAttribute.Required property which enables a Web service to require that a client send a specific SOAP header when the property is set to true. ASP.NET indicates that the SOAP header is required in a generated WSDL document by setting the wsdl:required attribute to "true" on the soap:header element. .NET Framework clients of the Web service built from the WSDL document receive a SoapHeaderException if they do not send the required SOAP header and other clients receive a SOAP Fault. To interoperate with other SOAP implementations, this functionality is removed in later versions.
The Required property is obsolete in version 1.1, and the wsdl:required attribute of a soap:header element in a WSDL document is ignored by the Web Services Description Language tool (Wsdl.exe). Because a SOAP header can no longer be required, a Web service should verify that the field or property representing the SOAP header is not null before accessing it.
See Also
Reference
SoapHeaderException
SoapHeader
SoapHeaderAttribute
SoapUnknownHeader
Concepts
Handling and Throwing Exceptions in XML Web Services
Building XML Web Service Clients