How do we use wscf.lightblue?

This is what we landed on in a large SOA project:
  • Put shared types into common data conctracts (e.g. org.Common.XSD)
  • Common types may be restricted types, enums and entity types such as Customer, Order, etc. used by many services
  • Define headers in a separate contract, e.g. Common.Headers.XSD
  • Generate code for common data conctracts and build a shared assembly (e.g. org.Common.Contracts.dll)
  • For each web service application:
    • Design web services Contract-First, start with a schema (e.g. Myservice.XSD)
    • Import org.Common.XSD and use common types from that namespace
    • In the service project, create a reference to the shared assembly (e.g. org.Common.Contracts.dll)
    • Use wscf.lightblue to generate a service description file from the contract (e.g. MyService.WSDL)
    • Import header schema and specify Request/Response headers
    • Use wscf.lightblue to generate WCF code from MyService.WSDL, reusing types from org.Common.Contracts.dll

For an introduction to Contract-First WCF service development, see this MSDN article: http://msdn.microsoft.com/en-us/magazine/ee335699.aspx.

Check out this presentation to see our Contract-First process: https://docs.google.com/viewer?a=v&pid=explorer&chrome=true&srcid=0ByaI0UwHkc-pZmIyYTY2ODUtYWNkMi00ZTY4LTlhN2EtMzRiNGYxNmUyMmRl&hl=en_US.

Getting Started : Create Your First XML Schema

If you want a quick start to your first XML schema (XSD - file), right-click a project in Visual Studio and click the Create XML Schema command from the wscf.lightblue submenu. Enter a schema name of your choice or use the default name, HelloWorld:

createxmlschema.png

wscf.lightblue will create an XML schema for a Hello World service with one method: Hello().

Generating the WSDL file from XSD

In Visual Studios Solution Explorer, select an XML schema (an XSD file) and click the Generate WSDL from Schema command from the wscf.lightblue submenu.:

wscf.lightblue.wsdl.png

Metadata file(s): Initialized to selected item in Visual Studio.
Service name: Name og the service
Infer operations pattern: This pattern will be used to infer operations from element tags in the XSD contract. Initialized to Request;Response. This means that elemnt pairs containing the text Request ad Response will be defined as a two-way operation in the WSDL, eg. GetPersonRequest / GetPersonResponse.
Import schema(s): Specify XSD(s) that contains headers types and faults if any.
Request element: Element used as SOAP header for all operation requests.
Response element: Element used as SOAP header for all operation responses.
Fault element: Element used as SOAP fault for all operations.
Destination file name: Generated WSDL file
Destination namespace: Target namespace in WSDL.

In wscf.lightblue you can only specify 1 set of request / response SOAP headers which will be added to all operations.
This will work nicely for 99% of our projects since we use Operational Management tools such as SOA Software or SO-Aware to deal with security headers.
So for our intents and purposes, one set of headers will do just fine.
If you need more a complex SOAP header configuration, you can use WSCF.blue.

Generation WCF C# code from the WSDL

In Visual Studios Solution Explorer, select a Web Service Descritpion (WSDL file) and click the Generate WCF Code from contract command from the wscf.lightblue submenu.:

wscf.lightblue.png

Metadata files: Set to selected item in Visual Studio. Can be multiple files separated with spaces and filenames with wildcards, see documentation for SvcUtil.exe.
Data contracts only: Only generate code for data contracts, not service interface and client proxy. Mandatory if selected item has extension .XSD.
Reuse types in referenced assemblies: Don't generate code for types found in referenced assemblies. Select all referenced assemblies or sepcified.
Destination file name: Generated code file. Inferred from service name in contract if left blank.
Destination namespace: CLR namespace. Inferred from XML target namespace in contract if left blank.

Command Line Code Generator Tool wscf.exe

wscf.lighblue also ships with a command line utility: %ProgramFiles%\Capgemini\wscf.lightblue\wscf.exe.
This is handy for build scripts. In large SOA projects, you may want to periodically gather all contracts and build corresponding assemblies with WCF code implemenatation.
This gives you a contract cache and an assembly cache that can be referenced from service consumer applications.
Example usage:

wscf.exe /m:MyService.WSDL /n:*,wscf /r:org.Common.Contracts.dll /o:MyService.cs

The arguments are very similar to the arguments used for SvcUtil.exe with one important difference:
SvcUtil.exe needs all imported metadata files (WSDL and XSDs) as parameters. wscf.exe only needs the WSDL, it will figure out what other metadata files are needed for itself.

If you want to see what goes on under the hood, wscf.exe produces a command file called wscf.lightblue.CodeGenerator.GenerateCode.cmd.
In here you can see the command issued to SvcUtil.exe.

Command Line Contract First Build Tool cfbuild.exe

This command line tool will copy WSDL and XSD files from a folder hierarchy and generate code and assemblies for eacg WSDL.

Usage: cfbuild options

Options:

/rootDirectory (/r): The path to the root folder of the projects structure that
contains service contracts.
Contracts will be copied to contractsDirectory and service assemblies will be ge
nerated for each WSDL file.

/contractsDirectory (/c): Drop folder for service contracts. Deafult: ".\Contrac
ts"

/searchPatterns (/s): List of search patterns separated by semicolon. Default: "
.wsdl;.xsd"

/excludeFolders (/e): List of folders to exclude in search for contracts separat
ed by semicolon. Default: "Web References;Service References"

/projectsToBuild (/p): List of projects or Visual Studio solutions that must be
built in addtion to service assemblies. Separated by semicolon.

/referencedAssemblies (/f): List of assemblies to refence when generating servic
e code and building service assemblies. Separated by semicolon.

/assembliesFolder (/a): Service assemblies drop folder

/continueOnError: Continue on error. Default: false

/rebuild: Clean contract and assembly folders and rebuild all. Default: false

/configuration (/g): Build configuration Release/Debug. Default: Release

Example:

cfbuild /r:..\.. /c:..\Contracts /s:.wsdl;xsd /p:..\Common\Common.csproj;..\Da
ta\Data.csproj;..\Parameter\Parameter.csproj /a:..\Assemblies /f:Common.dll;Data.dll;Parameter.dll

ScvUtil Bugfix

wscf.lightblue alters the code generated by SvcUtil.
The argument ReplyAction="*" is removed from OperationContract attributes.
The asterix causes problems when using the code to set up a web server, it leads to publishing metadata with empty service contract (with no operations in it).
There is a detailed explanation here: http://shishkin.wordpress.com/2007/03/21/wcf-actions-asterisk-and-metadata/
There may or may not be a good reasons for ReplyAction="*", I haven't had time to investigate - but to make a long story short: Remove it, and everything works just fine!

Looking ahead

I have no plans for extending wscf.lightblue with new features. I want to keep it the simplest Contract-First tool for Visual Studio that could possibly work.
Any bugs you report will be fixed ASAP.
If I get ambitious, I'll try to figure out how to converge wscf.lightblue with WSCF.blue.

Last edited Feb 4, 2012 at 4:19 PM by henrik_thomsen, version 15

Comments

No comments yet.