Generating a C# Client Binding

CAA Web Services Home		Generating a C# Client Binding How to use WSDL and XSD definitions to generate C# client bindings for CAA Web services
Technical Article

Abstract

This article introduces the .NET Framework Web Services support and explains how to use the Web Services Description Language Tool (wsdl.exe) in order to generate C# client bindings for CAA Web services. These bindings can be used to create client applications that interact with CAA Web services.

.NET Framework Web Services Overview
Officially Certified Release
Step-by-step
In Short
References

.NET Framework Web Services Overview

The .NET Framework natively provides support to build Web services, as well as to consume them. In the context of CAA Web services, only the client side feature of the .NET Framework is required:

Buildtime: the .NET Framework SDK ships with a tool named Web Services Description Language Tool (wsdl.exe). It can be used to generate a C# client binding (or proxy class) based on the WSDL and XSD definitions of a CAA Web service,
Runtime: using the .NET Framework runtime, the generated C# client binding handles the work of sending and receiving SOAP messages to the target CAA Web service implementation. The SOAP network endpoint URI describing a deployed implementation of the CAA Web service is set on the generated C# proxy class.

Note: If you have already installed Microsoft Visual Studio .NET 2003, you do not need to install the .NET Framework SDK separately. Visual Studio .NET 2003 includes the SDK.

The wsdl.exe tool shipped with the .NET Framework 1.1 suffers from a limitation. It does not support WSDL documents containing WS-I conformance claims, even though the use of the related XML elements are officially documented in the WS-I Basic Profile [1]. As a consequence, if you try to generate a C# proxy using the wsdl.exe tool using one of the CAA Web services WSDL documents, it will issue an error. Fortunately, this particular wsdl.exe issue has been fixed with .NET Framework 1.1 Service Pack 1. As a consequence, this level is the offical minimal prerequisite when trying to generate a C# proxy for CAA Web services.

Without Service Pack 1, the workaround would consist in the following steps:

Retrieve the WSDL interface document describing the CAA Web service you wish to consume and save it to your local file system,
Retrieve all of the XSD referenced by the WSDL interface document and save them at the same location,
Update the relative paths contained in the wsdl:types section of the WSDL interface document so that it directly references the locally available XSD files,
Remove the wsdl:documentation element contained in the WSDL interface document. It can be done manually or using a tool. For example, you can download the DeDoc tool available on the GotDotNet Web site [2]. It automatically removes WSDL elements that contain children (e.g. WS-I conformance claims) allowing wsdl.exe to consume these WSDL documents.

The sample WSDL document below highlights the WS-I conformance claims which is contained in the wsdl:documentation element and that must be removed:

<?xml version="1.0" encoding="UTF-8" ?>

            <definitions [...]>

              [...]

              <binding [...]>

                <documentation>

                  <wsi:Claim conformsTo="http://ws-i.org/profiles/basic/1.0">

                </documentation>

                [...]

              </binding>

            </definitions>

You can refer to the .NET Framework documentation for further details on Web services related topics. See [3] for access to some accurate links on the MSDN Web site.

[Top]

Officially Certified Release

The term "certified" is intended to describe the fact that a given .NET Framework release has been successfully tested and validated in order to consume CAA Web services. As of now, the certified release requires:

Microsoft .NET Framework 1.1 + Software Development Kit + Service Pack 1.

[Top]

Step-by-step

Before using wsdl.exe to create the C# proxy, it is important to get an understanding of some of the concepts that are related to the WSDL documents describing the available CAA Web services. See [4] for an overview of these concepts.

Generating the C# Client Binding
Overview of the Generated Code

[Top]

Generating the C# Client Binding

As detailed in the following section, there is not much difference between using either the WSDL interface document or the WSDL implementation document as input of the wsdl.exe tool (unlike what can be observed with the Axis WSDL2Java compiler for example). There are several ways available to access these WSDL documents:

Retrieving WSDL interface documents from the file system: all of the WSDL interface documents are available from the runtime view of every product that provides CAA Web services. You can refer to [5] in order to determine the exact location of the WSDL interface document describing the CAA Web services you wish to consume,
Retrieveing WSDL interface documents from a remote location: once a product has been deployed as a web application on a target application server, you can use the file servlet to access all of the files delivered in the runtime view. You can refer to [5] for the description of the URI scheme providing access to each available WSDL interface document,
Retrieveing WSDL implementation documents from a remote location: once a product has been deployed as a web application on a target application server, you can use the wsdl servlet to dynamically generate the content of the WSDL implementation documents. These files are not physically delivered in the file system, because they contain deployment specific information. You can refer to [6] for the description of the URI scheme providing access to each available WSDL implementation document.

The remote location approaches are typically useful if you do not have access to the file system of the product installation (for example, it may be the case for security considerations).

In order to use the wsdl.exe tool, you need to open up a command prompt. Click on Start -> Run and then type cmd. From the prompt, browse to the \Bin directory of your .NET Framework 1.1 SDK installation. By default, it is located in the C:\Program Files\Microsoft.NET\SDK\v1.1\Bin directory. For details on the wsdl.exe tool options, you can issue the following command: wsdl /?.

You are now ready to invoke the wsdl.exe tool, providing as input the WSDL document describing the CAA Web service you wish to consume:

wsdl /namespace:<Namespace> /out:<Filename>
            <WSDL-document>

<Namespace>: the namespace for the generated C# proxy class,
<Filename>: the filename of the generated C# proxy class,
<WSDL-document>: the path or URI of the input WSDL document (as explained above).

