ServiceModel Metadata Utility Tool (Svcutil.exe)

Article
07/03/2007

The ServiceModel Metadata Utility tool is used to generate service model code from metadata documents and metadata documents from service model code.

Remarks

The ServiceModel Metadata Utility Tool can be found at the Windows SDK installation location, specifically, C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin

The tool has a 5 minute timeout when retrieving metadata. This timeout only applies to retrieving metadata over the network. It does not apply to any processing of that metadata.

The following table summarizes the various functionalities provided by this tool and the corresponding topic that discusses how it is used.

Task	Topic
Generates code from running services or static metadata documents.	Generating a WCF Client from Service Metadata
Exports metadata documents from compiled code.	How to: Use Svcutil.exe to Export Metadata from Compiled Service Code
Validates compiled service code.	How to: Use Svcutil.exe to Validate Compiled Service Code
Downloads metadata documents from running services.	How to: Download Metadata Documents from a Running Service
Generates serialization code.	How to: Use Svcutil.exe to Generate Serialization Code

Caution:
Svcutil will overwrite existing files on a disk if the names supplied as parameters are identical. This can include code files, configuration or metadata files. To avoid this when generating code and configuration flies, use the /mergeConfig switch. In addition, the /r and /ct switches for referencing types are for generating data contracts. These switches do not work when using XmlSerializer.

Svcutil will overwrite existing files on a disk if the names supplied as parameters are identical. This can include code files, configuration or metadata files. To avoid this when generating code and configuration flies, use the /mergeConfig switch.

In addition, the /r and /ct switches for referencing types are for generating data contracts. These switches do not work when using XmlSerializer.

Common usages

The following table shows some commonly used options for this tool.

Option	Description
/directory:<directory>	Directory to create files in. Default: The current directory. Short form: /d
/help	Displays the command syntax and options for the tool. Short form: /?
/noLogo	Suppress the copyright and banner message.
/svcutilConfig:<configFile>	Specifies a custom configuration file to use instead of the App.config file. This can be used to register system.serviceModel extensions without altering the tool's configuration file.
/target:<output type>	Specifies the output to be generated by the tool. Valid values are code, metadata or xmlSerializer. Short form: /t

Code Generation

Svcutil.exe can generate code for service contracts, clients and data types from metadata documents. These metadata documents can be on a durable storage, or be retrieved online. Online retrieval follows either the WS-Metadata Exchange protocol or the DISCO protocol (for details see the Metadata Download section).

Caution:
Svcutil.exe generates the client based on the WSDL or policy file received from the service. The user principal name (UPN) is generated by concatenating username, "@" and a fully-qualified domain name (FQDN). However, for users who registered on Active Directory, this format is not valid and the UPN generated by the tool causes a failure in Kerberos authentication with the error message "The logon attempt failed". To resolve this problem, you should manually fix the client file generated by this tool.

Svcutil.exe generates the client based on the WSDL or policy file received from the service. The user principal name (UPN) is generated by concatenating username, "@" and a fully-qualified domain name (FQDN). However, for users who registered on Active Directory, this format is not valid and the UPN generated by the tool causes a failure in Kerberos authentication with the error message "The logon attempt failed". To resolve this problem, you should manually fix the client file generated by this tool.

svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>

Argument	Description
Epr	The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange. For more information, see the Metadata Download section.
metadataDocumentPath	The path to a metadata document (wsdl or xsd) that contains the contract to import into code (.wsdl, .xsd, .wspolicy or .wsmex). Svcutil follows imports and includes when you specify a remote URL for metadata. However, if you want to process metadata files on the local file system, you must specify all files in this argument. In this way, you can use Svcutil in a build environment where you cannot have network dependencies. You can use wildcards (e.g., .xsd, .wsdl) for this argument.
url	The URL to a service endpoint that provides metadata or to a metadata document hosted online. For more information on how these documents are retrieved, see the Metadata Download section.

Epr

The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange. For more information, see the Metadata Download section.

metadataDocumentPath

The path to a metadata document (wsdl or xsd) that contains the contract to import into code (.wsdl, .xsd, .wspolicy or .wsmex).

Svcutil follows imports and includes when you specify a remote URL for metadata. However, if you want to process metadata files on the local file system, you must specify all files in this argument. In this way, you can use Svcutil in a build environment where you cannot have network dependencies. You can use wildcards (e.g., *.xsd, *.wsdl) for this argument.

url

The URL to a service endpoint that provides metadata or to a metadata document hosted online. For more information on how these documents are retrieved, see the Metadata Download section.

/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

/config:<configFile>

Specifies the filename for the generated configuration file.

Default: output.config

/mergeConfig

Merges the generated configuration into an existing file, instead of overwriting the existing file.

