Geeks With Blogs
Molnar Tibor blog

BiztalkWscfClient Description

In order to understand this article, you should have the knowledge of consuming web services in Biztalk 2004 and/or Biztalk 2006 orchestrations. Also, is recommended to be familiar with the Wscf tool (

To learn to use this tool, check out the tutorial. You can download the tool's install kit, tutorial and source code here.

The problems

To create a webport type, a web reference should be added to a Biztalk Server Project. This creates under the web references folder a new entry for the web reference containing the related .disco and.wsdl files, a generated .odx file containing the designer data and the XLANG description for the new web port type's multipart message types (one for the SOAP request message and one for the SOAP response) and, if complex types from other namespaces (different  then the namespace of the messages ) were imported to define the messages, one .xsd file for each of those namespaces.

So far so good, but imagine the case, when the web service referenced by a Biztalk Server Project was created with the contract first approach (manually or using a tool like Wscf): first the messages were defined using different complex schemas referencing one another, then the wsdl file was generated, then the implementation classes were generated based on the wsdl file. What could happen is that the schemas created by Visual Studio (and used as message types in the web port type definition) during adding the web reference are slighlty different then the original schemas. For example 'xs:restriction' and 'xs:all' will be replaced with the base type of the restriction (xs:string for example) respectivelly with 'xs:sequence', the 'maxoccures' attribute value other then 'unbounded' will be replaced with 'unbounded'. Even if we add the web reference using the wsdl file generated by Wscf with the referenced message schema and the possible imported type schemas (which are the first things created in the contract first development process, the messages schema is imported din the wsdl file using xsd:import), new schemas will be created for the Biztalk message types by the web reference creation process under the node, the differences mentioned above still will be there.

Another thing is that if we use different web references from different web services which are sharing the same complex types, the message types will be duplicated between different web service references. There is a possibility that in a Biztalk solution there are multiple orchestrations referencing web services which shares a common messages and type schema repository; wouldn't be nice if we would just get all those schemas and reusing in the Biztalk solution once without replicating parts of that repository in web references.

Fig 1.  Example of a web reference added in a regular way  to a Biztalk project. Reference.xsd, Reference1.xsd and Reference2.xsd duplicates the contetnt of the Person.xsd, Company.xsd and BiztalkWscfDemoSrvcMsgs.xsd, the content of CommonTypes.xsd is ignored because contains only restrictions (these schemas can be found in the tutorial)

Let's summarise the issues we might have: 

  • the schemas used for the Biztalk message types can be different from the original schemas used to define the web service messages
  • possible type definition duplication between web service references
  • the referenced schemas might be better organized in a central repository

The idea

During the compilation of an orchestration which has a web reference, wsdl.exe is used to generate in compile time the code for the web port and the .Net classes used for receiving/sending the Biztalk messages, those classes are mapped to the biztalk message types created by compiling the schemas which can be found under the node.

 Let's create a schema repository with the exact type and message schemas created at the beginning of the consumed  web services development and create our web port types using as message types directly the types defined in those schemas!

This can be done by generating (based on the wsdl file created by Wscf) the .odx file containing the  web port type and, in this generated file, mapping the message types and web port type defined in this .odx file to the C# classes and web port generated by Wscf, this way getting rid of wsdl.exe.

The tool: BiztalkWscfClient

 The BiztalkWscfClient tool is a Visual Studio add-in (has two versions: for VS2003/Biztalk2004 and VS2005/Biztalk2006) and can be used to add web service references to a Biztalk project through the next steps:

  • Step1: Wscf is used to create, based on given xml message schemas (which might include recursively arbitrary number of schemas), the wsdl file of a web service (all these files are the contract of the web service) and then the C# classes corresponding to the messages and the xml types used by these messages, the web service proxy; these classes will be included into a normal class library. This step corresponds form the regular web refernce creation process to the execution of wsdl.exe in compile time and could be automated in the same way, another alternative is that the assembly might be received from the creators of the web service due to the fact that anyway exists an updated central repository of the Wscf generated C# messages and web port classes.
  • Step2: the xml schemas used in the previuos step are included in a Biztalk project in order to give the possibility to the Biztalk project compiler to compile them to C#  types, this could be the schema repository for the Biztalk solution, can be created even by source control sharing if we are in the same team with the guys developing the referenced web service 
  • Step3: in the biztalk project, which will contain the web reference and which references the projects created or reused in Step1 and Step2,  BizTalkWscf Client is used to create the web port type .odx file by right clicking on the directory which will contain that file. The next parameters shoul be provided:
    • the full path to the wsdl file (by navigating to that file)
    • the namespace of the schemas from the project created in Step2
    • the namespace of the web service proxy port created in Step1
    • the url of the service, this is optional, can be set later after deploying the assemblies

BizTalkWscfClient will generate the odx file containing the web port type togheter with the message types corresponding to the referenced web service.


Advantages using this tool:

  • Biztalk will use for the message types exactly the same schemas which were used to define the web service messages for the development of the web service, this way the messages will be correctly validated
  • The organisation of the Biztalk Server Projects is match more clear
  • Message type duplications are eliminated

Disadvantages using this tool:

  • The step of creating the C# web port should be done manually. I would be happy to automate it if somebody is interested. Also, it worth mention that in a project where those types are already generated in an assembly for another projects, that assembly can be shared with the biztalk solution.
  • The message schemas should be copied in two locations: the web proxy project and the biztalk  project, the first one can be eliminated if we automate the generation of the web proxy (see above). Also, this step might be infrequent if we integrate a stable web service or the sachemas can be shared in source control if we are in the same project with the guys creating the web services.

Fig 2.  Example of a web reference added to a Biztalk project using the BiztalkWscfClient tool. The generated BiztalkWscfDemoService.odx web port type file references the message types defined in the BiztalkWscfDemoSrvcMsgs.xsd schema, no intermediary schemas are used. The files are much better organized then in Fig.1

Who created this tool

My name is Molnar Tibor, I'm working for iQuest Tehnologies, a Romania-based outsourcing IT company with more then 150 employee.

Copyright © 2006 Molnar Tibor. All rights reserved.


You may not distribute this software in any form without express written permission. Please use this blog to report any problems, provide feedback or raise queries.

Posted on Wednesday, February 8, 2006 5:03 AM | Back to top

Comments on this post: BiztalkWscfClient Description

# re: BiztalkWscfClient Description
Requesting Gravatar...
Great Post, most helpful,
Left by Don Whiteside on Sep 19, 2007 10:41 PM

# re: BiztalkWscfClient Description
Requesting Gravatar...
I think this is a great tool. Using it for the first time and running into 1 error. When building my BizTalk 2004 solution, I get a compile error on the generated web port odx. It says it "expected '{'. I'm not familiar with how an odx is generated, but I'm looking at the code and I don't know what the error is. Can you help me?
Left by Edith Russo on Feb 04, 2008 7:33 AM

# re: BiztalkWscfClient Description
Requesting Gravatar...
hi, with MS shutting down GotDotNet, where can i download this ?. tried googling it, but can't find anywhere to download it ?
Left by Chats on Feb 26, 2008 5:15 PM

Your comment:
 (will show your gravatar)

Copyright © Molnar Tibor | Powered by: