Published: 11 Jun 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:

  • How to configure a web service to use WSE 3.0
  • How to configure a client application to use WSE 3.0
  • How to configure a web service to use MTOM messaging mechanism
  • How to enable a client application to use MTOM while communicating with a MTOM enabled web service

Prerequisites

In order to follow this article the followings are required:

  • VS.NET 2005 using C#
  • Familiar with windows client application
  • Web Services Enhancement 3.0 (download) installed
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:

  • UploadDocument(string, byte[]) - receives a byte array and file name to be upload to the web server
  • DownloadDocument(string) - receives a file name to be downloaded and return a byte array of the desired file

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:

  • A new configuration section is added microsoft.web.services3
  • A reference to the Microsoft.Web.Services3 assembly is added
  • Under the system.web element, the <webServices> configuration element is defined. Here the Web service is configured to use the Microsoft Web Services Enhancement Soap Protocol factory WseProtocolFactory which is defined by the <soapServerProtocolFactory> configuration element under the <webServices> element. This is a must for a web service to be able to use WSE 3.0.
    Note: The type attribute of the <soapServerProtocolFactory> Element must be on one line, even though the following example shows it split across multiple lines for readability

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.

  • The optional mode is the default settings. In this mode the WSE processes the incoming SOAP messages whether or not they are MTOM encoded. This gives much more flexibility to web services that are not only dealing with large amount of data. With optional the client is the one who decide whether to use MTOM or not, if the client application request to use MTOM the web service will use MTOM.
  • In always mode all incoming and outgoing SOAP messages must be MTOM encoded. When a SOAP request is received that is not encoded using MTOM, an HTTP error 415: "Media unsupported" is returned to the sender. This option is ideal for Web Services that only deal with large amount of data.
  • In never mode all incoming SOAP messages must not be MTOM encoded. When a SOAP request is received that is encoded using MTOM, an HTTP error 415: "Media unsupported" is returned to the sender. That means the client application should never use MTOM.
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:

  • A <messaging> configuration element is defined under the <microsoft.web.services3> configuration. This is used to specify the MTOM options.

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:

  • The Button will be used to open the OpenFileDialog to browse for a local file to upload.
  • The TextBox is used to display the path of the local file system you wish to upload through the web service.
  • Another TextBox will be used to define the name of the file that will be used to save the file on the server.
  • Another Button is used to Upload, this will invoke the web service’s UploadDocument Method.
  • A third TextBox is used to define the file name that will be downloaded from the server through the web service.
  • The last Button will be used to download, this will invoke the web service’s DownloadDocument method.

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:

  • Two Proxy classes are generated:
    1. DocumentLibraryService: this is the proxy class that does not use WSE 3.0. It inherits from the System.Web.Services.Protocols.SoapHttpClientProtocol class.
    2. DocumentLibraryServiceWse: this is the proxy class that makes use of WSE 3.0. It inherits from the Microsoft.Web.Services3.WebServicesClientProtocol class.

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

<<  Previous Article Continue reading and see our next or previous articles Next Article >>

About Muhammad Mosa

Sorry, no bio is available

This author has published 8 articles on DotNetSlackers. View other articles or the complete profile here.

Other articles in this category


Code First Approach using Entity Framework 4.1, Inversion of Control, Unity Framework, Repository and Unit of Work Patterns, and MVC3 Razor View
A detailed introduction about the code first approach using Entity Framework 4.1, Inversion of Contr...
jQuery Mobile ListView
In this article, we're going to look at what JQuery Mobile uses to represent lists, and how capable ...
Exception Handling and .Net (A practical approach)
Error Handling has always been crucial for an application in a number of ways. It may affect the exe...
JQuery Mobile Widgets Overview
An overview of widgets in jQuery Mobile.
Book Review: SignalR: Real-time Application Development
A book review of SignalR by Simone.
Top
 
 
 

Discussion


Subject Author Date
placeholder Enable MTOM, force MTOM = true ??? Al Mic 8/31/2009 8:02 AM
Good Post Kazi Manzur Rashid 6/13/2007 8:59 AM
placeholder Can not find the Add-In on the context Menu. Himanshu Shukla 6/9/2008 3:27 AM
RE: Can not find the Add-In on the context Menu. Muhammad Mosa 6/24/2008 3:49 AM
placeholder Webservcie and Proxy has WSE and non-WSE Class!? Sascha Folville 6/23/2008 9:00 AM
Re: placeholder Webservcie and Proxy has WSE and non-WSE Class!? Muhammad Mosa 6/24/2008 3:42 AM
placeholder Can not find Reference.map and Reference.cs files Mahalakshmi Sethu 7/30/2008 6:38 AM
RE: Can not find Reference.map and Reference.cs files Muhammad Mosa 7/30/2008 8:14 AM
placeholder RE: RE: Can not find Reference.map and Reference.cs files Mahalakshmi Sethu 8/6/2008 3:32 AM
RE: RE: RE: Can not find Reference.map and Reference.cs files Muhammad Mosa 8/6/2008 5:12 AM
placeholder RE: Can not find Reference.map and Reference.cs files Mahalakshmi Sethu 8/7/2008 8:23 AM
RE: RE: Can not find Reference.map and Reference.cs files Muhammad Mosa 8/7/2008 12:48 PM
placeholder RE: Can not find Reference.map and Reference.cs files Mahalakshmi Sethu 8/8/2008 5:46 AM
RE: RE: Can not find Reference.map and Reference.cs files Muhammad Mosa 8/7/2008 12:50 PM
placeholder can't see Refresnce.map and refrence.cs Shruti Kanda 8/7/2008 12:11 PM
Refresnce.map and refrence.cs Shruti Kanda 8/7/2008 2:22 PM
placeholder RE: Refresnce.map and refrence.cs Muhammad Mosa 8/7/2008 3:00 PM

Please login to rate or to leave a comment.