ASP.NET Web Services Techniques

• Working with SOAP Headers
• Asynchronous Web Services Clients
• SOAP Faults
• Passing Binary Data
• Session and Application State Management
• Caching
• Hooking into HTTP Pipeline
• WSDL.exe and web.config Tips

• Microsoft Windows 2000, Windows XP, or Windows Server 2003,
• Microsoft .NET Framework 1.0 SP2 or higher,
• IIS 5.0 or higher; or ASP.NET Cassini Sample Web Server,
• SQL Server 7/2000, or MSDE 2000, and
• Microsoft Visual Studio .NET.

Working with SOAP Headers

• Creating a new class that derives from the SoapHeader class. The SoapHeader class is part of System.Web.Services.Protocols namespace,
• Adding an instance of the above class as a member variable to our Web service class, and
• Making use of the [SoapHeder] Web method attribute.

SOAP Headers Demo

<%@ WebService Language="C#" Class="SQLTableData"%>
using System;
using System.Xml;
using System.Xml.Serialization;
using System.Web.Services;
using System.Web.Services.Protocols;

using System.Data;
using System.Data.SqlTypes;
using System.Data.SqlClient;

//Overriding SoapHeader class - to create a class that represents 
//the content of a SOAP Header

public class SQLLoginDetails : SoapHeader
{
   public string UserID;
   public string Password;
   
   [XmlAttribute]
   public string Token;
}


[WebService (Namespace="uri:PerfectXML-TestWS", Description="SOAP Headers Demo")]
public class SQLTableData
{
   public SQLLoginDetails sqlAuthentication;

   public enum eQueryType {eTableQuery, eStoredProcedure};
   
   [WebMethod (Description="Use this method to run a SELECT * query on a table " +
   "or to execute a stored procedure. Method returns DataSet. Requires SQL Server " +
   "authentication details passed as the SOAP Header values.")]
   
   [SoapHeader ("sqlAuthentication", Required=true)]
   public DataSet GetData(string TableOrSPName, eQueryType IsItTableOrSP)
   {
      DataSet dsResult = new DataSet();
      if(sqlAuthentication.Token != "123") 
         throw new Exception("Missing Token.");
      
      string strQuery;
      if (IsItTableOrSP == eQueryType.eTableQuery)
         strQuery = "SELECT * FROM [" + TableOrSPName + "]";
      else
         strQuery = "EXEC " + TableOrSPName;
      
      SqlDataAdapter adapter = new SqlDataAdapter(strQuery,
         "SERVER=.;UID=" + sqlAuthentication.UserID + 
         ";PWD=" + sqlAuthentication.Password + ";INITIAL CATALOG=NorthWind;");
      
      adapter.Fill(dsResult);
      
      return dsResult;
   }
}

<?xml version="1.0" encoding="utf-8"?>
<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>
    <SQLLoginDetails Token="123" 
           xmlns="uri:PerfectXML-TestWS">
      <UserID>sa</UserID>
      <Password></Password>
    </SQLLoginDetails>
  </soap:Header>

  <soap:Body>
    <GetData xmlns="uri:PerfectXML-TestWS">
      <TableOrSPName>Customers</TableOrSPName>
      <IsItTableOrSP>eTableQuery</IsItTableOrSP>
    </GetData>
  </soap:Body>
</soap:Envelope>

<?xml version="1.0" encoding="utf-8" ?> 
<soap:Envelope 
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
 <GetDataResponse xmlns="uri:PerfectXML-TestWS">
  <GetDataResult>
   <xs:schema id="NewDataSet" xmlns="" 
         xmlns:xs="http://www.w3.org/2001/XMLSchema" 
         xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
                        ...
   </xs:schema>

   <diffgr:diffgram 
        xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" 
        xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
                      ...
   </diffgr:diffgram>
  </GetDataResult>
 </GetDataResponse>
</soap:Body>
</soap:Envelope>

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>System.Web.Services.Protocols.SoapException: 
        Server was unable to process request. ---> 
             System.Exception: Missing Token.
        at SQLTableData.GetData(String TableOrSPName, eQueryType IsItTableOrSP)
        --- End of inner exception stack trace ---</faultstring>
      <detail />
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Imports System

Imports System.Data
Imports System.Data.SqlClient
Imports System.Data.SqlTypes

Imports System.Web
Imports System.Web.Services
Imports System.Web.Services.Protocols

Imports HeadersClient.localhost

