ServiceModel metadata utility (Svcutil.exe)

ServiceModel metadata utility is used to generate service model code based on metadata documents and metadata documents based on service model code.

I,SvcUtil.exe

The ServiceModel metadata utility can be found in the installation location of the Windows SDK. The specific location is C: \ Program Files \ Microsoft SDKs \ Windows \ v6.0 \ Bin.

The following table summarizes the functions provided by the tool and describes the topics related to how to use the tool.

Task	Topic
Generate code based on the running service or static metadata document	Generate a WCF client based on service metadata
Export the metadata document from the compiled code.	How to: Use Svcutil.exe to export metadata from Compiled Service Code
Verify the Compiled Service Code.	How to: Use Svcutil.exe to verify Compiled Service code
Download the metadata document from the running service.	How to: Use Svcutil.exe to download the metadata document
Generate serialization code	How to: Use XmlSerializer to improve the startup time of the WCF client application

Warning

If the name provided in the form of parameters is the same, Svcutil overwrites the existing files on the disk. This may include code files, configuration files, or metadata files. To avoid this situation when generating code and configuration files, use the/mergeConfig switch. In addition, the/r and/ct switches for reference types will be used to generate data protocols. When XmlSerializer is used, these switches do not work.

Timeout

This tool has timed out for 5 minutes when retrieving metadata. This timeout is only applicable for retrieving metadata over the network. It does not apply to any processing operations on the metadata. Multi-objective

This tool does not support multiple targets. To generate a. NET 4 project from svcutil.exe, you must use svcutil.exe in. NET 4 SDK. To generate a. NET 3.5 project, use the executable file in. NET 3.5 SDK. Access the WSDL document

When Svcutil is used to access the WSDL document that has reference to the security token service (STS), Svcutil will execute the WS-MetadataExchange call on STS. However, the service can use WS-MetadataExchange or http get to publish its WSDL document. Therefore, if STS only uses http get to publish the WSDL document, the client written in WinFX fails. For clients written in. NET Framework 3.5, Svcutil will try to use WS-MetadataExchange and http get to obtain sts wsdl.

Use SvcUtil.exe

Common usage

The following table shows some common options for this tool.

Option

Description

/Directory: <directory>

The directory in which the file is to be created.

Default setting: current directory.

Abbreviated form:/d

/Help

Displays the command syntax and options of this tool.

Abbreviated form :/?

/NoLogo

Message About Canceling copyright and title.

/SvcutilConfig: <Configuration File>

Specify the custom configuration file to replace the App. config file. You can use this custom configuration file to register the system. serviceModel extension without changing the configuration file of the tool.

/Target: <output type>

Specifies the output to be generated by the tool.

Valid values are code, metadata, or xmlSerializer.

Abbreviated form:/t code generation

Svcutil.exe can generate code for service agreements, clients, and data types based on metadata documents. These metadata documents can be stored in a persistent storage area or Retrieved online. Online retrieval uses the WS-Metadata Exchange protocol or DISCO protocol (For more information, see the "Metadata Download" section ).

You can use SvcUtil.exe to generate a service and data contract based on the predefined WSDL document. Use the/serviceContract switch and specify the location to download or find the URL or file location of the WSDL document. This will generate the service and data contract, which can then be used to implement the definition in the WSDL document of the complaint service. For more information, see How to: retrieve metadata and implement compatibility services ..

For services that use the BasicHttpContextbinding Terminator, svcutil.exe sets the allowCookies attribute to true for BasicHttpBinding. Cookie is used for the context on the server. If you want to manage the context on the client when the service uses cookies, you can manually modify the configuration to use context binding.

Warning

Svcutil.exe generates a client based on the WSDL or policy file received from the service. The user's primary name (UPN) is generated by concatenating the user name, "@", and fully qualified domain name (FQDN. However, this format is invalid for users registered on Active Directory, and the UPN generated by the tool will cause Kerberos authentication failure. The error message is "logon failed ". To solve this problem, you must manually fix the client files generated by this tool.

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

Parameters

Description

Epr

XML file path, which contains the WS-Addressing EndpointReference that supports the service endpoint of WS-Metadata Exchange. For more information, see the "Metadata Download" section.

MetadataDocumentPath

The path of the metadata document (wsdl or xsd), which contains the protocol for importing code (. wsdl,. xsd,. wspolicy, or. wsmex.

When you specify a remote URL for metadata, Svcutil uses imported and contained content. However, to process metadata files on the local file system, you must specify all files in this parameter. In this way, you can use Svcutil in an environment where no network dependency is available. Wildcard characters (*. xsd, *. wsdl) can be used for this parameter ).

Url

Provides the URL of the service endpoint of metadata or the URL of the metadata document hosted online. For more information about how to retrieve these documents, see the "Metadata Download" section.

Option

Description

/Async

Generate synchronous and asynchronous method signatures at the same time.

Default setting: only the synchronous method signature is generated.

Abbreviated form:/

/CollectionType: <type>

Generate synchronous and asynchronous method signatures at the same time.

Default setting: only the synchronous method signature is generated.

Abbreviated form:/

/Config: <Configuration File>

Specify the file name for the generated configuration file.

Default setting: output. config

/DataContractOnly

Only generate code for the data protocol type. No service agreement type is generated.

Only the local metadata file must be specified for this option.

Abbreviated form:/dconly

/EnableDataBinding

Implement the INotifyPropertyChanged interface on all data protocol types to enable data binding.

Abbreviated form:/edb

/ExcludeType: <type>

Specifies the name of the fully qualified or assembly qualified type to be excluded from the referenced protocol type.

When this switch is used with/r from a separate DLL, the full name of the XSD class is referenced.

Abbreviated form:/et

/ImportXmlTypes

Configure the data protocol serialization program to import non-data protocol types as the IXmlSerializable type.

/Internal

Generate an internal class. Default setting: only public classes are generated.

Abbreviated form:/I

/Language: <language>

Specifies the programming language to be used for code generation. You shall provide the language name registered in the Machine. config file, or the fully qualified name of the class inherited from CodeDomProvider.

Values: c #, cs, csharp, vb, visualbasic, c ++, and cpp

Default setting: csharp

Abbreviated form:/l

Description

For the code provider that comes with Visual Studio 2005 SP1, this switch only supports C ++.

/MergeConfig

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

/MessageContract

Message Protocol type.

Abbreviated form:/mc

/Namespace: <string, string>

Specifies the CLR ing from the WSDL or XML schema targetNamespace to the CLR namespace. If "*" is used for targetNamespace, all targetnamespaces are mapped instead of the CLR namespace.

To ensure that the message protocol name does not conflict with the operation name, use: To restrict type reference, or make sure the name is unique.

Default settings: the target namespace derived from the data contract architecture document. The default namespace is used for all other generated types.

Abbreviated form:/n

/NoConfig

No configuration file is generated.

/NoStdLib

The standard library is not referenced.

Default settings: reference Mscorlib. dll and System. servicemodel. dll.

/Out: <FILE>

Specify the file name for the generated code.

Default setting: the name of the WSDL definition derived from a schema, the name of the WSDL service, or the target namespace.

Abbreviated form:/o

/Reference: <file path>

References the type in the specified assembly. When a client is generated, this option is used to specify assemblies that may contain types that indicate imported metadata.

You cannot use this switch to specify the message protocol and XmlSerializer type.

If DateTimeOffset is referenced, this type is used instead of generating a new type. If the application is written in. NET Framework 3.5, SvcUtil.exe automatically references DateTimeOffset.

Abbreviation:/r

/Serializable

Generate a class marked with the Serializable attribute.

Abbreviation:/s

/ServiceContract (service agreement)

Client classes and configurations are not generated for code that only generates service agreements.

Abbreviation:/SC

/Serializer: Auto

Generate a class marked with the Serializable attribute.

Abbreviation:/s

/Serializer: DataContractSerializer

Generate data types that use the data protocol serialization program for serialization and deserialization.

Abbreviation:/ser: DataContractSerializer

/Serializer: XmlSerializer

Generate data types that use XmlSerializer for serialization and deserialization.

Abbreviated form:/ser: XmlSerializer

/TargetClientVersion

Specifies the version of the. NET Framework that the application is targeting. Valid values: Version30 and Version35. The default value is Version30.

Abbreviated form:/tcv

