Geeks With Blogs
Molnar Tibor blog

BiztalkWscfClient Tutorial

This tutorial applies for two versions of the BiztalkWscfClient: the one created for Biztalk 2004 and the one created for for Biztalk 2006. In order to understand this article, you should have the knowledge of consuming web services in Biztalk 2004 and/or Biztalk 2006 orchestrations. Also, for walthrough, is required to have installed and to be familiar with the Wscf tool version 0.51 for Biztalk 2004 and version 0.6 for Biztalk 2006(

For reasoning of this tool check out the description.

Before starting the tutorial, download the zip file with the source code and install kits from here, unzip it, then:

  • for Biztalk 2004 please install BiztalkWscfClient (a Visual Studio 2003 add-in) by double clicking on the BizTalkWscfClientSetup.msi install kit which can be found in the BiztalkWscf2004 directory from the zip file.
  • for Biztalk 2006 please install BiztalkWscfClient (a Visual Studio 2005 add-in) with by double clicking on the BizTalkWscfClientSetup.vsi (a  Visual Studio Content Installer kit) which can be found in the BiztalkWscf2006 directory from the zip file.

For both versions of the tool, the files which result from this tutorial can be found in the BiztalkWscfClientTutorial directory, the source code of the tool  can be found in the BizTalkWscfClient directory from the corresponding root directories (BiztalkWscf2004 or BiztalkWscf2006)

What we build

Using this tutorial a web service will be created using contract first approach, then this web service will be consumed by a Biztalk orchestration using the BiztalkWscfClient tool. The web service will have one operation: getCompanyForPerson. All the projects created in this tutorial are added to the same solution for the sake of simplicity. Normaly there should be two solutions: one for the web service and one for  the Biztalk client.

To double check the resulted files throughout the tutorial, you can take a look on the solution from the BizTalkWscfClient directory of the BiztalkWscf2004 or BiztalkWscf2006 directories from the downloaded zip file.

The web service

This part is not directly linked to the BiztalkWscfClient  tool; presents the creation of the web service which will be consumed by Biztalk. The schemas and wsdl files created for the web service will be reused in the Biztalk solution.

Step1: Create the service contract - type/message schemas and wsdl file 

The first step in the contract first development is to create the schemas for the messages. For this tutorial the schemas are already created so no work is required from you:

  • CommonTypes.xsd, contains complex types reused in other complex type definitions
  • Person.xsd, contains the definition of the 'person' type, imports CommonTypes.xsd
  • Company.xsd, contains the definition of the 'company' type, imports CommonTypes.xsd and Person.xsd
  • BiztalkWscfDemoSrvcMsgs.xsd, contains the definition of the messages for the web service, imports Company.xsd and Person.xsd

Step2: Create the web service

In VS2003 create a C# web service project with the url http://localhost/BizTalkWscfDemoService. In VS2005 create a new web service having the location on the  file system (when I tried to create on HTTP on localhost, I received an error due to the fact that web site cannot be created on SharePoint web server). Follow the next steps:

  • delete the default web service created by VisualStudio (Service1.asmx on VS2003, Service.asmx on  VS2005)
  • create a folder in the project with the name 'Schemas'
  • create the CommonTypes.xsd, Person.xsd and Company.xsd files in this project folder, set the content of these files to the schemas from the corresponding links above; in a Visual Stuio, where the Biztalk schema editor is the default one, this can be done by opening the .xsd files by right click -> Open With -> HTML/XML Editor in VS2003, XML Editor in VS2005
  • create a folder in the project with the name 'ServiceContracts'
  • create the BiztalkWscfDemoSrvcMsgs.xsd file in this folder in way similar to the creation of the .xsd files mentioned above 
  • based on the messages definition from BiztalkWscfDemoSrvcMsgs.xsd, create the wsdl file into the 'ServiceContracts' directory using Wscf by right clicking on BiztalkWscfDemoSrvcMsgs.xsd, clicking 'Create WSDL Interface Description...' and going through the wizard. Use http://BizTalkWscfDemoService/BiztalkWscfDemoService for the namespace and 'BiztalkWscfDemoService' for the name of the service for the created wsdl file, check "Infer operations" and "Generate <service> element". The file which should  result can be found here for VS2003 and here for VS2005.

Based on the wsdl file generate the C# classes for complex  types, messages and web service port using Wscf then reorganize the project for better maintainability:  

  • right click the generated BiztalkWscfDemoService.wsdl->Generate Web Service Code, click 'Service-side stub', check 'Public properties', 'Serializable classes', 'Collections'and 'Separate files',  set the service namespace to 'BizTalkWscfDemo.Service', the service name to 'BizTalkWscfDemoService' then click 'Generate' (Wscf 0.6 for VS2005 will generate the classes in the App_Code/BiztalkWscfDemoService directory)
  • in VS2003, optionally, create a folder in the project with name 'Domain', move there Company.cs and Person.cs
  • in VS2003, optionally, create a folder in the project with name 'Messages',move there GetCompanyForPerson.cs and GetCompanyForPersonResponse.cs
  • in VS2003, optionally, move IBiztalkWscfDemoServicePort.cs in the root of the project near BiztalkWscfDemoService.asmx

Implement the only method of the generated web port (BiztalkWscfDemoService.asmx) called GetCompanyForPerson with the next code snippet in the generated BizTalkWscfDemoService.cs file:

Person person = new Person();
person.Email = "";
person.Id = "john.smith";
person.Name = "John Smith";
person.Phone = "12345";

Company company = new Company();
company.ContactPerson = person;
company.Address = "Biztalk Wscf Address";
company.Email = "";
company.Name = "BiztalkWscf";
company.Phone = "1234567";

return new GetCompanyForPersonResponse(company);

If you are developing on  Windows 2003, open the web.config file and put before the <httpModules> tag the next line: <trust level="Full" originUrl="" />. Also if you are developing on Windows 2003 and VS2003, assure in the IIS Manager that anonymous access is allowed to the virtual directory and that the web application is attached to an application  pool having enough rights to run (the default application pool is okay).

Build the solution. If you are in VS2005, start the ASP.Net development server by right clicking the BizTalkWscfDemoService.asmx file and selecting 'View in Browser', please remember the URL displayed in the browser.

Consume the web service in Biztalk

This is the important part for a Biztalk developer, here will the BiztalkWscfClient tool come in role.

Step1:  Create the C# web proxy

Add a C# class library to the solution with the name BiztalkWsfcDemo.Client.WebProxy, then:

  • delete the default class file Class1.cs
  • copy the 'Schemas' and 'ServiceContracts' directories created in the web service project (togheter with the contained .xsd and .wsdl files) to the new project, this can be done using copy & paste directly in Visual Studio
  • using Wscf generate the C# classes for the complex types, the message classes and the web proxy. Do this by right clicking BiztalkWscfDemoService.wsdl->Generate Web Service Code, click 'Client-side proxy', check 'Public properties', 'Serializable classes', 'Collections'and 'Separate files', use 'BiztalkWsfcDemo.Client.WebProxy' for the namespace and with 'BizTalkWscfDemoService' for the proxy filename, then click 'Generate'
  • if you are working with VS2005, open  the generated GetCompanyForPersonResponse.cs and change the line ' [System.Xml.Serialization.XmlTypeAttribute(AnonymousType=true, TypeName= "getCompanyForPersonResponse")]'to' [System.Xml.Serialization.XmlTypeAttribute(Namespace= "http://BizTalkWscfDemoService/BiztalkWscfDemoSrvcMsgs.xsd", TypeName= "getCompanyForPersonResponse")]', the 0.6 version of Wscf for VS2005 has this behaviour (bug?) to generate the message types without namespace
  • optionally, move the generated .cs files to the root of the project for better visibility
  • sign the generated assembly

Step2: Add the web reference to a Biztalk project with BiztalkWscfClient

Add an Empty Biztalk Server Project to the solution with the name  BiztakWscfDemo.Client,  then:

  • copy the 'Schemas' and 'ServiceContracts' directories created in the web service project (togheter with the contained .xsd and .wsdl files) into the biztalk project, those files are the contract of the web service
  • create a new folder called 'WebPorts'
  • right clickon the 'WebPorts' folder, click on the Generate Web Port .odx in this folder', the 'BiztalkWscfClient Web Port Type Generation' dialog appears
  • fill the dialog with the next infomartion:
    • set 'Wsdl File' to the full path of 'BiztalkWscfDemoService.wsdl' (copied in the 'ServiceContracts' directory from the Biztalk project)
    • set 'Messages Namespace' to 'BiztakWscfDemo.Client.ServiceContracts.BiztalkWscfDemoSrvcMsgs'. The Biztalk compiler generates for every schema from  a Biztalk project a .Net class having the base class 'Microsoft.XLANGs.BaseTypes.SchemaBase' from the 'Microsoft.XLANGs.BaseTypes.dll' assembly, those types will be compiled in a namespace which is the path in the project to the schema file concatenated with the schema file name. By setting this value, BiztalkWscfClient will now during the .odx file generation the namespace of the message classes generated basedon the messages from the 'BiztalkWscfDemoSrvcMsgs.xsd' file. 
    • set  'Wsdl Proxy Namespace' to 'BiztalkWsfcDemo.Client.WebProxy', which is the namespace of the generated web proxy created in the previous step.
    • set 'Service URL' to the URL where the web service resides ( 'http://localhost/BizTalkWscfDemoService/BizTalkWscfDemoService.asmx' in the case of  VS2003;  in case of VS2005 we will use the ASP.Net development server, use the URL displayed in  the browser at the end of the Step 2, when you  navigated to the web service). This is not mandatory, but if is not set, after deploying the Biztalk orchestration, the physical port must be created and bound manually to the web ports using the generated web port type
  • click the Generate button, the  'BiztalkWscfDemoService.odx' file containing the created web port type will be generated; close the dialog box
  • add the BiztalkWsfcDemo.Client.WebProxy project to the references of the Biztalk project

Fig.1. The web port type generation dialog filled in with the data required by the tutorial

Step3: Create a test orchestration and call the web service

In this step, we will see in action the web port type created with BiztalkWscfClient:

    • create a new orchestration (suggested name CallBiztalkWscfDemoWebService)
    • create the message 'msgGetCompanyForPersonRequest' of web message type 'BiztakWscfDemo.Client.WebPorts.BiztalkWscfDemoServicePort_.GetCompanyForPerson_request'
    • create another message 'msgGetCompanyForPersonResponse' of web message  type  'BiztakWscfDemo.Client.WebPorts.BiztalkWscfDemoServicePort_.GetCompanyForPerson_response'
    • create a port with the name 'Port_BizTalkWscfDemoService' using the existing  web port type 'BiztakWscfDemo.Client.WebPorts.BiztalkWscfDemoServicePort_.BiztalkWscfDemoServicePort', this is the one generated by the BiztalkWscfClient tool (the port is on the right side Port Surface from the figure below) 
    • create the port 'Port_ReceiveGetCompanyForPerson' (new 'PortType_ReceiveGetCompanyForPerson' web port type, default values in creation wizard), set for 'Message Type' in the Request of the port the web message type  'BiztakWscfDemo.Client.WebPorts.BiztalkWscfDemoServicePort_.GetCompanyForPerson_request'
    • add a receive shape (Activate=true) to receive the 'msgGetCompanyForPersonRequest' message from 'Port_ReceiveGetCompanyForPerson', pass the message to a send shape and send it to the 'Port_BizTalkWscfDemoService' port, then receive the response message from the same 'Port_BizTalkWscfDemoService' port into the 'msgGetCompanyForPersonResponse' message with a receive shape
    • create the 'Port_DumpReceivedCompanyMsg' port (new 'PortType_DumpReceivedCompanyMsg' port type, in creation wizard set to 'I'll always be sending...', the rest is default) to dump (send) the received response; set the message type in the Request of the port the web message type  'BiztakWscfDemo.Client.WebPorts.BiztalkWscfDemoServicePort_.GetCompanyForPerson_response'
    • add a send shape at the end of the orchestration for the 'msgGetCompanyForPersonResponse' message, link it to the 'Port_DumpReceivedCompanyMsg' port
    • sign the assembly generated for the  Biztalk project
    • build and deploy the Biztalk project, put the web proxy assembly created in Step 1 (BiztalkWsfcDemo.Client.WebProxy.dll) in the GAC of the biztalk server (to automate the depoyment process for Biztalk 2004, I'm using Scott Colestock's framework, you can get it from here).
    • for the deployed 'BiztakWscfDemo.Client.CallBiztalkWscfDemoWebService' orchestration bind the 'Port_BizTalkWscfDemoService' and 'Port_DumpReceivedCompanyMsg' ports to physical file ports using the default xml receive and send pipelines; enlist and start the orchestration
    • if you didn't specify the URL during the creation of the web port type, bind also the 'Port_BizTalkWscfDemoService' to a solicit response SOAP send port
    • drop the GetCompanyForPersonMsg.xml message into the receive file location of the 'Port_ReceiveGetCompanyForPerson' port
    • the response will appear in the send file location of the 'Port_DumpReceivedCompanyMsg' port

Fig.2. The orchestration (the trace Expressions were not mentioned in the tutorial)


As you can see on the image below, the schemas used  in the message definition are more manaegable then in the case of regular web references, they can be held in a schema repository - a project folder or a sepparte biztalk project. This way the message type duplication are eliminated. And, might be more important,  the biztalk messages are using exactly the same schemas which were used in the definition  of the web service messages.

It worth mention that in a bigger development project where the C# types and web proxy classes are already generated in an assembly for another .Net projects, that assembly can be shared with the biztalk solution, this way eliminating the 'Create the C# web proxy' step.

Fig.3 The Biztalk project with the type and message schemas, wsdl file, generated web port type BiztalkWscfDemoService.odx and the calling orchestration

The disadvantages are the manual work required in the 'C# web proxy' step, in the case of the regular web reference creation with Visual Studio this is done automatically in compile time. This kind of automation can be done also in the case of the BiztalkWscfClient tool, let me know if you are interested.  Another issue is that 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).

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:14 AM | Back to top

Comments on this post: BiztalkWscfClient Tutorial

# re: BiztalkWscfClient Tutorial
Requesting Gravatar...
Molnar, Nice tool. Have posted a question on the Gotdotnet workspace for this app. Can you have a look at the question and post a reply when you have time.

Left by Benjy on May 16, 2006 11:57 AM

Your comment:
 (will show your gravatar)

Copyright © Molnar Tibor | Powered by: