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 Files\Microsoft SDKs\Windowsv6.0\Bin.

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 :

OptionDescription
/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

/mergeConfigMerges the generated configuration into an existing file, instead of overwriting the existing file.
/messageContractGenerates 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

/serializableGenerates classes marked with the Serializable Attribute.Short Form: /s
/targetClientVersionSpecify 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.

12 Comments

  1. Pingback: Tweets that mention Generating WCF/WebService proxy class using SvcUtil.exe » Code Name "NitRiX Reloaded" -- Topsy.com

  2. Hi,
    Thanks for providing useful information of creating proxy.I am having one issue over creating proxy of serializable class. Actually, there are some data contracts and some of them are serializable classes(Microsoft.synchronization).I want to make use of these serializable classes in client side using proxy class to connect to server.
    could you please help me?
    Thanks & Regards,
    -Sharada

  3. Hi Sharada,

    Generate Proxy stub classes and include them in your client application.

    When you generate proxy by pointing to a WSDL of a Service, it automatically creates Proxy STUBS(base classes/dummy classes) matching the signature of all the Data contracts mentioned in your WSDL/Service.

    You might have to slightly adjust or import name space references by metioning name space of these classes.

    I hope this clarifies your doubt and is helpful for you.

    Thanks

    Nithin

  4. Hi,

    Thanks for the article. How do you add the svcutil command directly in the visual studio. When I right client and add service reference, I don’t see a place when I can add this command.

    Thanks,
    Seshu.

  5. Seshu,
    Visual Studio automatically uses (svcutil.exe) internally to generate necessary files when you use “Add Service References”.

    To control how our Stubs are created, the SVCUtil can be used by us to generate Stubs based on our need and include the generated files to your visual studio project/solution.

    Each time when you use “Add Service References”, visual studio does it for you by calling “Svcutil.exe” by using internal commands.

    Hope that clarifies your question.

  6. I don’t think we can do that.

    What you can do in this case is either connect to that address in a browser and just download and save the WSDL file to your local disk and call svcutil.exe on that local copy – or ask the publisher of that webservice to either give you an URL which doesn’t require authentication, or to simply send you the relevant WSDL and possibly XSD files so you can create a client side proxy for that service.

    Concluding: Based on references on the discussion on Stackoverflow.
    http://stackoverflow.com/questions/2693394/passing-username-and-password-to-svcutil-exe

  7. I have generated and added the config file and .vb file to the solution , now how to create an object to access the methods of the service.. I mean i am not able to find the namespace in the generated file… …

  8. Hi Amit,

    By default – the generated code file might not have a namespace defined in vb, so you can manually specify your code block in a namespace – in your generated vb file and refer the class and methods using that namespace.

Other times, you're doing some piece of work and suddenly you get feedback that tells you that you have touched something that is very alive in the cosmos. Share your feedback on this blog, it will help me improve it a lot..