Higher Level Messaging
The use of SoapSender and SoapReceiver in web services can become tedious due to all the additional functionalities to be implemented. Inspecting the SOAP message to identify the operation that the client invokes and correlating the messages are tasks that must always be carried out manually while developing web services based on SoapReceiver and SoapSender.
WSE 2.0 provides two additional classes (SoapService and SoapClient) to implement the tasks previously described. By means of these two classes it is possible to use all the features of SoapReceiver and SoapSender and to abstract the handling level of the SOAP messages.
To implement your web service simply create a new class inheriting from SoapService and then implement the operations that you want to support. A simple SoapService looks like this:
class MyService:SoapService
{
//implement the logic here...
}
For each SOAP operation within the Web service, add a method to the class and assign the SoapMethodAttribute attribute to the method. The SoapMethodAttribute indicates that a method can be called by clients through the internet. The method must have one parameter of either the SoapEnvelope type or an XML-serializable type and a return value of the SoapEnvelope type or the XML-serializable type. The SoapMethodAttribute allows you to specify the SOAP action for the SOAP operation.
The following code shows our implementation of a StrManager:
public class StrManager: SoapService
{
[SoapMethod("urn:StrManager:Concat")]
public SoapEnvelope StringConcat(SoapEnvelope env)
{
//implement the logic here…
}
[SoapMethod("urn:StrManager:Delete")]
public SoapEnvelope StringDelete(SoapEnvelope env)
{
//implement the logic here…
}
}
The web service can receive SOAP messages as a SoapEnvelope or an XML serializable object. If a SOAP message contains a serializable object it can be serialized inside the Body of a SOAP message.
Next, register the web service in the application that creates the SoapService instance like in the SoapSender and SoapReceiver example. The code to register a SoapService looks like this:
MyService myService = new MyService();
Uri serveruri = new Uri( "soap.tcp://localhost/MyReceiver" );
SoapReceivers.Add(serveruri, myService);
Now the WebService is ready to receive SOAP messages. In the sample code of Higher Level Messaging you can find the complete implementation of a StrManager web service.
In order to develop a client capable of sending messages to a SoapService instance, you should declare a class deriving from the SoapClient class:
class MyClient : SoapClient
{
//implement the logic here...
}
The SoapClient class defines methods to send messages to a web service and to receive response messages from that service. To send messages you can use the following methods:
|
Method |
Description |
|
SendOneWay |
Sends a request message to a web service and do not wait for a response message. |
|
SendRequestResponse |
Sends a request message to a web service and block the current thread until a response message is received. You can implement an asynchronous version of this method by using BeginSendRequestResponse. |
|
Send |
Provides the same functionality as SoapSender. |
Finally, develop methods for sending messages to a SoapService instance. To perform this task you should define methods having the SoapMethodAttribute assigned to them. The following code shows and implementation of a StrManagerClient:
public class StrManagerClient: SoapClient
{
[SoapMethod("urn:StrManager:Concat")]
public SoapEnvelope StringConcat(SoapEnvelope env)
{
return SendRequestResponse("StringConcat", env);
}
[SoapMethod("urn:StrManager:Delete")]
public SoapEnvelope StringDelete(SoapEnvelope env)
{
return SendRequestResponse("StringDelete", env);
}
}
The SoapService and SoapClient classes simplify the development of XML messaging applications in their different scenarios. We have provided another example with the same functionality as the previous one but using SoapService and SoapClient.
Using HTTP protocol
Up to this point, all the examples present the web service and the client using the TCP protocol. WSE 2.0 includes other protocols as in-process and HTTP. WSE 2.0 allows the use of the same web service with different communication protocols. The separation between the logic and the communication interface increases the chance to use the web services in the most heterogeneous environments.
In the code samples of this article you can find a service and two applications to host the web service, one using the TCP protocol and the other the HTTP protocol. In the client application (Figure 1.) you may choose the protocol to communicate with the web service.
Figure 1: The client user interface.
Conclusion
WSE 2.0 provides various classes to develop SOAP via HTTP or TCP applications. Both SoapSender and SoapReceiver implement the basic functionality to send and receive SOAP messages. WSE 2.0 also provides a high level API to develop Web Services through SoapService and SoapClient. The use of these APIs enlarges the horizon for the development of Web Services with high communication requirements.