Version30: if the code is generated for a client that uses WinFX, use/tcv: Version30.

Version35: if the code is generated for a client that uses. NET Framework 3.5,/tcv: Version35 is used. If/tcv: Version35 is used with the/async switch, an event-based asynchronous method and a callback/delegate-based asynchronous method are generated at the same time. In addition, you can enable the data set and DateTimeOffset of LINQ.

/Wrapped

Determines whether to use special case sensitivity for document-literal styles with packaging parameters. Please use/WrappedSwitch the ServiceModel metadata utility (Svcutil.exe) to specify the normal case.

Description

If service binding is one of the bindings provided by the system (see binding provided by the system) and the ProtectionLevel attribute is set to None or Sign, svcutil uses the <customBinding> element instead of the element provided by the expected system to generate the configuration file. For example, if the service uses the <wsHttpBinding> element whose ProtectionLevel is set to Sign, the generated configuration will have <customBinding> in the binding part, instead of <wsHttpBinding>. For more information about protection levels, see understanding protection levels. Metadata Export

Svcutil.exe can export metadata of services, protocols, and data types in compiled programs. To export service metadata, you must use the/serviceName option to specify the service to export. To export all data protocol types in the Assembly, use the/dataContractOnly option. By default, metadata is exported for all service agreements in the input assembly.

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

Parameters

Description

AssemblyPath

Specifies the path of the Assembly, which contains the service, protocol, or data protocol type to be exported. You can use the standard command line wildcard to provide multiple files as input.

Option

Description

/ServiceName: <service configuration name>

The configuration name of the service to be exported. If this option is used, the executable assembly containing the associated configuration file must be passed as the input. Svcutil.exe searches all associated configuration files for the service configuration. If the configuration file contains any extended types, the assembly containing these types must be in GAC or explicitly provided using the/reference option.

/Reference: <file path>

Add the specified assembly to a group of datasets used for parsing type references. If you want to export or verify a service that uses a third-party extension (behavior, binding, and binding element) registered in the configuration, use this option to find the extension assembly that is not in GAC.

Abbreviation:/r

/DataContractOnly

Only operate on the data protocol type. Service agreements are not processed.

Only the local metadata file must be specified for this option.

Abbreviated form:/dconly

/ExcludeType: <type>

Specifies the full or assembly qualified name of the type to be excluded from the export. This option can be used to prevent exporting certain types of metadata for a service or a set of service agreements. This option cannot be used with the/dconly option.

If a single assembly contains multiple services and each service uses a separate class with the same XSD name, you should specify the service name instead of the XSD class name for this switch.

The XSD or data protocol type is not supported.

Abbreviated form:/et service verification

You can use verification to detect service implementation errors without carrying the service. The/serviceName option must be used to indicate the service to be verified.

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

Parameters

Description

AssemblyPath

Specifies the path of the Assembly, which contains the service type to be verified. An Assembly must have an associated configuration file to provide service configuration. You can use the standard command line wildcard to provide multiple sets.

Option

Description

/Validate

Verify the service implementation specified by the/serviceName option. If this option is used, the executable assembly containing the associated configuration file must be passed as the input.

Abbreviated form:/v

/ServiceName: <service configuration name>

The configuration name of the service to be verified. Svcutil.exe searches all associated configuration files of all input assembly for the service configuration. If the configuration file contains any extended types, the assembly containing these types must be in GAC or explicitly provided using the/reference option.

/Reference: <file path>

Add the specified assembly to a group of datasets used for parsing type references. If you want to export or verify a service that uses a third-party extension (behavior, binding, and binding element) registered in the configuration, use this option to find the extension assembly that is not in GAC.

Abbreviation:/r

/DataContractOnly

Only operate on the data protocol type. Service agreements are not processed.

Only the local metadata file must be specified for this option.

Abbreviated form:/dconly

/ExcludeType: <type>

Specifies the full or assembly qualified name of the type to be excluded from verification.

Abbreviated form:/et Metadata Download

You can use Svcutil.exe to download metadata from a running service and save the metadata to a local file. To download metadata, you must specify the/t: metadata option. Otherwise, the client code is generated. Svcutil.exe tries to use WS-Metadata Exchange and DISCO to retrieve Metadata for HTTP and HTTPS URLs. For all other URLs, svcutil.exe only uses WS-Metadata Exchange.