/noConfig

Do not generate configuration files.

/dataContractOnly

Generates code for data contract types only. Service Contract types are generated.

You should only specify local metadata files for this option.

Short Form: /dconly

/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

Note:
The switch only supports C++ for the code provider that ships with Visual Studio 2005 SP1.

/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

/messageContract

Generates Message Contract types.

Short Form: /mc

/enableDataBinding

Implements the INotifyPropertyChanged interface on all Data Contract types to enable data binding.

Short Form: /edb

/serializable

Generates classes marked with the Serializable Attribute.

Short Form: /s

/async

Generates both synchronous and asynchronous method signatures.

Default: generate only synchronous method signatures.

Short Form: /a

/internal

Generates classes that are marked as internal. Default: generate public classes only.

Short Form: /i

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

You cannot specify message contracts and XmlSerializer types using this switch.

Short Form: /r

/excludeType:<type>

Specifies a fully-qualified or assembly-qualified type name to be excluded from referenced contract types.

When using this switch together with /r from separate DLLs, the full name of the XSD class is referenced.

Short Form: /et

/collectionType:<type>

Specifies a fully-qualified or assembly-qualified name of the type to be used as a collection data type, when code is generated from schemas.

Short Form: /ct

/noStdLib

Do not reference standard libraries.

Default: Mscorlib.dll and System.servicemodel.dll are referenced.

/serializer:Auto

Automatically selects the serializer. This uses the Data Contract serializer. If this fails, the XmlSerializer is used.

Short Form: /ser:Auto

/serializer:DataContractSerializer

Generates data types that use the Data Contract Serializer for serialization and deserialization.

Short Form: /ser:DataContractSerializer

/serializer:XmlSerializer

Generates data types that use the XmlSerializer for serialization and deserialization.

Short Form: /ser:XmlSerializer

/importXmlTypes

Configures the Data Contract serializer to import non-Data Contract types as IXmlSerializable types.

Note:
When the service binding is one of the system-provided bindings (see System-Provided Bindings), and the ProtectionLevel property is set to either None or Sign, Svcutil generates a configuration file using the <customBinding> element instead of the expected system-provided element. For example, if the service uses the <wsHttpBinding> element with the ProtectionLevel set to Sign, the generated configuration has <customBinding> in the bindings section instead of <wsHttpBinding>. For more information about the protection level, see Understanding Protection Level.

When the service binding is one of the system-provided bindings (see System-Provided Bindings), and the ProtectionLevel property is set to either None or Sign, Svcutil generates a configuration file using the <customBinding> element instead of the expected system-provided element. For example, if the service uses the <wsHttpBinding> element with the ProtectionLevel set to Sign, the generated configuration has <customBinding> in the bindings section instead of <wsHttpBinding>. For more information about the protection level, see Understanding Protection Level.

Metadata Export

Svcutil.exe can export metadata for services, contracts and data types in compiled assemblies. To export metadata for a service, you must use the /serviceName option to specify the service you would like to export. To export all data contract types within an assembly, you should use the /dataContractOnly option. By default, metadata is exported for all service contracts in the input assemblies.

svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*

Argument	Description
assemblyPath	Specifies the path to an assembly that contains services, contracts or data contract types to be exported. Standard command line wildcards can be used to provide multiple files as input.

Option	Description
/serviceName:<serviceConfigName>	Specifies the configuration name of a service to be exported. If this option is used, an executable assembly with an associated configuration file must be passed as input. Svcutil.exe searches all associated configuration files for the service configuration. If the configuration files contain any extension types, the assemblies that contain these types must either be in the GAC or explicitly provided using the /reference option.
/reference:<file path>	Adds the specified assembly to the set of assemblies used for resolving type references. If you are exporting or validating a service that uses 3rd-party extensions (Behaviors, Bindings and BindingElements) registered in configuration, use this option to locate extension assemblies that are not in the GAC. Short Form: /r
/dataContractOnly	Operates on data contract types only. Service Contracts are not processed. You should only specify local metadata files for this option. Short Form: /dconly
/excludeType:<type>	Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export. This option can be used when exporting metadata for a service, or a set of service contracts to exclude types from being exported. This option cannot be used together with the /dconly option. When you have a single assembly containing multiple services, and each uses separate classes with the same XSD name, you should specify the service name instead of the XSD class name for this switch. XSD or data contract types are not supported. Short Form: /et

Service Validation

Validation can be used to detect errors in service implementations without hosting the service. You must use the /serviceName option to indicate the service you want to validate.

svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*

Argument	Description
assemblyPath	Specifies the path to an assembly that contains service types to be validated. The assembly must have an associated configuration file to provide service configuration. Standard command-line wildcards can be used to provide multiple assemblies.

