Getting Started: Creating a WSE 3.0 Enabled Web Service to Transfer Large Amount

Published: 6/11/2007
By: Muhammad Mosa

In this article we will see how to create a WSE 3.0 enabled web service to transfer large amount of data using SOAP Message Transmission Optimization Mechanism a.k.a MTOM.

Introduction

In this article we will see how to create a WSE 3.0 enabled web service to transfer large amount of data using SOAP Message Transmission Optimization Mechanism a.k.a MTOM. This article will discuss the following:

Prerequisites

In order to follow this article the followings are required:

Note: I recommend when installing WSE 3.0 to install the whole package with documentation for later reference.

Creating a basic Web Service

The web service we are going to create is very simple. It will contain two methods:

The following steps describe how to create an ASP.NET Web Service using VS.NET 2005, if you are familiar with this, jump to the next section “Implement Web Service Methods”:

Step 1

From Visual Studio.Net 2005 File menu select New/Web Site.

Step 2

From New Web Site dialog select ASP.NET Web Service under Visual Studio Installed Templates.

Step 3

For Location select HTTP from the combo box, and type http://localhost/DocumentLibraryService on the text box.

Step 4

For the language select Visual C# and click OK.

Figure 1: New Web Site Dialog

New Web Site

Step 5

By default a file named Service.asmx is created. Delete this file and Service.cs which can be found in the App_Code folder. We will create another one.

Step 6

Right click on the project http://localhost/DocumentLibraryService and select Add New Item from the context menu.

Step 7

From Add New Item dialog select Web Service item and Name it DocumentLibraryService.asmx. Select C# as your language and make sure that the Place code in separate file option is checked and click Add.

Figure 2: Add New Item Dialog

Add New Item

The above steps are the basic steps to create an ASP.NET Web Service.

Implement the Web Service Methods

Bellow you’ll see the implementation of the UploadDocument and DownloadDocument web service methods. They are very simple and straight forward. I assumed this service will only serve documents within a folder named “documents” on the server

The UploadDocument(string, byte[]) Method

This method is responsible for file uploading, it accepts two parameters, the file name which is just the name with the extension and the file binary data as byte array. Of course this method will be marked as a Web Method using the WebMethod attribute.

Listing 1: UploadDocument Method

DownloadDocument(string) Method:

This method is responsible for downloading a file from the server. It accepts only one parameter which is the file name - just the name with extension. This method returns a byte array which represents the binary data of the downloaded document.

Listing 2: DownloadDocument Method

Configuring the Web Service to use WSE 3.0:

Step 1

Right click on the web service project http://localhost/DocumentLibraryService and select WSE Settings 3.0… from the context menu.

Step 2

From the displayed dialog and on General tab select the Enable this project for Web Services Enhancements check box and Enable Microsoft Web Services Enhancement Soap Protocol Factory check box and click OK.

Figure 3: WSE 3.0 Configuration tool, General Tab

WSE 3.0 Configuration tool

Step 3

Open your web.config and review the changes made by the WSE 3.0 configuration tool. You’ll notice the following:

How To: Enable a Web Service to Send and Receive Large Amounts of Data:

Again we will use WSE 3.0 configuration too to enable Web Service to send and receive large amounts of data.

Step 1

Right click on the web service project http://localhost/DocumentLibraryService and select WSE Settings 3.0… from the context menu

Step 2

From the displayed dialog select Messaging tab

Step 3

On MTOM Settings ensure that Server Mode is set to optional and click OK.

Figure 4: WSE 3.0 Configuration tool, Messaging Tab (MTOM Settings)

MTOM Settings

Let’s discuss the Server Mode option; this is a setting for the Web Service that will interact with large data. Available options are: optional, always and never.

Note: Later we will see how to enable client application to use MTOM by configuration and by code.

Again open the web.config file and review the changes made by the WSE 3.0 configuration tool. You’ll notice the following:

Create a simple client application

In this section we will create a simple client application (windows application console) to consume the web service for uploading and downloading documents. This client application will be very basic; the goal is to show how to consume a web service and to gain benefit of WSE 3.0 with MTOM. Below is a screenshot from the simple client application. I’ve created the client application project in the same solution.

Figure 5: Client application

Client Application

I’m assuming that you do the job of building a similar Windows Form that consists of the 3 textboxes and 3 buttons as the following:

Adding the Web Reference for the Document Library Web Service to the Client Application

