Exploring the Header in the WSE 2.0 SoapEnvelope Class
This article, the second of two parts, continues our exploration of the SoapEnvelope class in WSE2.0 by examining some of its properties and methods. In particular, we focus on manipulating the SoapHeader.
SOAP is well known as an extremely lightweight protocol requiring fewer resources from the sender or recipient of a communication. Since it is XML-based, any system capable of parsing XML should be capable of communicating using this protocol. The basic unit of communication in SOAP is a SOAP Message. WSE2.0 provides a large number of classes in the Microsoft.Web.Services2 name space that make the communication possible with flexible lightweight web services. A partial list of related classes in this name space include the following:
The function of the envisaged use of a SOAP Header is to provide support for extending the message content. The SOAP header might be used for message routing, transaction management, user authentication, etc.
The XML grammar rules applies to the SOAP Header as to its name (Header) and its position in the SOAP Envelope (the first immediate child of Soap Envelope); any other entries in the Header are its children and they are all namespace qualified. Other entries in the Header may be used by the intermediaries in the message route for processing of the message by that node.
As discussed earlier, in the first part of this two part series, while the Body element is mandatory in the SOAP Message, the Header is optional. There is a difference in how the SOAP specification treats the Header element in a SOAP message, and how Microsoft defines the Soap Header. Visual Studio IDE 2003 can manipulate headers.
The SOAP specification does not strictly define the headers. Therefore, a class containing the data in the header has to be created for adding header information for web services created by the IDE. This class is derived from the SoapHeader class. This tutorial shows how this is done.
Manipulating SoapHeader in Visual Studio .NET 2003
Create a new project of type web service, called Hdrs in this tutorial. Follow the earlier steps discussed in part one of this series to add a reference to WSE2.0 and a new web service, named SopHdr.asmx in this tutorial. Since we would like to look at the SoapEnvelope's Header property we will create a Public Class jhdr whose code is shown here [HdrInfo.vb] after the picture.
Imports System Imports System.Web.Services.Protocols Namespace SoapHeader Public Class jhdr Inherits System.Web.Services.Protocols.SoapHeader Public UserName As String End Class End Namespace
The code for the SopHdr.asmx is shown here:
Imports System.Web.Services.Protocols
Imports Microsoft.Web.Services2
Namespace SoapHeader
<System.Web.Services.WebService(Namespace:="http://tempuri.org/Hdrs/
SopHdr")> _
Public Class SopHdr
Inherits System.Web.Services.Protocols.SoapHeader
Public myHeader As New jhdr
#Region " Web Services Designer Generated Code "
<WebMethod(), SoapHeader("myHeader")> _
Public Function TestHdr() As String
Dim sen1 As New Microsoft.Web.Services2.SoapEnvelope
myHeader.UserName = "mysorian"
sen1.SetBodyObject("OK")
sen1.InnerXml = "<soap:Envelope
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
<soap:Header/>
<soap:Body>
</soap:Body>
</soap:Envelope>"
sen1.Header.InnerXml = myHeader.UserName
Try
'Return sen1.Header.IsEmpty
Return sen1.Header.OuterXml
Catch ex As SoapHeaderException
Return ex.Message
End Try
End Function
End Class
End Namespace
The following items are to be noted:
WSE2.0 is properly referenced by the imports statement. The statement regarding the inheritance from the System.Web.Services.protocols is included. An instance of the class jhdr is included. Also the SoapHeader reference to the jhdr class is referenced in the Web Method.
With the above in place, a Public function is scripted to get the SoapEnvelope's Header information using the above code. First of all a reference to the SoapEnvelope from WSE2.0 is instantiated with sen1. The SoapEnvelope should have a Body element; hence, a dummy body ["OK"] is set using the SetBodyObject method. Also the root element must be present; this is supplied by the SoapEnvelope's InnerXML setting.
Look at the complete string of the SoapEnvelope. You will observe that an empty SoapHeader element is added. With this preliminary preparation, the method can take all this information and return the SoapEnvelope's header from the web service. The commented return should produce a false since the header is not empty. Errors in the SoapHeader can be thrown as SoapErrorException. For example, if you were to drop the <Soap:Header/> element in the SoapEnvelope string an exception would be thrown.
As it is, the code produces the following output when run.
Clicking on TestHdr link will bring up the next web page:
Review the details of SOAP above. The Soap:Header element has the class information. TestHdrResponse results in a string (formatting the OuterXML of the SoapEnvelope's header). By clicking the Invoke button, the method call is made and the result is seen in the browser as shown here:
Summary:
The article has explored the properties and methods of the SoapEnvelope Class in WSE2.0's Microsoft.Web.Services2 namespace. The codes can be used for reference, and they can be copied and pasted while testing. Since SoapHeader is treated differently in the Visual Studio IDE, a class was designed to incorporate this information.
The SoapHeader code was tested using the SopHdr.asmx file, but the information in the header can be passed to the web service via client applications. In fact, web service authentication can be carried out incorporating the credentials in the SoapHeader [Reference: Professional ASP.NET Web Services, Russ Bassiura et al, Wrox Press, ISBN: 1-861005-45-8, 2001].
Windows Scripting 
Exploring the SoapEnvelope Class in WSE2.0