When the WSDL document is accessed from a remote location using the HTTP protocol, it may be required to set security settings for the wsdl.exe tool. This is typically the case when the remote server is secured using Basic Authentication. In such case, you need to provide two extra parameters:

wsdl /namespace:<Namespace> /out:<Filename>
            /username:<Username> /password:<Password>
            <WSDL-document>

<Username>, <Password>: valid set of credentials for Basic Authentication.

Upon successful invocation, you should receive the following message at the command prompt: Writing file 'XXX.cs', where XXX is the name of the file provided as input of the wsdl.exe tool:

Fig.1: Generating the C# Client Binding

[Top]

Overview of the Generated Code

The wsdl.exe tool always generates a single source file for each WSDL document used as input, no matter its type (WSDL interface document versus WSDL implementation document). The generated file contains a proxy class that defines both synchronous and asynchronous methods for each operation defined in the WSDL document. For example, when the IApplicationBinder.wsdl WSDL interface document defines the getUserContexts operation, wsdl.exe generates the following methods: bindToApplication, BeginbindToApplication and EndbindToApplication. The first method can be used to interact with the target CAA Web service synchronously, and the other ones can be used to interact with it asynchronously.

The wsdl.exe tool generates almost the exact source code when using the WSDL interface document as input than when using the WSDL implementation document. The only differences are:

WSDL implementation document: the name of the C# proxy class constructor is computed from the value of the name attribute of the wsdl:service element. In the constructor body, the Url property is set and is computed from the value of the location attribute of the soap:address element.

The code below provides a sample of the generated code when using as input the WSDL implementation document describing the ENOPosApplicationBinderImpl CAA Web service implementation:

namespace com.dassault_systemes.caaplmsecurity.caaenoposappbinderdotnet1_1clientbase.enoposapplicationbinderimpl {

              ...

              [System.Diagnostics.DebuggerStepThroughAttribute()]

              [System.ComponentModel.DesignerCategoryAttribute("code")]

              [System.Web.Services.WebServiceBindingAttribute(
                Name="IApplicationBinderBinding", 
                Namespace="urn:com:dassault_systemes:ENOPosWS:ENOPos_ws:IApplicationBinder")]

              public class ENOPosApplicationBinderImpl : System.Web.Services.Protocols.SoapHttpClientProtocol {

              

                public ENOPosApplicationBinderImpl() {

                  this.Url = "http://karindsy.dsy.ds:9081/LCAB17D49/servicerouter?service=urn!com!dassault_syst" +

                    "emes!ENOPosWS!ENOPosAppliBinder!ENOPosApplicationBinderImpl";

                }

              }

            }

WSDL interface document: the name of the constructor is computed from the value of the wsdl:portType element. The Url property is not set inside the constructor.

The code below provides a sample of the generated code when using as input the WSDL interface document describing the IApplicationBinder CAA Web service interface:

namespace com.dassault_systemes.caaplmsecurity.caaenoposappbinderdotnet1_1clientbase.enoposapplicationbinderimpl {

              ...

              [System.Diagnostics.DebuggerStepThroughAttribute()]

              [System.ComponentModel.DesignerCategoryAttribute("code")]

              [System.Web.Services.WebServiceBindingAttribute(
                Name="IApplicationBinderBinding", 
                Namespace="urn:com:dassault_systemes:ENOPosWS:ENOPos_ws:IApplicationBinder")]

              public class IApplicationBinderBinding : System.Web.Services.Protocols.SoapHttpClientProtocol {

              

                public IApplicationBinderBinding() {

                }

              }

            }

Aside from the proxy class itself, wsdl.exe also generates the type mapping between XML structures and C# objects. For every complexType element defined in the XSD referenced by a given WSDL interface document, wsdl.exe generates the corresponding C# class in the same namespace than the C# proxy one. The XSD types are directly mapped to .NET types when available. The example below describes how a given complexType referenced in the IApplicationBinder.wsdl file is mapped to its corresponding C# equivalent:

Complex type definition defined in PPRGenericWS.xsd:

<xsd:complexType name="Identifier">

              <xsd:sequence>

                <xsd:element minOccurs="1" maxOccurs="1" form="qualified" name="Identifier" nillable="true" type="xsd:base64Binary" />

                <xsd:element minOccurs="1" maxOccurs="1" form="qualified" name="Location" nillable="true" type="xsd:string" />

              </xsd:sequence>

            </xsd:complexType>

Corresponding C# class generated by wsdl.exe:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="urn:com:dassault_systemes:PPRGenericWS")]

            public class Identifier {

              [System.Xml.Serialization.XmlElementAttribute("Identifier", DataType="base64Binary", IsNullable=true)]

              public System.Byte[] Identifier1;

            

              [System.Xml.Serialization.XmlElementAttribute(IsNullable=true)]

              public string Location;

            }

[Top]

In Short

A C# client binding (or proxy class) can be generated for CAA Web services using the Web Services Description Language Tool (wsdl.exe). You must use apply the Service Pack 1 to your Microsoft .NET Framework 1.1 + SDK installation in order to avoid the issue of the wsdl.exe tool that fails to understand WS-I conformance claims contained in the WSDL interface documents describing the available CAA Web services.

The generated C# client binding can be used to consume the related CAA Web service implementations that have been deployed on a target application server. For more details, please refer to the use cases describing how to consume the CAA Web services you wish to use.

[Top]

References

[1]	WS-I Basic Profile 1.0
[2]	DeDoc Tool
[3]	.NET Framework Developer's Guide
[4]	CAA Web Services and WSDL Definitions
[5]	WSDL Interface Documents
[6]	WSDL Implementation Documents

History

Version: 1 [Jan 2006]	Document created
[Top]

CAA Web Services Home