This article, the first of two parts, will explore the SoapEnvelope class in WSE2.0 by examining some of its properties and methods. The namespace to which this class belongs has a large number of classes and each of them have a large number of properties and methods; that includes the inherited ones. We will only highlight a few of them here.
WSE2.0 provides the class libraries that add the power to the .NET Class libraries in extending the web services capabilities to the existing web services architecture. Soap messaging in WSE2.0 is a key to many enhanced capabilities that provides support for communication using protocols other than HTTP. This amounts to not needing even a web server when the TCP protocol is used. The request/response model of HTTP is really not needed when sending messages, especially when no messages are expected to be returned. However, messaging by HTTP is also supported.
The 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 by 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 makes the communication possible with flexible lightweight web services. A partial list of related classes in this name space is the following:
A SOAP message consists of a Header, a Body and any other independent elements housed in what is called a SOAP Envelope. A SOAP message is an XML document that imposes the existence of a single root element. The Soap envelope is the top element, or the root element of the Soap message. Following the Soap envelope root element is the Soap Header which is optional; the Soap Body, which is required, follows next. This is the minimum requirement for the SOAP Message. An XML document such as the one shown in the following paragraph would represent an empty Soap Message.
This article looks at the properties and methods exposed by the SoapEnvelope class, with special reference to WSE2.0, that can be used in building web services. The public events are all inherited from XMLDocument and will not be discussed here. Some of the properties and methods pertinent to WSE2.0 will be explored by building web services and testing them.
There are more than 50 methods, a majority of them from the inheritance. In this tutorial, only some of the methods from WSE2.0 are discussed.
The reader should review the XMLNode and XMLDocument in the Class Viewer which can be found in C:Program FilesMicrosoft Visual Studio .NET2003SDKv1.1BinWinCV.exe, or a similar location.
SoapEnvelope Properties
Similarly, in the case of properties, from a total of 34 public properties from inheritance and WSE2.0, only a few from WSE2.0 are discussed. However, some of the others, not discussed, will appear in the discussion of other classes.
It is assumed that Visual Studio 2003 is installed. It is also assumed that WSE2.0 has been installed. If not, it can be installed from the Microsoft web site. Search for Microsoft WSE 2.0 SP2.msi (8.8Mb). Once installed in the Visual Studio IDE you should be able to see the related dll in the .NET reference.
Web Service Project
Create a new web service project (WSE2_1), and remove the default Service1.asmx file. Insert a web service file. In this tutorial it is named Props.asmx.
Since we are going to look at properties and methods of the WSE2.0, you need to add a reference to WSE2.0. Right click the solution[WSE2_1] and click on Add Reference.... This will bring up the following screen as shown. This will add references to the Microsoft.Web.Services2.dll and all the properties and methods will be available at design time. These are also available via intellisense.
In the Visual Studio IDE, click on the menu item View and from the drop down click on Object Browser. This will bring out all the objects. The next figure shows the namespaces related to WSE2.0. We will be looking at one of the classes highlighted.
Visual Studio 2003 provides a default HelloWorld() WebMethod which has been removed. First of all the Microsoft.Web.Services2 should be imported to the web service as shown in the imports.
The following code creates a web service which looks at the inner text property of a SoapEnvelope:
Imports System.Web.Services
Imports Microsoft.Web.Services2
<System.Web.Services.WebService(Namespace :=
"http://tempuri.org/WSE2_1/Props")> _
Public Class Props
Inherits System.Web.Services.WebService #Region
" Web Services Designer Generated Code "
[author's note: this code has been removed for clarity]
#End Region <WebMethod()> _
Public Function InTxt() As String
Dim sen1 As New Microsoft.Web.Services2.SoapEnvelope
Try
sen1.LoadXml("<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:Body>
<nom>United States</nom>
</soap:Body></soap:Envelope>")
Return sen1.InnerText
Catch ex As Exception
Return ex.Message
End Try
End Function End Class
We shall only concentrate on some of the important items highlighted in blue in the code without concerning ourselves too much with the designer created code. The second line below shows that the proper reference to WSE2.0 has been made.
Imports System.Web.Services
Imports Microsoft.Web.Services2
Most of the properties and methods will be explored in this WebMethod template called InTxt(). This will actually look at the inner text property of the SoapEnvelope. The SoapEnvelope constructor admits of the NEW method and therefore a SoapEnvelope, sen1, is declared using the New keyword.
Once declared it is assigned a value which is appropriate for a SoapEnvelope document as shown. In the above code, the LoadXML() method is used to load the SoapEnvelope. The method's return is set to the inner text property of the SoapEnvelope that was loaded. Build the solution and right click the Props.asmx to click on View in Browser. This brings up the following browser screen:
The InTxt is the method of the web service can be tested by clicking the link which brings up the following (partially shown here):
The method can be tested by clicking the Invoke button in the browser. The result is shown again in the browser as shown:
A similar web service along the same lines as the above can be used to investigate and explore the Body property as well as the SetBodyObject() methods. Here the Body is a string, "Thing of beauty is a joy for ever." The SetBodyObject() method will set up the above "body" as the body of the envelope.
Public Function SetBdyObj() As String
Dim sen1 As New Microsoft.Web.Services2.SoapEnvelope
Dim strbdy As String
strbdy = "Thing of beauty is a joy for ever"
sen1.SetBodyObject(strbdy)
Try
Return sen1.Body.InnerXml
Catch ex As Exception
Return ex.Message
End Try
End Function
The web client would see the code shown in the next paragraph when he accesses this service and calls the SetBdyObj() function.
<string> <string xmlns="http://tempuri.org/">Thing of beauty is a joy for ever</string> </string>
Summary
This article explored the SoapEnvelope class in WSE2.0 by interrogating some of its properties and methods. The namespace to which this class belongs has a large number of classes and each of them have a large number of properties and methods; that includes the inherited ones. In addition to Microsoft's WSE2.0 document, the following resources are also recommended:
Programming Microsoft .NET XML Web Services by D.Foggon et al, Published by Microsoft Press, ISBN 0-7356-1912-3, 2003
Understanding Web Services Specifications and the WSE by J.H.Gailey, Published by Microsoft Press, ISBN 0-7356-1913-1, 2004
Windows Scripting 
/ 3 
Exploring the Header in the WSE 2.0 SoapEnvelope Class