Option	Description
/validate	Validates a service implementation specified by the /serviceName option. If this option is used, an executable assembly with an associated configuration file must be passed as input. Short Form: /v
/serviceName:<serviceConfigName>	Specifies the configuration name of a service to be validated. Svcutil.exe searches all associated configuration files of all input assemblies for the service configuration. If the configuration files contain any extension types, the assemblies that contains these types must either be in the GAC or explicitly provided using the /reference option.
/reference:<file path>	Adds the specified assembly to the set of assemblies used for resolving type references. If you are exporting or validating a service that uses 3rd-party extensions (Behaviors, Bindings and BindingElements) registered in configuration, use this option to locate extension assemblies that are not in the GAC. Short Form: /r
/dataContractOnly	Operates on data contract types only. Service Contracts are not processed. You should only specify local metadata files for this option. Short Form: /dconly
/excludeType:<type>	Specifies the fully-qualified or assembly-qualified name of a type to be excluded from validation. Short Form: /et

Metadata Download

Svcutil.exe can be used to download metadata from running services, and save the metadata to local files. To download metadata, you must specify the /t:metadata option. Otherwise, client code is generated. For HTTP and HTTPS URL schemes, Svcutil.exe attempts to retrieve metadata using WS-Metadata Exchange and DISCO. For all other URL schemes, Svcutil.exe only uses WS-Metadata Exchange.

Svcutil issues the following metadata requests simultaneously to retrieve metadata.

MEX (WS-Transfer) request to the supplied address
MEX request to the supplied address with /mex appended
DISCO request (using the DiscoveryClientProtocol from ASMX) to the supplied address.

By default, Svcutil.exe uses the bindings defined in the MetadataExchangeBindings class to make MEX requests. To configure the binding used for WS-Metadata Exchange, you must define a client endpoint in configuration that uses the IMetadataExchange contract. This can be defined either in the configuration file of Svcutil.exe, or in another configuration file specified using the /svcutilConfig option.

svcutil.exe /t:metadata <url>* | <epr>

Argument	Description
url	The URL to a service endpoint that provides metadata or to a metadata document hosted online.
epr	The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange.

XmlSerializer Type Generation

Svcutil.exe can generate C# serialization code that is required for types that can be serialized using XmlSerializer. Svcutil.exe only generates code for types used by Service Contracts found in the input assemblies.

svcutil.exe /t:xmlSerializer <assemblyPath>*

Argument	Description
assemblyPath	Specifies the path to an assembly that contains service contract types. Serialization types are generated for all Xml Serializable types in each contract.

Option	Description
/reference:<file path>	Adds the specified assembly to the set of assemblies used for resolving type references. Short Form: /r
/excludeType:<type>	Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export or validation. Short Form: /et
/out:<file>	Specifies the filename for the generated code. This option is ignored when multiple assemblies are passed as input to the tool. Default: Derived from the assembly name. Short Form: /o

/reference:<file path>

Adds the specified assembly to the set of assemblies used for resolving type references.

Short Form: /r

/excludeType:<type>

Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export or validation.

Short Form: /et

/out:<file>

Specifies the filename for the generated code. This option is ignored when multiple assemblies are passed as input to the tool.

Default: Derived from the assembly name.

Short Form: /o

Examples

The following command generates client code from a running service or online metadata documents.

svcutil http://service/metadataEndpoint

The following command generates client code from local metadata documents.

svcutil *.wsdl *.xsd /language:C#

The following command generates data contract types in Visual Basic from local schema documents.

svcutil /dconly *.xsd /language:VB

The following command downloads metadata documents from running services.

svcutil /t:metadata http://service/metadataEndpoint

The following command generates metadata documents for service contracts and associated types in an assembly.

svcutil myAssembly.dll

The following command generates metadata documents for a service, and all associated service contracts and data types in an assembly.

svcutil myServiceHost.exe /serviceName:myServiceName

The following command generates metadata documents for data types in an assembly.

svcutil myServiceHost.exe /dconly

The following command verifies service hosting.

svcutil /validate /serviceName:myServiceName myServiceHost.exe

The following command generates serialization types for XmlSerializer types used by any service contracts in the assembly.

svcutil /t:xmlserializer myContractLibrary.exe

Security Concerns

You should use the appropriate Access Control List (ACL) to protect Svcutil.exe's installation folder, Svcutil.config, and files being pointed to by /svcutilConfig. This can prevent malicious extensions from being registered and run.

In addition, to minimize the chance that security be compromised, you should not add untrusted extensions to be part of the system, or use untrusted code providers with Svcutil.exe.

Finally, you should not use the tool in the middle-tier of your application, as it may cause denial-of-service to the current process.