To consume a web service you’ll need to have a reference to that web server. By using VS.NET 2005 we will add a reference to the web service we have just built. This will create a proxy class to ease the web service consuming to the client application.

To add a reference to a web service follow these steps:

Step 1

Right click on the client application project and select Add Web Reference from the context menu. The following Web Reference dialog will appear.

Figure 6: Add Web Reference Dialog

Add Web Reference

Step 2

From the Add Web Reference dialog, for the purpose of this article click Web services in this solution link. The screen will load the available web services on the current working solution, in our case it will be DocumentLibraryService.

Figure 7: Add Web Reference Dialog and the Web Services in the Current Solution List

Web Services In Current Solution List

Step 3

Click on DocumentLibraryService link. Wait till the form loads and on the Web reference name type DocLibSvc and click Add Reference.

Figure 8: Add Web Reference Dialog and define the Web Reference name in the Solution List

Define Web Reference Name

The web reference is added to the client application under the Web References folder. It’s time to have a look on the generated web service proxy class. To do that, from the Solution Explorer select your windows client project and click Show All Files.

Figure 9: Web Reference

Solution Explorer

Double click on the Reference.cs as this is where the proxy class is generated. After reviewing the file you’ll notice the following:

The main difference between the two proxy classes is the base class. When using the DocumentLibraryServiceWse class the base class Microsoft.Web.Services3.WebServicesClientProtocol provide features of WSE 3.0 like the RequireMtom property which we will use later to enable the client to send MTOM encoded messages.

Configuring the client application to use WSE 3.0

We’ll have to configure the client application to use WSE 3.0 too. To do that follow these steps.

  1. Right click on the windows client project and select WSE Settings 3.0 from the context menu
  2. From the displayed dialog and on General tab select the Enable this project for Web Services Enhancements check box and click OK

This will modify the app.config file of the client application. It will define a configuration section for <microsoft.web.services3>. You can use this configuration section to pre configure client application to use MTOM.

Consuming the web service

Now it is time to write the code that will consume the web service through the client application. Below is the code to upload a document using DocumentLibraryServiceWse.

Listing 7: Invoke UploadDocument Method

Note that the DocumentLibraryServiceWse.RequireMtom is set to true. If you didn’t set this property to true the web service will not use MTOM.

The code for downloading a document will use the same concept.

Listing 8: Invoke DownloadDocument Method

MTOM Settings Client Mode Options vs Server Mode Options

In the MTOM Settings on the WSE 3.0 Configuration tool you must have noticed that there is a Client Mode option. This option is only applicable for clients that access web services. The Client Mode option has only two values, On and Off. The default option is Off. In fact these options maps to the RequireMtom property. So if your client mode option is Off and you wish to use MTOM, all you need to do is to set RequireMtom property to true and vice versa.

If the Server Mode is set to always, the Client Mode must be On or you must set the RequireMtom to true before each request. And if the Server Mode is set to never, the Client Mode must be Off or you must set RequireMtom to false. In the case the Server Mode is optional you’ll need to decide what needs to be set for the RequireMtom to true or false.

What else I can do?

The WSE 3.0 Configuration tool has the option to enable message trace for diagnostics. You can set this option and select the path on which input and output file will be placed. An important thing to note is that you need to set the security for the selected paths to enable the IIS process to access these paths and write to them.

Figure 10: WSE 3.0 Configuration, Diagnostics

Diagnostics settings

When you wish to transfer really huge amount of data which exceed 4 MB you’ll need to configure the Web server to handle the larger amount of data. This can be done by increasing the ASP.NET limits on the maximum size of request and the maximum number of seconds that a request is allowed to execute by adding the <httpruntime> configuration element to the web service application's web.config file as well as increasing the WSE limit on the maximum size of SOAP messages using the <maxmessagelength> Element.

Listing 10: Increase max request limit to 400MB and request timeout to 5 minutes

Listing 11: Configure WSE 3.0 send and receive the largest possible SOAP messages

Conclusion

The client application could be a web application and it will be treated the same way. It is known that using WSE 3.0 MTOM is very efficient for transferring huge amount of data over HTTP. You can also host your web service outside IIS and consume it over TCP in this case all messages are encoded as MTOM.

Downloads

Please visit the link at the below url for any additional user comments.

Original Url: http://dotnetslackers.com/articles/aspnet/GettingStartedCreatingWSEEnabledWebService.aspx