Svcutil sends the following metadata request to retrieve the metadata at the same time.

• For the MEX (WS-Transfer) request of the provided address

• MEX requests for the provided address (with/mex attached)

• For the DISCO request of the provided address (use DiscoveryClientProtocol in ASMX ).

Svcutil.exe uses the bindings defined in the MetadataExchangeBindings class for the MEX request. To configure the binding for WS-Metadata Exchange, you must define a client endpoint in the configuration using the IMetadataExchange protocol. You can define this endpoint in the configuration file of Svcutil.exe, or in another configuration file specified by the/svcutilConfig option.

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

Parameters

Description

Url

Provides the URL of the service endpoint of metadata or the URL of the metadata document hosted online.

Epr

XML file path, which contains the WS-Addressing EndpointReference that supports the service endpoint of WS-Metadata Exchange. XmlSerializer type generation

If the service and client applications use the data types that can be serialized using XmlSerializer, the serialization code of these data types will be generated and compiled at runtime, resulting in lower startup performance.

Description

Pre-generated serialization code can only be used in client applications and cannot be used in services.

Svcutil.exe can generate necessary C # serialization code based on the compiled assembly of the application, thus improving the startup performance of these applications. For more information, see How to: Use XmlSerializer to improve the startup time of the WCF client application.

Description

Svcutil.exe only generates code for the type used by the service agreement in the input assembly.

Svcutil.exe/t: xmlSerializer <assemblyPath> *

Parameters

Description

AssemblyPath

Specifies the path of the assembly that contains the service agreement type. Generate a serialization type for all Xml serializable types in each protocol.

Option

Description

/Reference: <file path>

Add the specified assembly to a group of datasets used for parsing type references.

Abbreviation:/r

/ExcludeType: <type>

Specifies the full or assembly qualified name of the type to be excluded from the export or verification.

Abbreviated form:/et

/Out: <FILE>

Specify the file name for the generated code. If multiple assemblies are passed to the tool as input, this option is ignored.

Default setting: the name of the derived assembly.

Abbreviated form:/o

/UseSerializerForFaults

Specify that XmlSerializer (instead of the default DataContractSerializer) should be used to read and write errors.

Example

Maximum name table character count quota

When you use svcutil to generate service metadata, you will receive the following message:

Error: unable to get metadata from http: // localhost: 8000/somesservice/mex. When reading XML data, the maximum number of characters in the name table is exceeded (16384 ). A name table is a data structure used to store strings encountered when processing XML. A long XML document with non-repeating element names, feature names, and feature values may trigger this quota. You can add this quota by changing the MaxNameTableCharCount attribute of the XmlDictionaryReaderQuotas object used when creating an XML reader.

If you return a large WSDL file when requesting the metadata of a service, the service will cause this error. The problem is that it exceeds the character quota of the svcutil.exe tool. This value is set to help prevent dos attacks. You can add this quota by specifying the following configuration file for svcutil.

The following configuration file demonstrates how to set the svcutil reader quota

<? Xml version = "1.0" encoding = "UTF-8"?> <Configuration> <system. serviceModel> <bindings> <customBinding> <binding name = "MyBinding"> <textMessageEncoding> <readerQuotas maxDepth = "2147483647" maxStringContentLength = "2147483647" maxArrayLength = "2147483647" maxBytesPerRead =" "maxNameTableCharCount =" 2147483647 "/> </textMessageEncoding> 
Create a file named svcutil.exe. config and copy the XML sample code to the file. Put the file in the same directory as svcutil.exe. When svcutil.exe is run next time, it selects a new setting.
Security questions
You should use the appropriate access control list (ACL) to protect the installation folder, Svcutil. config, and files pointed to by/svcutilConfig. This prevents malicious extension registration and operation.
In addition, to minimize the likelihood of security hazards, you should not add untrusted extensions to the system or use untrusted code providers for Svcutil.exe.
Finally, you should not use this tool in the application's middle layer because it may cause the current process to drop services.
See
Task
How to: Create a Windows Communication Foundation Client Reference
DataContractAttribute
DataMemberAttribute
ServiceModel metadata utility (Svcutil.exe)