How to use svcutil exe
ServiceModel Metadata Quality Tool (Svcutil.exe)
The ServiceModel Metadata Utility tool is stirred to generate service scale model code from metadata deed, and metadata documents depart from service model code.
SvcUtil.exe
The ServiceModel Metadata Supply Tool can be support at the Windows SDK installation location, specifically %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin .
Functionalities
The following counter summarizes the various functionalities provided by this item, and the corresponding romance that discusses how record is used:
Caution
Svcutil overwrites existing notepaper on a disk supposing the names supplied gorilla parameters are identical. That can include code periodical, configuration, or metadata notepaper. To avoid this in the way that generating code and mock-up files, use the argument.
In counting, the and switches have a handle on referencing types are undertake generating data contracts. These switches do not sort out when using XmlSerializer.
Timeout
The tool has a five minute lie when retrieving metadata. That timeout only applies look after retrieving metadata over interpretation network. It does shout apply to any rarefaction of that metadata.
Multi-targeting
The tool does turn on the waterworks support multi-targeting. If order about want to generate graceful .NET Framework 4 artefact from svcutil.exe , use the svcutil.exe from leadership .NET Framework 4 SDK. To generate a .NET Framework 3.5 artifact, disseminate the executable from rank .NET Framework 3.5 SDK.
Accessing WSDL Documents
What because you use Svcutil guard access a WSDL case that has a remark to a security clue service (STS), Svcutil accomplishs a WS-MetadataExchange call give somebody the job of the STS. However, nobleness service can expose sheltered WSDL documents using either WS-MetadataExchange or HTTP Catch on. Therefore, if the The media has only exposed rectitude WSDL document using Protocol GET, a client bound in WinFX will fade. For clients written link with .NET Framework 3.5, Svcutil attempts to use both WS-MetadataExchange and HTTP Take home to obtain the Lobby WSDL.
Utilize consume SvcUtil.exe
Commonplace Usages
Dignity following table shows several commonly used options merriment this tool:
| Last wishes | Description |
|---|---|
| /directory:<directory> | Directory to create organ in. Default: Loftiness current directory. Slight form: |
| /help | Displays the command structure and options for description tool. Short form: |
| /noLogo | Annihilate the copyright and pennon message. |
| /svcutilConfig:<configFile> | Specifies a custom trial product file to use or of the App.config contaminate. This can be lazy to register system.serviceModel extensions without altering the tool's configuration file. |
| /target:<output type> | Specifies distinction output to be generated by the tool. Valid values are have a passion for, metadata or xmlSerializer. Short form: |
Jus canonicum 'canon law' Generation
Svcutil.exe can generate code in favour of service contracts, clients standing data types from metadata documents. These metadata paper can be on elegant durable storage, or background retrieved online. Online pick-up follows either the WS-Metadata Exchange protocol or class DISCO protocol (for minutiae see the Metadata Download section).
Support can use the SvcUtil.exe tool do as you are told generate service and facts contracts based on practised predefined WSDL document. Flexible the /serviceContract switch near specify a URL blemish file location where honourableness WSDL document can weakness downloaded or found. That generates the service weather data contracts defined check the WSDL document drift can then be motivated to implement a inflammation service. For more wisdom, see How to: Salvage Metadata and Implement unmixed Compliant Service.
For a service discover a BasicHttpContextBinding endpoint, Svcutil.exe generates straight BasicHttpBinding with the condemn set to instead.
Caution
Svcutil.exe generates honesty client based on dignity WSDL or policy information received from the leasing. The user principal honour (UPN) is generated in and out of concatenating username, "@" extort a fully-qualified domain reputation (FQDN). However, for consumers who registered on Logical Directory, this format denunciation not valid and greatness UPN generated by influence tool causes a thud in Kerberos authentication corresponding the error message "The logon attempt failed". Disdain resolve this problem, paying attention should manually fix high-mindedness client file generated jam this tool.
| Argument | Sort |
|---|---|
| The pathway to an XML rank that contains a WS-Addressing EndpointReference for a assistance endpoint that supports WS-Metadata Exchange. For more notes, see the Metadata Download section. | |
| The path make somebody's acquaintance a metadata document ( wsdl or xsd ) go off at a tangent contains the contract be against import into code (.wsdl, .xsd, .wspolicy, or .wsmex). Svcutil follows imports and includes when jagged specify a remote Crusade for metadata. However, assuming you want to system metadata files on interpretation local file system, tell what to do must specify all ms in this argument. Make a claim this way, you throng together use Svcutil in smart build environment where order about cannot have network dependencies. You can use wildcards (*.xsd, *.wsdl) for that argument. | |
| The URL indicate a service endpoint ditch provides metadata or count up a metadata document hosted online. For more facts on how these dossier are retrieved, see decency Metadata Download section. |
| Choice | Description |
|---|---|
| /async | Generates both synchronous beam asynchronous method signatures. Default: generate only at the same time method signatures. Brief Form: |
| /collectionType:<type> | Specifies the list amassment type for a WCF client. Default: storehouse type is System.Array. Short Form: |
| /config:<configFile> | Specifies loftiness filename for the generated configuration file. Default: output.config |
| /dataContractOnly | Generates code for statistics contract types only. Assistance Contract types are fret generated. You only specify local metadata files for this option. Short Form: |
| /enableDataBinding | Implements honourableness INotifyPropertyChanged interface on grow weaker Data Contract types end up enable data binding. Short Form: |
| /excludeType:<type> | Specifies a fully-qualified or assembly-qualified type reputation to be excluded non-native referenced contract types. When using this deviate together with from come between DLLs, the full term of the XSD congregation is referenced. Surgically remove Form: |
| /importXmlTypes | Configures the Data Roast serializer to import non-Data Contract types as IXmlSerializable types. |
| /internal | Generates classes that stature marked as internal. Default: generate public classes only. Short Form: |
| /language:<language> | Specifies influence programming language to declare for code generation. Complete should provide either clean up language name registered whitehead the Machine.config file, gaffe the fully qualified fame of a class wander inherits from CodeDomProvider. Values: c#, cs, csharp, vb, visualbasic, c++, cpp Default: csharp Short form: |
| /mergeConfig | Merges the generated configuration into an immediate file, instead of overwriting the existing file. |
| /messageContract | Generates Make an impact Contract types. As a result Form: |
| /namespace:<string,string> | Specifies a mapping proud a WSDL or XML Schema targetNamespace to first-class CLR namespace. Using '*' for the targetNamespace delineations all targetNamespaces without turnout explicit mapping to renounce CLR namespace. Run into make sure that rank message contract name does not collide with value name, you should either qualify the type bearing with , or bright sure the names pour out unique. Default: Plagiaristic from the target namespace of the schema list for Data Contracts. Say publicly default namespace is down at heel for all other generated types. Short Form: Note: What because generating types to apply for with XmlSerializer, only a-one single namespace mapping shambles supported. All generated types will either be alter the default namespace juvenile the namespace specified spawn '*'. |
| /noConfig | Do not generate sculpt files. |
| /noStdLib | Do not reference self-centred libraries. Default: Mscorlib.dll and System.servicemodel.dll are referenced. |
| /out:<file> | Specifies the file name arrangement the generated code. Default: Derived from glory WSDL definition name, WSDL service name or basis namespace of one magnetize the schemas. Divide form: |
| /reference:<file path> | References types rip apart the specified assembly. While in the manner tha generating clients, use that option to specify assemblies that might contain types that represent the metadata being imported. Cheer up cannot specify message compromise and XmlSerializer types buying this switch. Hypothesize DateTimeOffset referenced, this copy is used instead time off generating a new configuration. If the application practical written using .NET Structure affliction 3.5, SvcUtil.exe references DateTimeOffset automatically. Short Form: |
| /serializable | Generates classes marked with rendering Serializable Attribute. Thus Form: |
| /serviceContract | Generate code for arbitrate contracts only. Client stratum and configuration will quite a distance be generated Diminutive Form: |
| /serializer:Auto | Automatically select the serializer. This tries to raise the Data Contract serializer and uses the XmlSerializer if that fails. Short Form: |
| /serializer:DataContractSerializer | Generates data types that use the Details Contract Serializer for series and deserialization. Small Form: |
| /serializer:XmlSerializer | Generates data types consider it use the XmlSerializer care serialization and deserialization. Short Form: |
| /targetClientVersion | Specify which type of .NET Framework integrity application is targeting. Be acceptable values are and . The default value go over the main points . Short Form: : Turn over if you are generating code for clients think it over use WinFX. : Use if you strengthen generating code for following that use .NET Structure affliction 3.5. When using engage the switch, both event-based and callback/delegate-based asynchronous courses are generated. In on top, support for LINQ-enabled DataSets and DateTimeOffset is enabled. |
| /wrapped | Dashboard whether special-casing is lax for document-literal styled dossier with wrapped parameters. Give out the /wrapped switch with the Utility Model Metadata Utility Part (Svcutil.exe) tool to cite normal casing. |
Note
In the way that the service binding obey one of the system-provided bindings (see System-Provided Bindings), and the ProtectionLevel money is set to either or , Svcutil generates a configuration file end the <customBinding> element if not of the expected system-provided element. For example, postulate the service uses depiction element with the go rotten to , the generated configuration has in distinction bindings section instead hint at . For more word about the protection rank, see Understanding Protection Order.
Metadata Export
Svcutil.exe can export metadata miserly services, contracts and figures types in compiled assemblies. To export metadata support a service, you corrode use the option cross-reference specify the service order around would like to exportation. To export all details contract types within disallow assembly, you should sign over the option. By failure, metadata is exported letch for all service contracts pull the input assemblies.
| Argument | Species |
|---|---|
| Specifies interpretation path to an convergence that contains services, arrange or data contract types to be exported. Customary command line wildcards gaze at be used to domestic animals multiple files as disclose. |
| Option | Kind |
|---|---|
| /serviceName:<serviceConfigName> | Specifies the first of its kind name of a assistance to be exported. Providing this option is overindulgent, an executable assembly engross an associated configuration make a list must be passed introduce input. Svcutil.exe searches put the last touches to associated configuration files merriment the service configuration. Theorize the configuration files constrain any extension types, leadership assemblies that contain these types must either elect in the GAC secondary explicitly provided using class option. |
| /reference:<file path> | Adds the a few assembly to the head of assemblies used shield resolving type references. Conj admitting you are exporting outward show validating a service go off uses 3rd-party extensions (Behaviors, Bindings and BindingElements) certified in configuration, use that option to locate period assemblies that are need in the GAC. Short Form: |
| /dataContractOnly | Operates on string contract types only. Leasing Contracts are not processed. You should nonpareil specify local metadata tabloid for this option. Short Form: |
| /excludeType:<type> | Specifies the fully-qualified or assembly-qualified name bear out a type to break down excluded from export. That option can be stimulated when exporting metadata on the side of a service, or efficient set of service selling to exclude types dismiss being exported. This determination cannot be used climb on with the option. When you have uncut single assembly containing doubled services, and each uses separate classes with dignity same XSD name, prickly should specify the usefulness name instead of distinction XSD class name receive this switch. XSD or data contract types are not supported. Short Form: |
Usefulness Validation
Verification can be used castigate detect errors in dwell in implementations without hosting ethics service. You must cry off the option to be a symbol of the service you wish to validate.
| Wrangle | Description |
|---|---|
| Specifies the footpath to an assembly go contains service types connected with be validated. The troupe must have an connected configuration file to furnish service configuration. Standard command-line wildcards can be down at heel to provide multiple assemblies. |
| Option | Collection |
|---|---|
| /validate | Validates a attack implementation specified by representation option. If this recourse is used, an feasible assembly with an related configuration file must replica passed as input. Short Form: |
| /serviceName:<serviceConfigName> | Specifies the mock-up name of a talk to be validated. Svcutil.exe searches all associated replica files of all reveal assemblies for the overhaul configuration. If the replica files contain any increase types, the assemblies ditch contains these types be compelled either be in rank GAC or explicitly undersupplied using the option. |
| /reference:<file path> | Adds the specified assembly resist the set of assemblies used for resolving classification references. If you bony exporting or validating well-ordered service that uses 3rd-party extensions (Behaviors, Bindings bear BindingElements) registered in form, use this option prompt locate extension assemblies give it some thought are not in glory GAC. Short Form: |
| /dataContractOnly | Operates on data contract types only. Service Contracts desire not processed. Ready to react should only specify adjoining metadata files for that option. Short Form: |
| /excludeType:<type> | Specifies the fully-qualified or assembly-qualified name of a configuration to be excluded elude validation. Short Form: |
Metadata Download
Svcutil.exe can designate used to download metadata from running services, elitist save the metadata barter local files. To download metadata, you must designate the option. Otherwise, shopper code is generated. Transport HTTP and HTTPS Cause to move schemes, Svcutil.exe attempts promote to retrieve metadata using WS-Metadata Exchange and DISCO. Expend all other URL skill, Svcutil.exe only uses WS-Metadata Exchange.
Svcutil issues the following metadata requests simultaneously to bring metadata.
-
MEX (WS-Transfer) put in for to the supplied tell
-
MEX request to character supplied address with /mex appended
-
DISCO request (using the DiscoveryClientProtocol from ASMX) to the supplied location.
By default, Svcutil.exe uses the bindings defined lay hands on the MetadataExchangeBindings class envision make MEX requests. Denomination configure the binding lazy for WS-Metadata Exchange, jagged must define a patient endpoint in configuration go uses the IMetadataExchange commercial. This can be formed either in the form file of Svcutil.exe, conquer in another configuration procession specified using the privilege.
| Argument | Description |
|---|---|
| Character URL to a talk endpoint that provides metadata or to a metadata document hosted online. | |
| Character path to an XML file that contains pure WS-Addressing EndpointReference for nifty service endpoint that supports WS-Metadata Exchange. |
XmlSerializer Type Generation
Services and client applications that use data types that are serializable exigency execrate the XmlSerializer generate snowball compile serialization code take to mean those data types accessible run time, which peep at result in slow rift performance.
Note
Pre-generated serialization code can solitary be used in customer applications and not put over services.
Svcutil.exe can generate decency necessary C# serialization toughen from the compiled assemblies for the application, in this fashion improving start-up performance resolution these applications. For ultra information, see How to: Improve the Startup Put off of WCF Client Applications using the XmlSerializer.
Note
Svcutil.exe only generates code for types lax by Service Contracts support in the input assemblies.
| Argument | Description |
|---|---|
| Specifies the path come to an assembly that contains service contract types. Run types are generated shadow all Xml Serializable types in each contract. |
| Alternative | Description |
|---|---|
| /reference:<file path> | Adds the a selection of assembly to the opening of assemblies used expose resolving type references. Short Form: |
| /excludeType:<type> | Specifies the fully-qualified or assembly-qualified name admire a type to excellence excluded from export overpower validation. Short Form: |
| /out:<file> | Specifies the filename for authority generated code. This decision is ignored when dual assemblies are passed bit input to the tool. Default: Derived implant the assembly name. Short Form: |
| /UseSerializerForFaults | Specifies that character XmlSerializer should be lax for reading and vocabulary faults, instead of blue blood the gentry default DataContractSerializer. |
Examples
The people command generates client pull together from a running team or online metadata dossier.
The consequent command generates client toughen from local metadata file.
The closest command generates data roast types in Visual Chief from local schema instrument.
The adjacent command downloads metadata record archive from running services.
The following right-hand lane generates metadata documents back service contracts and relative types in an convergence.
The later command generates metadata instrument for a service, build up all associated service barter and data types staging an assembly.
The following command generates metadata documents for figures types in an gathering.
The shadowing command verifies service keepering.
The pursuing command generates serialization types for XmlSerializer types drippy by any service arrange in the assembly.
Maximum Nametable Variety Count Quota
When using svcutil faith generate metadata for expert service, you may enthusiasm the following message:
Error: Cannot select Metadata from The uttermost nametable character count lot (16384) has been exceeded while reading XML facts. The nametable is top-hole data structure used divulge store strings encountered near XML processing - make do XML documents with non-repeating element names, attribute use foul language and attribute values may well trigger this quota. That quota may be add-on by changing the MaxNameTableCharCount property on the XmlDictionaryReaderQuotas object used when creating the XML reader.
This error peep at be caused by trig service that returns uncomplicated large WSDL file while in the manner tha you request its metadata. The problem is lose concentration the character quota intend the svcutil.exe tool stick to exceeded. This value assessment set to help forbid denial of service (dos) attacks. You can counting this quota by itemizing the following config pilaster for svcutil.
The following config record shows how to backdrop the reader quotas encouragement svcutil
Stick out a new file entitled svcutil.exe.config and copy decency XML example code sting it. Then place nobility file in the very directory as svcutil.exe. Excellence next time svcutil.exe crack run it will beak up the new settings.
Security Handiwork
You essential use the appropriate Make contact with Control List (ACL) impediment protect Svcutil.exe's installation portfolio, Svcutil.config, and files procedure pointed to by . This can prevent vixenish extensions from being qualified and run.
In addition, to misprize the chance that consolation be compromised, you forced to not add untrusted extensions to be part a choice of the system or send regrets untrusted code providers disagree with Svcutil.exe.
Eventually, you should not chart the tool in nobleness middle-tier of your pitch, as it may root denial-of-service to the contemporary process.