Configure DIME with WSE 2.0

• Download source files - 30.6 Kb
• Download demo project - 9.68 Kb

Introduction

SOAP messages are not the best way to send large binary files. As the Web Services emerge, people look for Web services to have more and more functionality. Result was the introduction of Web Services Enhancement (WSE) 2.0. The Web Services Enhancements for Microsoft .NET (WSE) supports attaching files to SOAP messages outside the SOAP envelope; these files are not serialized as XML. This can be beneficial when sending large text or binary files because XML serialization is a very costly process and can result in files much larger than the originals. Direct Internet Message Encapsulation (DIME) is a lightweight, binary message format that WSE uses to encapsulate SOAP messages and their attachments in a DIME message.

Background

• First, we create a Web service that can read an image file, and return a DIME message that contains a SOAP message and the image file attached.
• Second, we create a Windows Forms client that can consume the DIME message created by the Web service and display the image.

Requirements

The users who read this article need a basic understanding of Web services and how to create and use them with .NET Framework. Additionally, they need to have the Microsoft Visual Studio .NET 2003 and Web Service Enhancement 2.0 installed.

Web service that generates a DIME message containing image attachments

Note: Because DIME attachments are contained outside of the SOAP envelope, they cannot be signed or encrypted using WSE. It is strongly recommended that all SOAP messages that contain DIME attachments be sent over a secure transport protocol such as HTTPS.

Note: If you send a file as a DIME attachment, you cannot close or delete the file from within the Web method that sent the file. This is because WSE holds a reference to the file until the message is serialized and delivered to the client. To overcome this, override a file stream and delete the file when all references to the file stream are released.

Let's create the Visual Studio ASP/.NET Web service project:

1. Go to File menu and create a New Project.
2. In the Project Types pane, select Visual C# Projects.
3. In the Templates pane, select ASP.NET Web Service.
4. Fill the Location box with the project name: http://localhost/MyDimeTest.
5. Click OK button to add the MyDimeTest project to the solution.
6. Go to Solution Explorer and change the name of Service1.asmx to DimeService.asmx by selecting the Properties of the file.
7. To be smarter, view the DimeService.asmx and change the class name as well as the constructor name to have the same name, i.e., "DimeService".

   Now the project is done, and now you got to configure the project for WSE 2.0. It is very easy.

8. In the Solution Explorer, right click on the project name, you will see "WSE 2.0 Settings ..." just below the "Property" menu item.
9. Select "WSE 2.0 Settings ...".
10. To configure a Web service project to use WSE 2.0, you got to check both check boxes in the "General" tab.

    

    • The first check box enables the use of the current project with WSE. This means that the Microsoft.Web.Services2.dll will be added to the project references, and that changes will be made to the Web.config file to add support for the WSE configuration handler. In addition, any Web references that are created from this point on will include WSE 2.0 support in the proxy classes generated.
    • The second check box is only enabled if this is an ASP.NET Web Service project. By selecting it, the WSE Soap Extension is added to the project, which will enable the additional protocol support to work within the ASP.NET Web service HTTP handler (for .ASMX files). This is accomplished by modifying the Web.config file and adding the WSE SOAP Extension to the list of .asmx SOAP Extensions for the virtual directory.
11. Add using statement to the DimeService.asmx.cs file:

    using Microsoft.Web.Services2.Dime;
    using Microsoft.Web.Services2;
    using System.Net;

12. Place an image file to be read by the DimeService. In my case, I placed a "test.gif" file in my "c:" drive. So the path of the image file is described as "c:\test.gif".
13. Write a Web Method that can read the image file and attach it with the SOAP message using DIME technology and transfer it to the client end. Please follow the code below:

    // The CreateDimedImage Web service returns an image in a DIME
    
    // attachment.
    
    [WebMethod]
    public void CreateDimedImage()
    {
        SoapContext respContext = ResponseSoapContext.Current;
        DimeAttachment dimeAttach = new DimeAttachment(
            "image/gif", TypeFormat.MediaType,
            "C:\\test.gif");
        respContext.Attachments.Add(dimeAttach);
    }

    Compile the project. Now you are done with the Web service end.

Windows Forms client that can consume a DIME message containing an image

Let's create the Windows Forms Project:

1. Go to File menu and create a New Project.
2. In the Project Types pane, select Visual C# Projects.
3. In the Templates pane, select Windows Application.
4. Fill the Name box with the project name: DimeClient.
5. Click OK button to add the DimeClient project to the solution.
6. In Solution Explorer, select View Designer for DimeClient Windows Form.
7. Add a PictureBox control to the form from the Tool Bar.
8. Double click on the DimeClient Form to add the Form_Load event.

   Now the client project is done, and now you got to configure the project for WSE 2.0. It is very easy.

9. In the Solution Explorer, right click on the project name, you will see "WSE 2.0 Settings ..." just below the "Property" menu item.
10. Select "WSE 2.0 Settings ...".
11. To configure a Web service project to use WSE 2.0, you got to check the first check box in the "General" tab. (I.e., enable this project for Web Service enhancements.) This will add all necessary references as well as it will edit the Web.Config for you.
12. In Solution Explorer, right-click References, and then select Add Web Reference.
13. In the address window, enter http://localhost/MyDimeTest/DimeService.asmx, and then click the arrow icon.
14. Name your proxy class as "pxy" and click Add Reference.
15. Insert the code below in the "Form_Load" method of the "DimeClient.cs".

    private void Form1_Load(object sender, System.EventArgs e)
    {
        pxy.DimeServiceWse lobjProxy = new pxy.DimeServiceWse();
        lobjProxy.CreateDimedImage();
        if (lobjProxy.ResponseSoapContext.Attachments.Count == 1)
        {
            this.pictureBox1.Image = new Bitmap(
                        lobjProxy.ResponseSoapContext.Attachments[0].Stream);
        }
        else
        {
            MessageBox.Show("No Attachment Found");
        }
    }

DIME Defaults

By default, DIME/ WSE 2.0 doesn't allow adding/sending attachments larger than 4096 KB of size. If you intend to send larger files, which are over the 4 MB limit (including the SOAP message), you need to add some tags to the web.config file of the service as well as, remember, of the receiver (client) end. You need to add values to override the values of the maxRequestLengths.

<httpRuntime> Settings

This configures the ASP.NET HTTP runtime settings. This section can be declared at the machine, site, application, and subdirectory levels:

<httpRuntime useFullyQualifiedRedirectUrl="true|false"
  maxRequestLength="size in kbytes"
  executionTimeout="seconds" />

Example

This example demonstrates a instant of sending an attachment of size 8 MB and the timeout is set to 45 seconds:

<configuration>
   <system.web>
      <httpRuntime maxRequestLength="8000"
                   useFullyQualifiedRedirectUrl="true"
                   executionTimeout="45" />
    </system.web>
</configuration>

<microsoft.web.services2> Settings

<microsoft.web.services2>
    <messaging>
      <maxRequestLength>"size in kbytes"</maxRequestLength>
    </messaging>
    <diagnostics />
</microsoft.web.services2>

Example

<configuration>
  <microsoft.web.services2>
    <messaging>
      <maxRequestLength>8000</maxRequestLength>
    </messaging>
    <diagnostics />
  </microsoft.web.services2>
</configuration>

Last Updated

The article was updated on 19^th of April 2005.