Public Class Form1
    Inherits System.Windows.Forms.Form

    Private WebSvcClient As New SQLTableData()
    Private HeaderData As New SQLLoginDetails()

    Private Sub btnGetData_Click(ByVal sender As System.Object, 
       ByVal e As System.EventArgs) Handles btnGetData.Click

        Try
            StatusBar1.Text = "Sending Web Service Request..."
            Cursor = Windows.Forms.Cursors.WaitCursor
            Dim ResultDS As DataSet
            dgResults.SetDataBinding(ResultDS, "")

            HeaderData.UserID = txtUserID.Text
            HeaderData.Password = txtPassword.Text
            HeaderData.Token = txtToken.Text

            WebSvcClient.SQLLoginDetailsValue = HeaderData

            If IsItSP.Checked Then
                ResultDS = WebSvcClient.GetData(cbTableOrSPName.Text, 
                                eQueryType.eStoredProcedure)
            Else
                ResultDS = WebSvcClient.GetData(cbTableOrSPName.Text, 
                                eQueryType.eTableQuery)
            End If

            dgResults.SetDataBinding(ResultDS, "Table")

            StatusBar1.Text = "Ready"
        Catch se As SoapException
            StatusBar1.Text = "SOAP Exception: " & se.Message
            MessageBox.Show(se.ToString())
        Catch oe As Exception
            StatusBar1.Text = "Exception: " & oe.Message
            MessageBox.Show(oe.ToString())
        Finally
            Cursor = Windows.Forms.Cursors.Default
        End Try

    End Sub
End Class

    Private Sub bgnGetDataAsync_Click(ByVal sender As System.Object, 
                  ByVal e As System.EventArgs) Handles bgnGetDataAsync.Click
        Try
            StatusBar1.Text = "Sending Web Service Request..."

            Dim ResultDS As DataSet
            dgResults.SetDataBinding(ResultDS, "")

            HeaderData.UserID = txtUserID.Text
            HeaderData.Password = txtPassword.Text
            HeaderData.Token = txtToken.Text

            WebSvcClient.SQLLoginDetailsValue = HeaderData

            Dim CallbackFn As New AsyncCallback(AddressOf GetDataCallback)
            
            If IsItSP.Checked Then
                WebSvcClient.BeginGetData(cbTableOrSPName.Text, 
                         eQueryType.eStoredProcedure, CallbackFn, WebSvcClient)
            Else
                WebSvcClient.BeginGetData(cbTableOrSPName.Text, 
                         eQueryType.eTableQuery, CallbackFn, WebSvcClient)
            End If
        Catch se As SoapException
            StatusBar1.Text = "SOAP Exception: " & se.Message
            MessageBox.Show(se.ToString())
        Catch oe As Exception
            StatusBar1.Text = "Exception: " & oe.Message
            MessageBox.Show(oe.ToString())
        End Try
    End Sub

    Public Sub GetDataCallback(ByVal ar As IAsyncResult)
        Try
            Dim WebSvcClient As SQLTableData = CType(ar.AsyncState, SQLTableData)
            ASyncResultDS = WebSvcClient.EndGetData(ar)

            'See KB Article 318604
            Dim CallDataBindToDataGrid As New MethodInvoker(AddressOf RefreshGrid)
            BeginInvoke(CallDataBindToDataGrid)
        
        Catch se As SoapException
            StatusBar1.Text = "SOAP Exception: " & se.Message
            MessageBox.Show(se.ToString())
        Catch oe As Exception
            StatusBar1.Text = "Exception: " & oe.Message
            MessageBox.Show(oe.ToString())
        End Try
    End Sub

    Public Sub RefreshGrid()
        dgResults.SetDataBinding(ASyncResultDS, "Table")
        StatusBar1.Text = "Ready"
    End Sub

• How to create a Web service that accepts SOAP Headers,
• How to generate SOAP Faults,
• Passing SOAP Headers from the client,
• Handling SOAP Faults on the client side, and
• Sending Asynchronous Web service requests

Passing Binary Data

• Using the "Web Services Enhancements for Microsoft .NET" toolkit that supports WS-Attachment with DIME to send attachments with SOAP. Click here to read an article on MSDN for more details on this. DIME for sending attachments with SOAP messages is also supported by Microsoft SOAP Toolkit 3.0. Click here for more information on this.
  
  
• Encoding the binary data using Base64 or hex encoding and including that directly as part of the XML message (instead of separate attachment).

Binary Data Demo

<%@ WebService Language="C#" Class="BinaryData"%>
using System;
using System.Xml;
using System.Xml.Serialization;
using System.Web.Services;

using System.IO;

[WebService (Namespace="uri:PerfectXML-TestWS", Description="Binary Data Demo")]
public class BinaryData
{
   [WebMethod (Description="Binary Data returned using <b>base64</b> encoding.")]
   public byte[] GetImageAsBase64()
   {
        FileStream ImageFS = new FileStream(@"c:\PXML.JPG", FileMode.Open, FileAccess.Read);

        int ImageSize = Convert.ToInt32(ImageFS.Length);
        byte[] ImageBytes = new byte[ImageSize];
        ImageFS.Read(ImageBytes, 0, ImageSize);
        ImageFS.Close();
        return ImageBytes;
   }

   [WebMethod (Description="Binary Data returned using <b>Hex</b> encoding.")]
   public string GetImageAsHex()
   {
      return System.BitConverter.ToString(GetImageAsBase64()).Replace("-", "");
   }

}

• If the Web service method return value is declares as byte[], the ASP.NET Framework would serialize that byte data using Base64 encoding.
• We use System.BitConverter.ToString method to convert the binary data into hex.

Imports BinaryDataClient.localhost
Imports System.IO
Imports System.Text

Public Class Form1
    Inherits System.Windows.Forms.Form

    Private Sub btnBase64_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnBase64.Click
        Cursor = Cursors.WaitCursor

        Try
            Dim binDataHelper As New BinaryData()

            Dim PicureBytes() As Byte = binDataHelper.GetImageAsBase64()
            EmpPictureBox.Image = New System.Drawing.Bitmap(New MemoryStream(PicureBytes))

        Catch e1 As Exception
            MessageBox.Show(e1.ToString())
        Finally
            Cursor = Cursors.Default
        End Try
    End Sub

    Private Sub btnHex_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnHex.Click
        Cursor = Cursors.WaitCursor

        Try
            Dim binDataHelper As New BinaryData()
            Dim PicureBytes() As Byte = HexStringToByteArray(binDataHelper.GetImageAsHex())
            EmpPictureBox.Image = New System.Drawing.Bitmap(New MemoryStream(PicureBytes))

        Catch e1 As Exception
            MessageBox.Show(e1.ToString())
        Finally
            Cursor = Cursors.Default
        End Try
    End Sub

    Private Function HexStringToByteArray(ByVal hexString As String) As Byte()
        Dim StringLen As Integer

        StringLen = hexString.Length

        If StringLen Mod 2 <> 0 Then
            Throw New ArgumentException()
        End If

        Dim ByteArrLen As Integer = (StringLen / 2) - 1
        Dim resultByteArray(ByteArrLen) As Byte
        Dim iIndex As Integer

        For iIndex = 0 To ByteArrLen
            resultByteArray(iIndex) = Convert.ToByte(hexString.Substring(iIndex * 2, 2), 16)
        Next

        Return resultByteArray
    End Function

End Class

Stateful Web Services

<%@ WebService Language="C#" Class="StateDemo"%>
using System;
using System.Web;
using System.Web.Services;

[WebService (Namespace="uri:PerfectXML-TestWS", Description="Application and Session State Demo")]
public class StateDemo
{

   [WebMethod (
      EnableSession=true,
      Description="Login by passing the Customer ID, such as ALFKI, VINET, etc.")]
   public bool Login(string CustomerID)
   {
      if (CustomerID == null)
         throw new Exception("Customer ID is required.");

      if (CustomerID.Trim().Length <= 0)
         throw new Exception("Customer ID is required.");
      
      if(HttpContext.Current.Session["Customer"] == null)
      {
         HttpContext.Current.Session["Customer"] = CustomerID;

         if(HttpContext.Current.Application["LoggedInUsersCount"] == null)
            HttpContext.Current.Application["LoggedInUsersCount"] = 1;
         else
            HttpContext.Current.Application["LoggedInUsersCount"] = 
               Convert.ToInt32(HttpContext.Current.Application["LoggedInUsersCount"]) + 1;

         return true;
      }
      else
      {
         throw new Exception("Already logged in as " + HttpContext.Current.Session["Customer"]);
      }
      
      return false;
   }
   
   [WebMethod (
      EnableSession=true,
      Description="Logout and end the session.")]
   public bool Logout()
   {
      if(HttpContext.Current.Session["Customer"] == null)
      {
         throw new Exception("Not logged in.");
      }
      else
      {
         HttpContext.Current.Session["Customer"] = null;

         if(HttpContext.Current.Application["LoggedInUsersCount"] == null)
            HttpContext.Current.Application["LoggedInUsersCount"] = 0;
         else
            HttpContext.Current.Application["LoggedInUsersCount"] = 
               Convert.ToInt32(HttpContext.Current.Application["LoggedInUsersCount"]) - 1;

         return true;
      }
      return false;
   }

   [WebMethod (
      EnableSession=true,
      Description="To find out how many users are logged in.")]
   public int GetLoggedInUsersCount()
   {
      if(HttpContext.Current.Application["LoggedInUsersCount"] == null)
         HttpContext.Current.Application["LoggedInUsersCount"] = 0;
      
      return Convert.ToInt32(HttpContext.Current.Application["LoggedInUsersCount"]);
   }

   [WebMethod (
      EnableSession=true,
      Description="To reset the logged in users count.")]
   public void ResetLoggedInUsersCount()
   {
      HttpContext.Current.Application["LoggedInUsersCount"] = 0;
   }
}

Caching

• ASP.NET Caching - Article by Rob Howard
• Caching Architecture Guide for .NET Framework Applications
• ASP.NET Caching Features - .NET Framework Documentation
• INFO: ASP.NET Caching Overview (KB Article 307225)
• ASP.NET Caching (O'Reilly OnDotNet Web site)

<%@ WebService Language="C#" Class="CachingDemo"%>
using System;
using System.Web;
using System.Web.Services;
using System.Xml;
using System.IO;

[WebService (Namespace="uri:PerfectXML-TestWS", Description=".NET XML Web Services Caching Demo")]
public class CachingDemo : WebService
{
   [WebMethod (CacheDuration=60, Description="Returns number of files in the current folder.")]
   public string GetFilesCount()
   {

      string CurDir = Server.MapPath(".");

      string Message = "As of: " + System.DateTime.Now.ToString() + " " + 
         CurDir + " contains " + Directory.GetFiles(CurDir).Length.ToString() +
         " files.";

      return Message;
   }
}

Hooking into HTTP Pipeline

• HOW TO: Create an ASP.NET HTTP Handler by Using Visual C# .NET
• INFO: ASP.NET HTTP Modules and HTTP Handlers Overview
• HTTP Modules
• Serving Up ASP.NET Handlers the Easy Way
• HTTP Handlers and HTTP Modules in ASP.NET
• HTTP Runtime Support
• Deploying HTTP Handlers and HTTP Modules

IHttpHandler Web Service Demo

• first calls a supporting private function that uses DOM to load the SOAP message from the HTTP request stream and extracts the string to be encrypted,
• it then calls another supporting function to do SHA1 encryption on the input string,
• finally, it calls yet another supporting private function, that loads a local XML file that contains SOAP response template, fills it with the SHA1 encrypted string, and writes that to the response stream.

namespace PerfectXML.HttpHandlerTest
{
  using System;
  using System.Web;
  using System.Xml;
  using System.Security.Cryptography;
  
  public class SampleHttpHandler : IHttpHandler
  {
    public bool IsReusable {get {return true; } }
    
    public void ProcessRequest(HttpContext ctx)
    {
      string InputString = GetInputString(ctx);

      string SHA1EncryptedString = DoSHA1Encryption(InputString);

      SendResponse(ctx, SHA1EncryptedString);

      return;
    }

    private string GetInputString(HttpContext ctx)
    {
      try
      {
        XmlReader reqStreamReader = new XmlTextReader(ctx.Request.InputStream);
        XmlDocument soapRequestDoc = new XmlDocument();
        soapRequestDoc.Load(reqStreamReader);

        XmlNode inputStringNode;
        inputStringNode = soapRequestDoc.DocumentElement.SelectSingleNode("//InputString");

        return inputStringNode.InnerText;
      }
      catch(Exception e1)
      {
        return e1.ToString();
      }
    }

    private string DoSHA1Encryption(string InputString)
    {
      const int DATA_SIZE = 40;
      byte[] data = new byte[InputString.Length];

      char[] chardata = InputString.ToCharArray();
      char[] resultdata = new char[DATA_SIZE];

      int iIndex=0;
      foreach (char c in chardata)
        data[iIndex++] = Convert.ToByte(c);

      byte[] result; 

      SHA1 sha = new SHA1CryptoServiceProvider(); 
      result = sha.ComputeHash(data);
      return System.BitConverter.ToString(result).Replace("-","").ToLower();
    }

    private void SendResponse(HttpContext ctx, string SHA1EncryptedString)
    {
      try
      {
        ctx.Response.BufferOutput = true;
        ctx.Response.ContentType = "text/xml";

        XmlDocument soapResponseDoc = new XmlDocument();
        soapResponseDoc.Load(ctx.Server.MapPath("SOAPResponse.xml"));

        XmlNode resultStringNode;
        resultStringNode = soapResponseDoc.DocumentElement.SelectSingleNode("//GetSHA1HashResult");
        resultStringNode.InnerText = SHA1EncryptedString;

        ctx.Response.Write(soapResponseDoc.DocumentElement.InnerXml);
      }
      catch(Exception e)
      {
        ctx.Response.Write(e.ToString());
      }
    }
  }
}

• Step 1: Compile the C# class
          csc /out:bin\SampleHttpHandler.dll /t:library SampleHttpHandler.cs
  
  Make sure you have a sub-folder named bin under the current virtual root and run the above command on the DOS command prompt. The above command executes the C# command line compiler asking it to build a assembly DLL and put it in the bin folder.
  
  
• Step 2: Update IIS Metabase
  Start IIS Service Manager, right click on the virtual directory, select Properties, click on Configuration button on the "Virtual Directory" tab to bring the Application Configuration dialog box. Click "Add" button to add the Application Extension Mapping. For Executable text box, select aspnet_isapi.dll from the same location as it is for .aspx or .asmx handler (for example: C:\WINNT\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll), type extension as .enc. Leave Verbs to "All Verbs" and only "Script engine" checked.
  
  This tells IIS that for any HTTP request for file with extension .enc, it should forward the request to ASP.NET (aspnet_isapi.dll). Only thing remaining now is to tell ASP.NET to use our handler for such requests. We do this by updating web.config file under the vroot.
  
  
• Step 3: Updating web.config
  Add the following entry in the web.config file under the system.web section:

  <httpHandlers>
    <add verb="*" path="*.enc" 
        type="PerfectXML.HttpHandlerTest.SampleHttpHandler, SampleHttpHandler" />
  </httpHandlers>

  The above web.config entry defines a new HttpHandler for all types of requests for all files with extension .enc. The type attribute contains the fully qualified class name followed by the assembly name.

  Try
      Cursor = Cursors.WaitCursor

      'Send POST request to *.enc file - the request stream contains the SOAP message
      Dim req As HttpWebRequest = _
        CType(WebRequest.Create("http://localhost/RealWorldWebSvcs/test.enc"), HttpWebRequest)
      req.Method = "POST"
      req.ContentLength = txtInput.Text.Length
      Dim aStream As Stream = req.GetRequestStream()
      Dim encoding As New ASCIIEncoding()
      Dim byteData As Byte() = encoding.GetBytes(txtInput.Text)
      aStream.Write(byteData, 0, byteData.Length)
      aStream.Close()


      'Read the Response
      Dim res As HttpWebResponse = req.GetResponse()
      aStream = res.GetResponseStream()
      Dim byteResultData(res.ContentLength) As Byte
      aStream.Read(byteResultData, 0, res.ContentLength)
      txtOutput.Text = encoding.GetString(byteResultData)
      aStream.Close()

  Catch e1 As Exception
      txtOutput.Text = e1.ToString()
  Finally
      Cursor = Cursors.Default
  End Try

Tips

• Disabling GET and POST
  By default, ASP.NET Web services support GET, POST, and SOAP methods to invoke Web services. The remove element can be used to turn off GET and POST:

   <system.web>
     <webServices>
  
        <protocols>
           <remove name="HttpPost"/>
           <remove name="HttpGet"/>
        </protocols>
  
     </webServices>
   </system.web> 

• Web Service URL from the web.config file
  When you run wsdl.exe (or when Visual Studio .NET runs it for you to add Web Reference), the generated Web service proxy class contains the hard-coded reference to the Web service URL. However if you wanted the flexibility to configure the Web service URL, you can pass /appsettingurlkey: (or /urlkey: for short) parameter with wsdl.exe and along with the key in web.config file from where the generated proxy class will read the Web service URL.
  
  
• Generating code using wsdl.exe
  By default the wsdl.exe tool generates the Web service client (proxy) code. However, if you pass the /server parameter, it will generate an abstract class for an XML Web service implementation. By default C# code is generated, use /language (or /l for short) for other languages such as VB.NET.
  
  
• web.config editor
  If you hate text editing .config files, then $24.95 can get you an excellent editor. See HunterStone Inc. Web site for more details.

Summary