Generating WCF/WebService proxy class using SvcUtil.exe

Introduction

This article  prepared based on my recent explorations on creating generic WCF/WebService proxy class using SvcUtil.exe tool which is part of .NET Framework Runtime. SvcUtil.exe helps me in creating a single Proxy Stub class for my WCF/web service, which can be directly reused in any project when necessary, without the need to Add Web Reference or Add Service Reference through the Visual Studio 2010 solution explorer.

ServiceModel Metadata Utility Tool (Svcutil.exe)

The ServiceModel Metadata Utility tool is used to generate service model code from metadata documents and metadata documents from service model code. The ServiceModel Metadata Utility Tool can be found at the Windows SDK installation location, specifically, C:Program FilesMicrosoft SDKsWindowsv6.0Bin.

Svcutil.exe generates the client based on the WSDL or policy file received from the service.

Usage Syntax :

svcutil /t:code http://<service_url>/out:<file_name>.cs /config:<file_name>.config

Options Reference :

Option	Description
/config:<configFile>	Specifies the filename for the generated configuration file.Default: output.config
/language:<language>	Specifies the programming language to use for code generation. You should provide either a language name registered in the Machine.config file, or the fully-qualified name of a class that inherits from CodeDomProvider.Values: c#, cs, csharp, vb, visualbasic, c++, cpp Default: csharp Short form: /l
/mergeConfig	Merges the generated configuration into an existing file, instead of overwriting the existing file.
/messageContract	Generates Message Contract types.Short Form: /mc
/namespace:<string,string>	Specifies a mapping from a WSDL or XML Schema targetNamespace to a CLR namespace. Using ‘*’ for the targetNamespace maps all targetNamespaces without an explicit mapping to that CLR namespace.To make sure that the message contract name does not collide with operation name, you should either qualify the type reference with ::, or make sure the names are unique. Default: Derived from the target namespace of the schema document for Data Contracts. The default namespace is used for all other generated types. Short Form: /n
/out:<file>	Specifies the file name for the generated code.Default: Derived from the WSDL definition name, WSDL service name or target namespace of one of the schemas. Short form: /o
/serializable	Generates classes marked with the Serializable Attribute.Short Form: /s
/targetClientVersion	Specify which version of .NET Framework the application is targetting. Valid values are Version30 and Version35. The default value is Version30.Short Form: /tcv Version30: Use /tcv:Version30 if you are generating code for clients that use .NET Framework 3.0. Version35: Use /tcv:Version35 if you are generating code for clients that use .NET Framework 3.5.
/reference:<file path>	References types in the specified assembly. When generating clients, use this option to specify assemblies that might contain types that represent the metadata being imported.Short Form: /r

more on the usage refer to http://msdn.microsoft.com/en-us/library/aa347733.aspx

A Simple Example:

I have an ASP.NET Web Service hosted on one of my domains.

I wanted to created Proxy Stub class from my WSDL url. So I used the following command in “Visual Studio Command Prompt”

svcutil /out:P:BookSearchSvcRefStub.cs http://dotnetcook.com/BookSearch.asmx?WSDL /config:P:BookSearch.config

And the command Generated the  files…

P:BookSearchSvcRefStub.cs -> C#  Code of Proxy Stub class

P:BookSearch.config -> Service Model configuration settings are saved to BookSearch.config

I just included the BookSearchSvcRefStub.cs in my project and made necessary changes to the namespace to meet with the name space of my class library or project. Copied the necessary *.config entries to my solution. Voila!! my code is ready to work.

Conclusion

When you add a Web Reference or Service Reference to a Visual Studio project by right clicking on the solution explorer on Visual Studio, Visual Studio internally input the above svcutil.exe command to generate Proxy class and emits  output to your Visual Studio project itself and configuration entries will be updated to your project App.config or Web.config.

But in some certain scenarios we do not want to depend on Visual Studio to add Service Reference, to make sure we will not include any unnecessary entries created by Visual Studio. This will make sure we do not alter the Service proxy code accidently, just like sometimes we do using “Update Service References”, which updates the proxy class contents to latest version downloaded from the Service Uri and we might breaking existing code base.  Also if we made any customization to the Proxy class and all the changes will be over written when Service Reference are updated. To avoid such incidents it’s better we generate Proxy Stub classes and reuse it where ever necessary.

There are more interesting commands you can use it with SvcUtil.exe to generate metadata or proxy code from a Web/WCF Service URL in C# or VB.NET.

Refer to http://msdn.microsoft.com/en-us/library/aa347733.aspx for more details.

Hope this helps.