Using Custom SOAP Headers

SOAP is the wire format used to communicate with web services. In SOA implementations, SOAP is used in Document mode. A less-often-used standard is SOAP-RPC, which is a special form of SOAP used to serialize Remote Procedure Calls. When SOAP documents are used as input parameters to methods, the wire format becomes more flexible and prevents additional artificial dependencies that are typically created when using SOAP-RPC.

Another feature that SOAP allows for is the use of custom headers. Attached to the top of any SOAP envelope, there can be a header that contains additional information. The great thing about using .NET with SOAP headers is that the information contained in a SOAP header can be carried from one method call to the next without explicitly writing additional code. This allows for information that needs to be transmitted to multiple methods to be sent without impacting the parameter list of each method.

The ASP.NET Web Services infrastructure insulates you from the complexities of constructing and decoding the XML that forms SOAP headers and allows you to concern yourself with the data contained within them.

The first code sample illustrates how to add a SOAP header to a web service method. This is a two-step process:


Create a class that derives from SoapHeader and declare an instance of that class as a public member within the web service.


Use the SoapHeaderAttribute to indicate the name of the SOAP header that will be used by a given method, as well as the header direction and whether that header is required.

To see this in action, take a look at the code in Listing 33.2, which contains the source code for a web service called SoapHeaderTest.asmx.

Listing 33.2. Using SOAP Headers in a Web Service

using System; using System.Web; using System.Collections; using System.Web.Services; using System.Web.Services.Protocols; /// <summary> /// Use this class to represent a soap header /// It will be serialized and deserialized for /// communication within a SOAP envelope /// </summary> public class TestSoapHeader : SoapHeader { public string FirstValue; public string SecondValue; } /// <summary> /// Summary description for SoapHeaderTest /// </summary> [WebService(Namespace = "")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] public class SoapHeaderTest : System.Web.Services.WebService { public TestSoapHeader TestHeader; public SoapHeaderTest() {     //Uncomment the following line if using designed components     //InitializeComponent(); } [WebMethod] public string HelloWorld() {     return "Hello World"; } [WebMethod] [SoapHeader("TestHeader", Direction=SoapHeaderDirection.InOut)] public string HeaderEnabledMethod(string message) {     if (TestHeader != null)     {         string output = string.Format(             "The Message you sent was {0}. The soap header contained {1} and {2}.",             message, TestHeader.FirstValue, TestHeader.SecondValue);         TestHeader.FirstValue += " (modified)";         TestHeader.SecondValue += " (modified)";         return output;     }     else         return string.Format(             "The message you sent was {0}.", message); } } 

One thing worth pointing out is that you can have bidirectional SOAP headers. This means that when the web service method is done executing, the current values of the SOAP header are then serialized back into the output of the web service. The client proxy takes care of the underlying work involved in reloading the headers from the SOAP envelope, making it a very seamless and easy-to-use system.

You add references to header-enabled web services in the same manner as standard web services. The only difference is that the SOAP header appears as a member of the service proxy, allowing the client code to manipulate the header before making a method call, as shown in Listing 33.3.

Listing 33.3. Programming with SOAP Headers: Client Code

private void button2_Click(object sender, EventArgs e) {     localhost.SoapHeaderTest svc = new DiscoClient.localhost.SoapHeaderTest();     svc.TestSoapHeaderValue = new DiscoClient.localhost.TestSoapHeader();     svc.TestSoapHeaderValue.FirstValue = "one";     svc.TestSoapHeaderValue.SecondValue = "two";     string output = svc.HeaderEnabledMethod("Hello World");     output = string.Format("Message from service : {0}\nHeader : {1} / {2}\n",         output, svc.TestSoapHeaderValue.FirstValue,         svc.TestSoapHeaderValue.SecondValue);     MessageBox.Show(output); } 

When you run a Windows Forms test harness application and click the button to launch the preceding code, the MessageBox output is shown in Figure 33.3.

Figure 33.3. Output from SOAP header example.

SOAP headers allow the web service and client to exchange information in a very loose manner without changing the list of parameters on the service methods. As you know, any change to a web service method signature that a client isn't aware of will cause the client to break.

Microsoft Visual C# 2005 Unleashed
Microsoft Visual C# 2005 Unleashed
ISBN: 0672327767
EAN: 2147483647
Year: 2004
Pages: 298 © 2008-2017.
If you may any questions please contact us: