Overview

Web services are the single most hotly hyped feature of the .NET platform, and it's no wonder—used properly, Web services can wrap legacy components, cross platform boundaries, and even Web-enable traditional rich desktop applications.

One of the most important details you should understand about Web services is that they use exactly the same Microsoft Visual Basic .NET code as any other .NET application. Therefore, you can use all the recipes from earlier chapters in a Web service to access files, connect to a database, process strings with regular expressions, and much more. The recipes in this chapter concentrate on .NET features that are unique to Web services. For example, you'll learn how to use caching with a Web service (recipes 16.2 and 16.3), how to use transactional Web methods (recipe 16.4), how to leverage Internet Information Services (IIS) authentication (recipe 16.6), and how to extend Web services with SOAP headers and a full-fledged SOAP extension (recipes 16.9 and 16.11).

Avoid Hard Coding the Web Service URL

Problem

You need to use a Web service whose URL might change.

Solution

Use a dynamic URL, which will be retrieved automatically from the client application's configuration file.

Discussion

By default, when you add a Web reference in Microsoft Visual Studio .NET, the Web service URL is hard-coded in the constructor of the proxy class.

Public Sub New() MyBase.New() Me.Url = "http://localhost/WebServices/MyService.asmx" End Sub

You can override this setting in your code by manually modifying the Url property of the proxy class after you instantiate it. However, there's another option: configure the proxy class to use a dynamic URL endpoint. You can make this change by selecting the Web reference in the Visual Studio .NET Solution Explorer and changing the URL Behavior option in the Properties window, as shown in Figure 16-1.

Figure 16-1: Configuring a dynamic Web service URL.

After you make this change, the Web service URL will be automatically added to the client application's configuration file. (The configuration file is named web.config for all Web applications and AppName.exe.config for all other applications, in which case the file appears in the design environment as simply App.config.) An example of the automatically generated configuration file setting is shown here:

value="http://localhost/WebServices/MyService.asmx"/>

In addition, the code in the proxy class is modified so that it attempts to read the URL from the configuration file. If it doesn't find the required value, it defaults to the URL that was used during development.

Public Sub New() MyBase.New() Dim urlSetting As String = _ ConfigurationSettings.AppSettings("AppName.ServerName.ServiceName") If Not urlSetting Is Nothing Then Me.Url = urlSetting Else Me.Url = "http://localhost/WebServices/MyService.asmx" End If End Sub

This approach allows you to modify the Web service URL after compiling and deploying the application, simply by editing the configuration file.

16 2 Add Response Caching

Problem

You want to improve Web service performance by caching the return value of a Web method.

Solution

Use response caching by setting the CacheDuration property of the WebMethod attribute.

Discussion

ASP.NET Web services support response caching in much the same way as ASP.NET Web pages. When response caching is enabled, your code runs only once, and the return value of the Web method is stored for subsequent method invocations. With Web forms, caching is performed on a per-form basis. With Web services, caching is enabled and configured distinctly for each Web method.

For example, the following Web method returns the current date and time on the server. This information is cached for one minute, meaning that subsequent requests within this timeframe will receive the previously recorded date information. You can test this behavior using the Web service test page.

_ Public Function GetDate() As String Return DateTime.Now.ToString() End Function

If your Web method accepts parameters, ASP.NET will only reuse the cached method result if it receives a request with the exact same parameters. If you have a method that accepts a wide range of values, caching might be ineffective or even wasteful because a great deal of information might be stored in the cache but rarely reused. For example, a Web method that performs a mathematical calculation based on numeric input is rarely a good choice for response caching. On the other hand, a Web method that accepts an ID referencing one of about a dozen different product items probably is. As always, response caching bypasses your code, making it unsuitable if your Web method needs to perform other actions (such as logging activity) or if your Web method depends on information that's not supplied through method parameters (such as user authentication information or session data).

16 3 Add Data Caching

Problem

You want to improve Web service performance by caching some data, but you need to reuse cached data among several methods. Or, you want to run your Web method code but still use some cached information.

Solution

Store any object in the cache using the Cache object.

Discussion

Data caching with a Web service works almost exactly the same as the Web page data caching technique described in recipe 15.11. In fact, you can store data in the cache using Web page code and retrieve it in a Web service, or vice versa. Data caching supports two types of expiration policy: absolute expiration and sliding expiration. For more information, refer to recipe 15.11.

The only difference between caching in a Web service and caching in a Web page is that in the former case, you can't retrieve the Cache as a built-in property. Instead, you need to access the cache through the shared HttpContext.Current property.

The following example shows a Web service with two Web methods. The first Web method, GetFullCustomerData, returns a DataSet with a table of customer information. This DataSet is either retrieved from the cache or generated automatically (if required) using the private GetCustomerDataSet function. The second Web method, GetCustomerNameList, also uses the customer DataSet and the GetCustomerDataSet function. However, it retrieves a subset of the available information—a list of contact names—and returns it as a string. The end result is that both Web methods can use the same cached data, reducing the burden that is placed on the database.

The full Web service code is shown here:

_ Public Class DataCachingTest Inherits System.Web.Services.WebService _ Public Function GetFullCustomerData() As DataSet ' Return the full customer table (from the cache if possible). Return GetCustomerDataSet() End Function _ Public Function GetCustomerNameList() As String() ' Get the customer table (from the cache if possible). Dim Dt As DataTable = GetCustomerDataSet().Tables(0) ' Create an array that will hold the name of each customer. Dim Names() As String ReDim Names(Dt.Rows.Count - 1) ' Fill the array. Dim Row As DataRow Dim i As Integer For Each Row In Dt.Rows Names(i) = Row("ContactName").ToString() i += 1 Next Return Names End Function Private Function GetCustomerDataSet() As DataSet Dim Cache As System.Web.Caching.Cache Cache = HttpContext.Current.Cache ' Check for cached item. If Cache("Customers") Is Nothing Then ' Recreate the item. Dim Customers As New DataSet("Customers") ' Create the connection. The connection string is retrieved ' from a setting in the web.config file. Dim Con As New SqlConnection( _ ConfigurationSettings.AppSettings("DBCon")) ' Create the command for filling the DataSet. Dim CmdSelect As New SqlCommand("SELECT * FROM Customers", Con) Dim Adapter As New SqlDataAdapter(CmdSelect) ' Fill the DataSet. Try Con.Open() Adapter.Fill(Customers, "Customers") Catch Err As Exception ' Throw a higher-level exception to mask any sensitive ' error information. Throw New ApplicationException("Database error.") Finally Con.Close() End Try ' Store the item in the cache (for 60 seconds). Cache.Insert("Customers", Customers, Nothing, _ DateTime.Now.AddSeconds(60), TimeSpan.Zero) ' Return the item. Return Customers Else ' Retrieve the item. Return CType(Cache("Customers"), DataSet) End If End Function End Class

16 4 Create a Transactional Web Method

Problem

You want to execute all the actions in a Web method within the context of a single COM+ transaction so that they all either fail or succeed as a unit.

Solution

Enable an automatic transaction using the TransactionOption property of the WebMethod attribute.

Discussion

.NET Web services include support for automatic transactions that can be enabled on a per-method basis. When enabled, any data source that supports COM+ transactions (which includes most databases) is automatically enlisted in the current transaction when it's used in your code. The transaction is automatically committed when the Web method completes. The transaction is rolled back if any unhandled exception occurs or if you explicitly call the SetAbort method of the System.EnterpriseServices.ContextUtil class.

To enable transaction support for a Web method, set the TransactionOption property of the WebMethod attribute to RequiresNew. For example, the transactional Web method shown in the following code takes two actions—it deletes records in a database and then tries to read from a file. However, if the file operation fails and the exception is not handled, the entire operation will be rolled back. To use this code, you must add a reference to the System.EnterpriseServices.dll assembly and import the System.EnterpriseServices namespace.

_ Public Sub UpdateDatabase() ' Create the connection. Dim Con As New SqlConnection(ConfigurationSettings.AppSettings("DBCon")) ' Create the command for filling the DataSet. Dim Cmd As New SqlCommand("DELETE * FROM Customers", Con) ' Apply the update. This will be registered as part of the transaction. Con.Open() Cmd.ExecuteNonQuery() ' Try to access a file. ' This generates an exception which is not handled. ' The Web method will be aborted and the changes will be rolled back. Dim fs As New System.IO.FileStream("does_not_exist.bin", IO.FileMode.Open) ' (If no errors have occurred, the database changes ' are committed here when the method ends). End Sub

You can use the Component Services console to monitor this transaction. You can start the Component Services utility by selecting Component Services from the Administrative Tools section of the Control Panel. In the Component Services console, select the Distributed Transaction Coordinator for the current computer, and view the Transaction Statistics. Figure 16-2 shows how the display will look after running this code, which produces one failed transaction.

Figure 16-2: Monitoring a failed transaction.

Because of the stateless nature of the HTTP protocol, a Web service method can participate only as the root of a transaction, which means that you can't enlist more than one Web method in the same transaction. Although the TransactionOption property accepts all the standard TransactionOption values, the values don't have the expected meanings. For example, Disabled, NotSupported, and Supported all have the same effect: they disable transaction support. Similarly, Required and RequiresNew both enable transaction support and start a new transaction. I recommend that you use RequiresNew in your Web methods because its name most clearly matches the actual behavior.

16 5 Create a One Way Web Method

Problem

You want a Web method to perform a long task, and you don't want to force the client to wait while the Web service code executes.

Solution

Create a one-way Web method by applying the SoapDocumentMethod or SoapRpcMethod attribute and setting the OneWay property to True.

Discussion

With one-way Web methods, the client sends a request message, and the server responds immediately to indicate that the method began processing. This behavior has the following consequences:

• The client doesn't need to wait while the Web method code executes.
• The Web method can't return any information to the client, either through a return value or a ByRef parameter.
• If the Web method throws an unhandled exception, it won't be propagated back to the client.

To create a one-way Web method, you need to apply a SoapDocumentMethod attribute (from the System.Web.Services.Protocols namespace) to the appropriate method and set the OneWay property to True. Here's an example:

_ Public Sub DoLongTask() ' (Start a long task that doesn't return ' information to the client.) End Sub

This example assumes that your Web service and client are using SOAP document encoding (the default). If you're using RPC encoding, use the corresponding SoapRpcMethod attribute to mark a one-way method.

16 6 Set Authentication Credentials for a Web Service

Problem

You want a Web service client to submit logon credentials for IIS authentication.

Solution

Use the Credentials property of the proxy class. You can create a new NetworkCredential object or use the CredentialCache to retrieve the credentials for the current user.

Discussion

Web services, like Web pages, can be used in conjunction with IIS authentication. All you need to do is place your Web services in a virtual directory that restricts anonymous access.

Unlike Web pages, Web services have no built-in method for retrieving authentication information from the client because Web services are executed by other applications, not directly by the user. Thus, the application that's interacting with the Web service bears the responsibility for submitting any required authentication information. Furthermore, Web services must use a form of Windows authentication that maps user credentials to valid user accounts. Form-based authentication will not work.

To create a simple Web service test, enable both anonymous and Windows Integrated authentication for the virtual directory in IIS Manager. Make sure that the web.config file specifies that Windows authentication will be used and that anonymous users will be permitted.

Next create a new subdirectory. Add a web.config file that explicitly denies anonymous users, as shown here:

Unauthenticated calls to any Web services in this directory will fail. However, if the user can submit credentials that map to a valid user account, the user will be authenticated and you'll be able to retrieve the authentication information through the built-in User object.

The following Web service provides a simple user authentication test. GetIISUser returns the user that was authenticated by IIS. If anonymous access is allowed, the result will be an empty string because no authentication will be performed. If anonymous access is denied, the result will be a string in the form [DomainName][UserName] or [ComputerName][UserName]. You can use the role-based security techniques described in recipe 18.2 to examine the group membership of this authenticated user.

_ Public Class AuthenticationTest Inherits System.Web.Services.WebService ' Retrieves the authenticated IIS user. _ Public Function GetIISUser() As String Return User.Identity.Name End Function End Class

The final step is to create a client that can submit the authentication information. The credentials are submitted through the Credentials property of the Proxy class. If you are using Basic authentication, you must create a NetworkCredential object that specifies the user name and password information. If you are using Windows Integrated authentication, you can automatically use the credentials of the currently logged on user using the shared CredentialCache.DefaultCredentials property. Both the CredentialCache and NetworkCredential classes are found in the System.Net namespace.

Figure 16-3 shows a Windows client that tests both approaches to authentication and attempts an unauthenticated call.

Figure 16-3: A client that tests authentication.

The full form code for the client is shown here:

Public Class AuthenticationClient Inherits System.Windows.Forms.Form ' (Designer code omitted.) Private Sub cmdNoAuthenticate_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdNoAuthenticate.Click ' Create the proxy. Dim Proxy As New localhost.AuthenticationTest() CallMethod(Proxy) End Sub Private Sub cmdAuthenticateCurrent_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdAuthenticateCurrent.Click ' Create the proxy. Dim Proxy As New localhost.AuthenticationTest() ' Assign the current user's credentials to the proxy class. ' This works for Windows Integrated authentication. Proxy.Credentials = System.Net.CredentialCache.DefaultCredentials CallMethod(Proxy) End Sub Private Sub cmdAuthenticateCustom_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdAuthenticateCustom.Click ' Create the proxy. Dim Proxy As New localhost.AuthenticationTest() ' Assign the credentials from the user name and password textboxes. ' This is required for Basic authentication. Proxy.Credentials = New System.Net.NetworkCredential( _ txtUser.Text, txtPassword.Text) CallMethod(Proxy) End Sub Private Sub CallMethod(ByVal proxy As localhost.AuthenticationTest) Try MessageBox.Show("User: " & proxy.GetIISUser(), _ "Authentication Succeeded") Catch Err As Exception MessageBox.Show(Err.Message, "Authentication Failed") End Try End Sub End Class

16 7 Use Session State

Problem

You want to create a Web service that can store information in user-specific session state.

Solution

Avoid this option if possible because it leads to several complications. If it's absolutely necessary to use session state, set the EnableSession property of the WebMethod attribute to True, and initialize the CookieContainer property of the proxy class before calling the Web method.

Discussion

ASP.NET Web services can use session state to store objects in server-side memory. However, this approach has several consequences, including:

• Because session state must be tracked using a cookie with the session ID, the client must take additional steps to maintain the cookie. In addition, session state won't work over protocols other than HTTP.
• Cookies are maintained separately for each proxy class. Therefore, there's no easy way for multiple Web services to access the same session information for a client.
• Web services are usually designed as stateless classes. Creating a Web service that retains information between calls might lead to behavior the client does not expect. In addition, the lifetime of a session does not necessarily match the lifetime of the Web service proxy object.
• If you store a large amount of information in session state, server memory will become scarce and performance will suffer.

If you still decide to use session state, you must tweak both the Web service and the client code. On the Web service side, every Web method that needs access to the session state collection must set the EnableSession property of the WebMethod attribute to True. If you do not take this step, any existing session information will be preserved, but it will not be deserialized and made available to your Web method code.

The following Web service allows the remote user to store and retrieve a simple string:

_ Public Class SessionTest Inherits System.Web.Services.WebService _ Public Sub SetString(ByVal data As String) Session("Data") = data End Sub _ Public Function GetString() As String Return CType(Session("Data"), String) End Function End Class

On the client side, you must create an empty cookie collection before you use the proxy. Otherwise, the proxy will not be able to accept the ASP.NET session cookie and a new session will be started for each method call. The client will need to maintain this instance of the proxy class (or at least its cookie collection) as long as it needs to access the same session.

Here's the code for a sample client that sends the data from a text box to the session-enabled Web service:

Public Class SessionClient Inherits System.Windows.Forms.Form ' (Designer code omitted.) Private Proxy As New localhost.SessionTest() Private Sub Form_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load ' Initialize the cookie container. Proxy.CookieContainer = New System.Net.CookieContainer() End Sub Private Sub cmdSet_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdSet.Click Proxy.SetString(txtData.Text) txtData.Text = "" End Sub Private Sub cmdGet_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdGet.Click txtData.Text = Proxy.GetString() End Sub End Class

16 8 Upload or Download Large Binary Data

Problem

You want to transfer an image or a file to or from a Web service.

Solution

Submit or return the data as a byte array.

Discussion

Web services support only a carefully limited set of data types, an approach that's designed to ensure optimum cross-platform compatibility. However, you can transmit virtually anything if you convert it to binary first.

The following Web service accepts a byte array and saves it directly to disk. For this code to work, the ASP.NET process must have privileges to write to the appropriate directory. You should also import the System.IO namespace.

_ Public Class UploadData Inherits System.Web.Services.WebService _ Public Sub UploadFile(ByVal originalName As String, _ ByVal buffer As Byte()) ' Canonicalize the originalName value so it just includes a filename. ' This strips out any path information, which a malicious user could ' submit to trick your application into writing in the wrong location. originalName = Path.GetFileName(originalName) ' Retrieve the save path from the configuration file. Dim SavePath As String SavePath = ConfigurationSettings.AppSettings("UploadDirectory") SavePath = Path.Combine(SavePath, originalName) ' Use CreateNew mode, so that an error will be raised if a file ' with the same name already exists. Dim fs As New FileStream(SavePath, FileMode.CreateNew) ' Write the file. fs.Write(buffer, 0, buffer.Length) fs.Close() End Sub End Class

Here is a sample client that allows the user to select a file and submit it to the Web service:

Public Class UploadClient Inherits System.Windows.Forms.Form ' (Designer code omitted.) Private Sub cmdUpload_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles cmdUpload.Click Me.Cursor = Cursors.WaitCursor ' Show a dialog that allows the user to choose a file. Dim dlgOpen As New OpenFileDialog() If dlgOpen.ShowDialog() = DialogResult.OK Then ' Read the file into a byte array. Dim fs As New FileStream(dlgOpen.FileName, FileMode.Open) Dim Buffer As Byte() ReDim Buffer(fs.Length) fs.Read(Buffer, 0, fs.Length) fs.Close() ' Submit the byte array to the Web service. Dim Proxy As New localhost.UploadData() Proxy.UploadFile(Path.GetFileName(dlgOpen.FileName), Buffer) MessageBox.Show("Upload complete.") End If Me.Cursor = Cursors.Default End Sub End Class

Notice that this example doesn't take security into account. In a production-level application, you would want to authenticate the user before allowing him or her to write data to the server (using the technique shown in recipe 16.6). You might also limit the maximum accepted message size to prevent denial of service attacks that work by flooding the server with data.

You would also need to take additional steps to prevent name collision, which occurs when two files are uploaded with the same name. Name collision causes the first file to be overwritten or the second operation to fail, depending on the file access mode you use. To prevent name collision, you could create a new GUID with each Web method request and use this GUID as the file name. In this case, you would probably need to log some information in a database mapping the GUID to the original file name. Alternatively, you might want to use multiple user-specific directories and allow users to overwrite their own uploaded files.

16 9 Send Out of Band Data in a SOAP Header

Problem

You want to send some information to one or more Web methods without having to add it as a method parameter.

Solution

Create a custom SOAP header that encapsulates the additional information you need.

Discussion

Sometimes, you might need to submit information to a Web method that does not specifically relate to the method itself. This is most often the case when you are building your own custom authentication system or state management system, and you need to submit some type of credentials or tracking information every time you call the Web service. You can accommodate this information by inserting additional parameters into every method. However, this approach raises several problems, including:

• The client needs to track this information and remember to submit it with each request.
• The Web service method signatures are needlessly cluttered.
• If you change your custom authentication or tracking system, you must modify each and every method definition.

A better approach is to submit this data out-of-band as a SOAP header. In this case, the client needs to specify the information only once and it will be automatically added to every request message as needed.

For example, consider a Web service that uses ticket-based authentication. In this system, the user is authenticated only once and given a time-limited GUID ticket. This ticket is presented on subsequent method invocations, saving the effort of re-authenticating the user with each request. In ticket-based authentication, you might want to create a SOAP header that tracks the user's authenticated GUID ticket. The class would derive from SoapHeader in the System.Web.Services.Protocols namespace and would add a single public member variable.

Public Class TicketHeader Inherits SoapHeader Public Ticket As Guid End Class

Now you must modify the Web service so that it includes a public TicketHeader member variable.

_ Public Class TicketTest Inherits System.Web.Services.WebService ' Holds the authentication SOAP header. Public Ticket As TicketHeader ' (Other code omitted.) End Class

Web methods that need to use or set TicketHeader must include the SoapHeader attribute. This attribute provides the following two pieces of information:

• It indicates which member variable will be used to receive the header. This variable is defined as a string, but it must correspond to a public Web service member variable of the appropriate type.
• It specifies the Direction, which indicates whether the Web method will receive the header from the client (SoapHeaderDirection.In), return a new header to the client (SoapHeaderDirection.Out), or need to be able to receive and modify the header (SoapHeaderDirection.InOut).

For example, the following Login Web method creates the authentication ticket if the user can be successfully authenticated. It uses SoapHeaderDirection.Out because it creates the SOAP header and returns it to the client.

_ Public Function Login(ByVal userName As String, ByVal password As String) _ As Boolean ' Typically, you would look up the user record in the database. ' In this case, authentication simply checks that the password is "test" If password = "test" Then ' Create the SOAP header. Ticket = New TicketHeader() Ticket.Ticket = Guid.NewGuid() ' Store the ticket in server memory to validate against later. Application(Ticket.Ticket.ToString()) = Ticket Return True Else Return False End If End Function

The Logout method, on the other hand, uses SoapHeaderDirection.InOut, which means it automatically receives the SOAP header from the client (if it exists). In addition, any changes that are made to the SOAP header are propagated back to the client.

_ Public Sub Logout() If Not (Ticket Is Nothing) Then ' Remove the server-side ticket information. Application(Ticket.Ticket.ToString()) = Nothing ' Remove the ticket information from the SOAP header. Ticket.Ticket = Nothing End If End Sub

All other methods can now receive the ticket header. The following DoSomething method is one example. It returns a string that indicates whether the ticket was found and could be authenticated. Usually, you would use these criteria to decide whether to carry on with a task or throw a SecurityException.

_ Public Function DoSomething() As String If IsAuthenticated() Then Return "Sucessful authentication" Else Return "Failed authentication" End If End Function Private Function IsAuthenticated() As Boolean ' Check first that the ticket exists. If Ticket Is Nothing Then Return False ' Now check if the ticket in the header corresponds to ' the ticket stored in server memory. If Application(Ticket.Ticket.ToString()) Is Nothing Then Return False Else Dim CachedTicket As TicketHeader CachedTicket = CType(Application(Ticket.Ticket.ToString()), _ TicketHeader) ' (This is where you would add any expiration logic.) ' Verify the ticket values are the same. ' This is not really necessary, but it's a simple failsafe. If CachedTicket.Ticket.CompareTo(Ticket.Ticket) = 0 Then Return True Else Return False End If End If End Function

Finally, consider the simple test code for a Windows client shown below. Notice that the client simply needs to call the Login method before using any other Web methods. The client does not need to interact with the ticket directly or even be aware that the ticket exists at all.

Dim Proxy As New localhost.TicketTest() Dim Success As Boolean = Proxy.Login("Me", "test") MessageBox.Show("Login result: " & Success.ToString()) ' This succeeds. Dim Result As String = Proxy.DoSomething() MessageBox.Show("DoSomething result: " & Result) Proxy.Logout() ' This fails, because the ticket information no longer exists. Result = Proxy.DoSomething() MessageBox.Show("DoSomething result: " & Result)

16 10 Trace a SOAP Message Using the SOAP Toolkit

Problem

You want to see raw SOAP request and response messages, probably for debugging purposes.

Solution

Use the SOAP trace utility included with the Microsoft SOAP Toolkit, and forward all Web service request messages to port 8080.

Discussion

The SOAP Toolkit includes COM components that you can use to call Web services in non-.NET clients. However, even if you code exclusively in the .NET world, you'll still find that the trace utility can be quite useful.

You can download the latest version of the SOAP Toolkit from http://msdn.microsoft.com/library/default.asp?url=/downloads/list/websrv.asp. You can then run the trace utility from the Start Menu icons created by the setup application. (Look for a shortcut named Trace Utility.)

To start a trace, select File | New | Formatted Trace from the menu in the trace utility. You can then use the defaults shown in Figure 16-4, in which case the trace utility will listen on port 8080 and forward all received messages to port 80 (which IIS uses to listen for all HTTP Web requests).

Figure 16-4: Configuring a SOAP trace.

To trace the messages sent in your application, you need to modify the client code so that SOAP requests are sent to the trace listener at port 8080. You can do so by modifying the Web service URL. For example, if your Web service is at http:// localhost/VBCookbookWebServices/Recipe16-7.asmx, request http://localhost:8080/VBCookbookWebServices/Recipe16-7.asmx instead. The following code shows how you can modify the URL of the proxy class using the System.Uri class, which allows you to insert the 8080 port into any URL.

' Retrieve the current URL for the proxy class. Dim ProxyUri As New Uri(Proxy.Url) ' Insert the port 8080. Proxy.Url = ProxyUri.Scheme & "://" & ProxyUri.Host & _ ":8080" & ProxyUri.AbsolutePath

The trace listener will then forward your message to its destination (the Web service), intercept the response message, and forward it to your client. The full message trace will be displayed in the utility. Figure 16-5 shows an example using the Web service from recipe 16.7, with two messages.

Figure 16-5: The results of a SOAP trace.

16 11 Log SOAP Messages with a SOAP Extension

Problem

You want to directly access or modify raw SOAP messages with .NET code.

Solution

Create a custom SOAP extension.

Discussion

ASP.NET allows you to access the raw SOAP messages that are transmitted to and from a Web service, but only by creating a special SOAP extension class. This class is triggered automatically as the SOAP message passes through the following four stages on the server:

• SoapMessageStage.BeforeDeserialize occurs immediately after the Web server receives the SOAP request message.
• SoapMessageStage.AfterDeserialize occurs after the raw SOAP message is translated to .NET data types but just before the Web method code runs.
• SoapMessageStage.BeforeSerialize occurs after the Web method code runs but before the return value is translated into a SOAP message.
• SoapMessageStage.AfterSerialize occurs after the return data is serialized into a SOAP response message but before it is sent to the client.

Each time the message moves into a new stage, ASP.NET calls the ProcessMessage method of any attached SOAP extensions. Your SOAP extension can respond by inspecting and logging various information about the SOAP message. If the message is in the BeforeDeserialize or AfterSerialize stage, you can retrieve the full SOAP message text. This recipe presents the complete code for a SOAP extension that logs SOAP request and response messages to the Windows event log on the server.

All SOAP extensions consist of two ingredients: a custom class that derives from System.Web.Services.Protocols.SoapExtension and a custom attribute that you apply to a Web method to indicate that your SOAP extension should be used. The custom attribute is the simpler of the two ingredients. It needs to include two properties: Priority (which is seldom used) and ExtensionType (which returns a Type object that represents your custom SoapExtension class). You can also add additional properties that will be used to supply initialization information to your SOAP extension. The following example adds an EventSource property, which stores the source string that will be used when writing event log entries:

_ Public Class EventLogSoapExtensionAttribute Inherits SoapExtensionAttribute Private _Priority As Integer Private _EventSource As String ' The priority property allows you to configure the order that multiple ' SOAP extensions will execute in, if order is important. Public Overrides Property Priority() As Integer Get Return _Priority End Get Set(ByVal Value As Integer) _Priority = Value End Set End Property ' This is a custom piece of data used to configure event log entries. Public Property EventSource() As String Get Return _EventSource End Get Set(ByVal Value As String) _EventSource = Value End Set End Property ' Returns the type representing the SOAP extension class. ' In this case, the class is named EventLogSoapExtension. Public Overrides ReadOnly Property ExtensionType() As System.Type Get Return GetType(EventLogSoapExtension) End Get End Property End Class

The EventLogSoapExtension class is much longer. Most of the code is basic boilerplate that you can copy into any SOAP extension. The custom logging logic is shown in bold text. All the lines that aren't bold are generic and will be a part of any SOAP extension you create.

Public Class EventLogSoapExtension Inherits SoapExtension ' These properties track the SOAP message as it is being ' serialized or deserialized. Private OldStream As Stream Private NewStream As Stream Public Overrides Function ChainStream(ByVal stream As Stream) As Stream OldStream = stream NewStream = New MemoryStream() Return NewStream End Function ' The source string that will be used when writing log entries. Private EventSource As String Public Overloads Overrides Function GetInitializer( _ ByVal methodInfo As LogicalMethodInfo, _ ByVal attribute As SoapExtensionAttribute) As Object ' Retrieve the EventSource property from the associated attribute. ' Use this information as the SOAP extension initializer. Return CType(attribute, EventLogSoapExtensionAttribute).EventSource End Function Public Overloads Overrides Function GetInitializer( _ ByVal serviceType As Type) As Object ' The SOAP extension was loaded through a configuration file. ' Do not attempt to retrieve the initializer. Return "" End Function Public Overrides Sub Initialize(ByVal initializer As Object) ' Apply the initializer every time the SOAP extension is executed. EventSource = CType(initializer, String) If EventSource = "" Then EventSource = "SOAPExtension" End Sub ' This method is invoked as the SOAP message changes stages. Public Overrides Sub ProcessMessage(ByVal message As SoapMessage) If message.Stage = SoapMessageStage.AfterSerialize Then ' The SOAP response message has just been created. ' We can log it. NewStream.Position = 0 Dim LogData As New MemoryStream() CopyStream(NewStream, LogData) LogMessage(LogData, message) NewStream.Position = 0 CopyStream(NewStream, OldStream) ElseIf message.Stage = SoapMessageStage.BeforeDeserialize Then CopyStream(OldStream, NewStream) NewStream.Position = 0 ' The SOAP request message has not yet been deserialized. ' We can log it. Dim LogData As New MemoryStream() CopyStream(NewStream, LogData) LogMessage(LogData, message) NewStream.Position = 0 End If End Sub Private Sub LogMessage(ByVal messageContent As Stream, _ ByVal message As SoapMessage) ' Create a log message that includes data about the SOAP message, ' and the contents of the SOAP message itself. Dim LogMessage As String LogMessage &= "Message in: " & message.Stage.ToString() & vbNewLine LogMessage &= "Action: " & message.Action & vbNewLine LogMessage &= "URL: " & message.Url & vbNewLine LogMessage &= "Time: " & DateTime.Now.ToString() messageContent.Position = 0 Dim r As New StreamReader(messageContent) LogMessage &= r.ReadToEnd() ' Create the EventLog source if needed. ' This action will only succeed if the ASP.NET worker process is ' running under an account that has been granted full control ' for the event log registry keys. If Not EventLog.SourceExists(EventSource) Then EventLog.CreateEventSource(EventSource, "Application") End If ' Log the message. Dim Log As New EventLog() Log.Source = EventSource Log.WriteEntry(LogMessage) End Sub Private Sub CopyStream(ByVal fromStream As Stream, _ ByVal toStream As Stream) Dim r As New StreamReader(fromStream) Dim w As New StreamWriter(toStream) w.WriteLine(r.ReadToEnd()) w.Flush() End Sub End Class

Finally you need to apply the custom EventLogSoapExtension attribute to any method that will use the SOAP extension. At the same time, you can specify the event source that should be used for logging.

_ Public Sub DoSomething() ' (No code needed.) End Function

Now when a client invokes the DoSomething method, the EventLogSoapExtension will be invoked automatically and ProcessMessage will be called four times. Two messages will be logged to the Application event log, one for the request message (as shown in Figure 16-6) and one for the response message.

Figure 16-6: The SOAP message information in the event log.

16 12 Call a Web Service from a Visual Basic 6 Client

Problem

You need to invoke a .NET Web service from a Windows client written in Visual Basic 6.

Solution

Use the SOAP Toolkit, which provides this functionality through an easy-to-use COM library.

Discussion

The SOAP Toolkit includes a COM component that you can use to call any type of Web service that provides a valid Web Services Description Language (WSDL) document. Thus, the SOAP Toolkit supports .NET Web services and Web services created on other platforms. You can download the latest version of the SOAP Toolkit from http://msdn.microsoft.com/library/default.asp?url=/downloads/list/websrv.asp. In Visual Basic 6, you can add a reference to the SOAP Toolkit by selecting Project | References from the menu and adding a check mark next to the Microsoft Soap Type Library item, as shown in Figure 16-7.

Figure 16-7: Adding a reference to the SOAP Toolkit in Visual Basic 6.

To use the SOAP Toolkit, you need to know the location of the WSDL for the service you want to use. You must also know which Web methods the service provides. The SOAP Toolkit dynamically generates a proxy at run time, and it uses late binding to access the proxy methods. Therefore, no runtime checking is performed to ensure that you enter a valid Web method name or supply the right parameters and data types. To determine the available Web methods and correct method signatures, you must read the WSDL or any documentation that is provided with the service.

The following example shows a Visual Basic 6 client that calls the Web service presented in recipe 16.2 to determine the current date and time. In this case, the WSDL document is retrieved directly from the Web server. To improve performance, it's recommended that you save a local copy of the WSDL file and use it to configure the SoapClient object.

' (This is Visual Basic 6 code.) Private Sub Form_Load() ' Create the SoapClient. Dim SoapClient As MSSOAPLib30.SoapClient30 Set SoapClient = New MSSOAPLib30.SoapClient30 ' Use the Init method to generate a proxy Dim WSDLPath As String WSDLPath = "http://localhost/VBCookbookWebServices/Recipe16-2.asmx?WSDL" Call SoapClient.MSSoapInit(WSDLPath) ' Call the GetDate web method to retrieve some information. MsgBox("Server returned: " & SoapClient.GetDate()) End Sub

Chapter 17 Remoting and Enterprise Services