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
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”:
From Visual Studio.Net 2005 File menu select New/Web Site.
From New Web Site dialog select ASP.NET Web Service under Visual Studio Installed Templates.
For Location select HTTP from the combo box, and type http://localhost/DocumentLibraryService on the text box.
For the language select
Visual C# and click OK.
Figure 1: New Web Site Dialog
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.
Right click on the project http://localhost/DocumentLibraryService and select Add New Item from the context menu.
From Add New Item dialog select Web Service item and Name it
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
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
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
Listing 1: UploadDocument 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:
Right click on the web service project http://localhost/DocumentLibraryService and select WSE Settings 3.0… from the context menu.
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
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.
Right click on the web service project http://localhost/DocumentLibraryService and select WSE Settings 3.0… from the context menu
From the displayed dialog select Messaging tab
MTOM Settings ensure that Server Mode is set to optional and click OK.
Figure 4: WSE 3.0 Configuration tool, Messaging Tab (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 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
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.
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
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:
<messaging> configuration element is defined under the
<microsoft.web.services3> configuration. This is used to specify the
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
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:
Button will be used to open the
OpenFileDialog to browse for a local file to upload.
TextBox is used to display the path of the local file system you wish to upload through the web service.
TextBox will be used to define the name of the file that will be used to save the file on the server.
Button is used to Upload, this will invoke the web service’s
- 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
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:
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
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
Figure 7: Add Web Reference Dialog and the Web Services in the Current Solution List
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
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
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:
DocumentLibraryService: this is the proxy class that does not use WSE 3.0. It inherits from the
DocumentLibraryServiceWse: this is the proxy class that makes use of WSE 3.0. It inherits from the
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.
- Right click on the windows client project and select WSE Settings 3.0 from the context menu
- 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
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
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
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
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,
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
true before each request. And if the Server Mode is set to
never, the Client Mode must be
Off or you must set
false. In the case the Server Mode is
optional you’ll need to decide what needs to be set for the
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
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
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
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