ServiceModel 元数据实用工具 (Svcutil.exe)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.

SvcUtil.exeSvcUtil.exe

可在 Windows SDK 安装位置找到 "%ProgramFiles%\Microsoft" 元数据实用工具,具体来说就是SDKs\Windows\v6.0\BinThe ServiceModel Metadata Utility Tool can be found at the Windows SDK installation location, specifically %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin.

功能Functionalities

下表汇总了此工具提供的各种功能,以及讨论如何使用该工具的相应主题: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. 根据服务元数据生成 WCF 客户端Generating a WCF Client from Service Metadata
从编译的代码中导出元数据文档。Exports metadata documents from compiled code. 如何:使用 Svcutil.exe 将元数据从已编译的服务代码中导出How to: Use Svcutil.exe to Export Metadata from Compiled Service Code
验证编译的服务代码。Validates compiled service code. 如何:使用 Svcutil.exe 验证已编译的服务代码How to: Use Svcutil.exe to Validate Compiled Service Code
从运行的服务中下载元数据文档。Downloads metadata documents from running services. 如何:使用 Svcutil.exe 下载元数据文档How to: Use Svcutil.exe to Download Metadata Documents
生成序列化代码。Generates serialization code. 如何:使用 XmlSerializer 改善 WCF 客户端应用程序的启动时间How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer

注意

如果作为参数提供的名称相同,svcutil.exe 将覆盖磁盘上的现有文件。Svcutil overwrites existing files on a disk if the names supplied as parameters are identical. 这可以包括代码文件、配置或元数据文件。This can include code files, configuration, or metadata files. 为避免出现这种情况,请使用 /mergeConfig 开关。To avoid this when generating code and configuration files, use the /mergeConfig switch.

此外,引用类型的 /r/ct 开关用于生成数据协定。In addition, the /r and /ct switches for referencing types are for generating data contracts. 使用 XmlSerializer 时,这些开关不起作用。These switches do not work when using XmlSerializer.

超时Timeout

检索元数据时,该工具有五分钟的超时时间。The tool has a five 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.

多目标Multi-targeting

该工具不支持多目标。The tool does not support multi-targeting. 如果要从svcutil.exe生成 .net 4 项目,请使用 .NET 4 SDK 中的svcutil.exeIf you want to generate a .NET 4 artifact from svcutil.exe, use the svcutil.exe from the .NET 4 SDK. 若要生成 .NET 3.5 项目,请使用 .NET 3.5 SDK 中的可执行文件。To generate a .NET 3.5 artifact, use the executable from the .NET 3.5 SDK.

访问 WSDL 文档Accessing WSDL Documents

使用 Svcutil 来访问具有对安全令牌服务 (STS) 的引用的 WSDL 文档时,Svcutil 将对 STS 执行 WS-MetadataExchange 调用。When you use Svcutil to access a WSDL document that has a reference to a security token service (STS), Svcutil makes a WS-MetadataExchange call to the STS. 但是,服务可以使用 WS-MetadataExchange 或 HTTP GET 来公开其 WSDL 文档。However, the service can expose its WSDL documents using either WS-MetadataExchange or HTTP GET. 因此,如果 STS 只使用 HTTP GET 公开了 WSDL 文档,则使用 WinFX 编写的客户端将失败。Therefore, if the STS has only exposed the WSDL document using HTTP GET, a client written in WinFX will fail. 对于以 .NET Framework 3.5 编写的客户端,Svcutil.exe 尝试同时使用 Ws-metadataexchange 和 HTTP GET 来获取 STS WSDL。For clients written in .NET Framework 3.5, Svcutil attempts to use both WS-MetadataExchange and HTTP GET to obtain the STS WSDL.

使用 SvcUtil.exeUsing SvcUtil.exe

常见用法Common Usages

下表显示了此工具的一些常用选项:The following table shows some commonly used options for this tool:

选项Option 说明Description
/目录:<directory >/directory:<directory> 要在其中创建文件的目录。Directory to create files in.

默认设置:当前目录。Default: The current directory.

缩写形式:/dShort form: /d
/help/help 显示此工具的命令语法和选项。Displays the command syntax and options for the tool.

缩写形式:/?Short form: /?
/noLogo/noLogo 取消版权和标题消息。Suppress the copyright and banner message.
/svcutilConfig:<Read-configfile >/svcutilConfig:<configFile> 指定要取代 App.config 文件使用的自定义配置文件。Specifies a custom configuration file to use instead of the App.config file. 可以使用该自定义配置文件来注册 system.serviceModel 扩展,而无需更改工具的配置文件。This can be used to register system.serviceModel extensions without altering the tool's configuration file.
/target:<输出类型 >/target:<output type> 指定要由工具生成的输出。Specifies the output to be generated by the tool.

有效的值为代码、元数据或 xmlSerializer。Valid values are code, metadata or xmlSerializer.

缩写形式:/tShort form: /t

代码生成Code Generation

Svcutil.exe 可以依据元数据文档为服务协定、客户端和数据类型生成代码。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. 联机检索采用 WS-Metadata Exchange 协议或 DISCO 协议(有关详细信息,请参见“元数据下载”一节)。Online retrieval follows either the WS-Metadata Exchange protocol or the DISCO protocol (for details see the Metadata Download section).

可以使用svcutil.exe工具基于预定义的 WSDL 文档生成服务和数据协定。You can use the SvcUtil.exe tool to generate service and data contracts based on a predefined WSDL document. 使用 /serviceContract 开关并指定可以从中下载或找到 WSDL 文档的 URL 或文件位置。Use the /serviceContract switch and specify a URL or file location where the WSDL document can be downloaded or found. 这会生成在 WSDL 文档中定义的服务和数据协定,然后可以使用该协定来实现投诉服务。This generates the service and data contracts defined in the WSDL document that can then be used to implement a complaint service. 有关详细信息,请参阅如何:检索元数据并实现兼容服务For more information, see How to: Retrieve Metadata and Implement a Compliant Service.

对于具有 BasicHttpContextBinding 终结点的服务, svcutil.exe会生成 BasicHttpBinding,并将 allowCookies 特性设置为 trueFor a service with a BasicHttpContextBinding endpoint, Svcutil.exe generates a BasicHttpBinding with the allowCookies attribute set to true instead. Cookie 用于服务器上的上下文。The cookies are used for context on the server. 如果在服务使用 Cookie 时,你要管理客户端上的上下文,则可以手动修改配置以使用上下文绑定。If you would like to manage context on the client when the service uses cookies, you can manually modify the configuration to use a context binding.

注意

Svcutil.exe 基于 WSDL 或从服务收到的策略文件生成客户端。Svcutil.exe generates the client based on the WSDL or policy file received from the service. 用户主体名称(UPN)是通过将用户名、"@" 和完全限定的域名(FQDN)进行连接生成的。The user principal name (UPN) is generated by concatenating username, "@" and a fully-qualified domain name (FQDN). 但是,对于在 Active Directory 上注册的用户,此格式无效,并且工具生成的 UPN 将导致 Kerberos 身份验证失败,错误消息为“登录没有成功”。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>

ArgumentArgument 说明Description
epr XML 文件的路径,该文件包含支持 WS-Metadata Exchange 的服务终结点的 WS-Addressing EndpointReference。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 包含要导入到代码中的协定的元数据文档(wsdlxsd)的路径(.wsdl、.xsd、. wspolicy 或 wsmex)。The path to a metadata document (wsdl or xsd) that contains the contract to import into code (.wsdl, .xsd, .wspolicy, or .wsmex).

当您为元数据指定远程 URL 时,Svcutil 采用导入和包含的内容。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. 这样,您可以在不能有网络依赖项的生成环境中使用 Svcutil。In this way, you can use Svcutil in a build environment where you cannot have network dependencies. 对于此参数,可以使用通配符(* .xsd,*.wsdl)。You can use wildcards (*.xsd, *.wsdl) for this argument.
url 可提供元数据的服务终结点的 URL,或是联机承载的元数据文档的 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.
选项Option 说明Description
/async/async 同时生成同步和异步方法签名。Generates both synchronous and asynchronous method signatures.

默认设置:只生成同步方法签名。Default: generate only synchronous method signatures.

缩写形式:/aShort Form: /a
/collectionType:<类型 >/collectionType:<type> 为 WCF 客户端指定列表集合类型。Specifies the list collection type for a WCF client.

默认:集合类型为 System.object。Default: collection type is System.Array.

缩写形式:/ctShort Form: /ct
/config:<Read-configfile >/config:<configFile> 为生成的配置文件指定文件名。Specifies the filename for the generated configuration file.

默认设置:output.configDefault: output.config
/dataContractOnly/dataContractOnly 只为数据协定类型生成代码。Generates code for data contract types only. 不生成服务协定类型。Service Contract types are not generated.

只应为此选项指定本地元数据文件。You should only specify local metadata files for this option.

缩写形式:/dconlyShort Form: /dconly
/enableDataBinding/enableDataBinding 在所有数据协定类型上实现 INotifyPropertyChanged 接口以启用数据绑定。Implements the INotifyPropertyChanged interface on all Data Contract types to enable data binding.

缩写形式:/edbShort Form: /edb
/excludeType:<类型 >/excludeType:<type> 指定要从引用的协定类型中排除的完全限定或程序集限定类型名称。Specifies a fully-qualified or assembly-qualified type name to be excluded from referenced contract types.

从单独的 DLL 中将此开关与 /r 一起使用时,将引用 XSD 类的全名。When using this switch together with /r from separate DLLs, the full name of the XSD class is referenced.

缩写形式:/etShort Form: /et
/importXmlTypes/importXmlTypes 配置数据协定序列化程序,以便将非数据协定类型作为 IXmlSerializable 类型导入。Configures the Data Contract serializer to import non-Data Contract types as IXmlSerializable types.
/internal/internal 生成标记为内部的类。Generates classes that are marked as internal. 默认设置:只生成公共类。Default: generate public classes only.

缩写形式:/iShort Form: /i
/language:<语言 >/language:<language> 指定要用于代码生成的编程语言。Specifies the programming language to use for code generation. 应提供在 Machine.config 文件中注册的语言名称,或从 CodeDomProvider继承的类的完全限定名称。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.

值:c#、cs、csharp、vb、visualbasic、c++、cppValues: c#, cs, csharp, vb, visualbasic, c++, cpp

默认设置:csharpDefault: csharp

缩写形式:/lShort form: /l
/mergeConfig/mergeConfig 将生成的配置合并到现有文件中,而不是覆盖现有文件。Merges the generated configuration into an existing file, instead of overwriting the existing file.
/messageContract/messageContract 生成消息协定类型。Generates Message Contract types.

缩写形式:/mcShort Form: /mc
/namespace:<string,string >/namespace:<string,string> 指定从 WSDL 或 XML 架构 targetNamespace 到 CLR 命名空间的映射。Specifies a mapping from a WSDL or XML Schema targetNamespace to a CLR namespace. 对于 targetNamespace,使用 "*" 可将所有 Targetnamespace 映射到该 CLR 命名空间的显式映射。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.

短格式: /n注意: 生成要与 XmlSerializer 一起使用的类型时,仅支持单个命名空间映射。Short Form: /n Note: When generating types to use with XmlSerializer, only a single namespace mapping is supported. 所有生成的类型都将位于默认命名空间或由 "*" 指定的命名空间中。All generated types will either be in the default namespace or the namespace specified by '*'.
/noConfig/noConfig 不生成配置文件。Do not generate configuration files.
/noStdLib/noStdLib 不引用标准库。Do not reference standard libraries.

默认设置:引用 Mscorlib.dll 和 System.servicemodel.dll。Default: Mscorlib.dll and System.servicemodel.dll are referenced.
/out:<文件 >/out:<file> 为生成的代码指定文件名。Specifies the file name for the generated code.

默认设置:派生自某个架构的 WSDL 定义名称、WSDL 服务名称或目标命名空间。Default: Derived from the WSDL definition name, WSDL service name or target namespace of one of the schemas.

缩写形式:/oShort form: /o
/reference:<文件路径 >/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.

无法使用此开关指定消息协定和 XmlSerializer 类型。You cannot specify message contracts and XmlSerializer types using this switch.

如果引用了 DateTimeOffset,则会使用此类型,而不是生成新类型。If DateTimeOffset referenced, this type is used instead of generating a new type. 如果使用 .NET Framework 3.5 编写应用程序,Svcutil.exe 将自动 DateTimeOffset 引用。If the application is written using .NET Framework 3.5, SvcUtil.exe references DateTimeOffset automatically.

缩写形式:/rShort Form: /r
/serializable/serializable 生成用 Serializable 属性标记的类。Generates classes marked with the Serializable Attribute.

缩写形式:/sShort Form: /s
/serviceContract/serviceContract 仅生成服务协定的代码。Generate code for service contracts only. 不会生成客户端类和配置Client class and configuration will not be generated

缩写形式:/scShort Form: /sc
/serializer:Auto/serializer:Auto 自动选择序列化程序。Automatically select the serializer. 这会尝试使用数据协定序列化程序,如果失败,则使用 XmlSerializer。This tries to use the Data Contract serializer and uses the XmlSerializer if that fails.

缩写形式:/serShort Form: /ser
/serializer:DataContractSerializer/serializer:DataContractSerializer 生成使用数据协定序列化程序进行序列化和反序列化的数据类型。Generates data types that use the Data Contract Serializer for serialization and deserialization.

缩写形式:/ser:DataContractSerializerShort Form: /ser:DataContractSerializer
/serializer:XmlSerializer/serializer:XmlSerializer 生成使用 XmlSerializer 进行序列化和反序列化的数据类型。Generates data types that use the XmlSerializer for serialization and deserialization.

缩写形式:/ser:XmlSerializerShort Form: /ser:XmlSerializer
/targetClientVersion/targetClientVersion 指定应用程序面向 .NET Framework 的版本。Specify which version of .NET Framework the application is targeting. 有效值为 Version30Version35Valid values are Version30 and Version35. 默认值为 Version30The default value is Version30.

缩写形式:/tcvShort Form: /tcv

Version30:如果要为使用 WinFX 的客户端生成代码,请使用 /tcv:Version30Version30: Use /tcv:Version30 if you are generating code for clients that use WinFX.

Version35:如果要为使用 .NET Framework 3.5 的客户端生成代码,请使用 /tcv:Version35Version35: Use /tcv:Version35 if you are generating code for clients that use .NET Framework 3.5. 如果将 /tcv:Version35/async 开关一起使用,则会同时生成基于事件的异步方法和基于回调/委托的异步方法。When using /tcv:Version35 with the /async switch, both event-based and callback/delegate-based asynchronous methods are generated. 此外,还能够支持启用 LINQ 的数据集和 DateTimeOffsetIn addition, support for LINQ-enabled DataSets and DateTimeOffset is enabled.
/wrapped/wrapped 控制是否对具有包装参数的 document-literal 样式的文档使用特殊大小写。Controls whether special-casing is used for document-literal styled documents with wrapped parameters. 结合使用 /wrapped开关和服务模型元数据实用工具(svcutil.exe)工具来指定正常大小写。Use the /wrapped switch with the Service Model Metadata Utility Tool (Svcutil.exe) tool to specify normal casing.

备注

如果服务绑定是系统提供的绑定之一(请参阅系统提供的绑定),并且 ProtectionLevel 属性设置为 NoneSign,则 svcutil.exe 将使用<customBinding >元素而不是预期的系统提供的元素生成配置文件。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. 例如,如果服务使用 <wsHttpBinding> 设置为 ProtectionLevelSign 元素,则生成的配置在绑定部分中将有 <customBinding>,而不是 <wsHttpBinding>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 可以导出已编译程序集中服务、协定和数据类型的元数据。Svcutil.exe can export metadata for services, contracts and data types in compiled assemblies. 若要导出服务的元数据,您必须使用 /serviceName 选项指定要导出的服务。To export metadata for a service, you must use the /serviceName option to specify the service you would like to export. 若要导出程序集内的所有数据协定类型,应使用 /dataContractOnly 选项。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>*

ArgumentArgument 说明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 >/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 将为服务配置搜索所有关联的配置文件。Svcutil.exe searches all associated configuration files for the service configuration. 如果配置文件包含任何扩展类型,则包含这些类型的程序集必须位于 GAC 中,或者必须使用 /reference 选项显式提供。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:<文件路径 >/reference:<file path> 将指定程序集添加到用于解析类型引用的一组程序集中。Adds the specified assembly to the set of assemblies used for resolving type references. 如果要导出或验证使用在配置中注册的第三方扩展(行为、绑定和绑定元素)的服务,请使用此选项找到不在 GAC 中的扩展程序集。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.

缩写形式:/rShort Form: /r
/dataContractOnly/dataContractOnly 只对数据协定类型进行操作。Operates on data contract types only. 不会处理服务协定。Service Contracts are not processed.

只应为此选项指定本地元数据文件。You should only specify local metadata files for this option.

缩写形式:/dconlyShort Form: /dconly
/excludeType:<类型 >/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. 此选项不能与 /dconly 选项一起使用。This option cannot be used together with the /dconly option.

如果有包含多个服务的单一程序集,并且每个服务都使用具有相同 XSD 名称的单独的类,则您应为此开关指定服务名称,而不是 XSD 类名称。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 或数据协定类型。XSD or data contract types are not supported.

缩写形式:/etShort Form: /et

服务验证Service Validation

可以使用验证在不承载服务的情况下检测服务实现中的错误。Validation can be used to detect errors in service implementations without hosting the service. 必须使用 /serviceName 选项指示要验证的服务。You must use the /serviceName option to indicate the service you want to validate.

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

ArgumentArgument 说明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/validate 验证 /serviceName 选项指定的服务实现。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.

缩写形式:/vShort Form: /v
/serviceName:<serviceConfigName >/serviceName:<serviceConfigName> 指定要验证的服务的配置名称。Specifies the configuration name of a service to be validated. Svcutil.exe 将为服务配置搜索所有输入程序集的所有关联配置文件。Svcutil.exe searches all associated configuration files of all input assemblies for the service configuration. 如果配置文件包含任何扩展类型,则包含这些类型的程序集必须位于 GAC 中,或者必须使用 /reference 选项显式提供。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:<文件路径 >/reference:<file path> 将指定程序集添加到用于解析类型引用的一组程序集中。Adds the specified assembly to the set of assemblies used for resolving type references. 如果要导出或验证使用在配置中注册的第三方扩展(行为、绑定和绑定元素)的服务,请使用此选项找到不在 GAC 中的扩展程序集。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.

缩写形式:/rShort Form: /r
/dataContractOnly/dataContractOnly 只对数据协定类型进行操作。Operates on data contract types only. 不会处理服务协定。Service Contracts are not processed.

只应为此选项指定本地元数据文件。You should only specify local metadata files for this option.

缩写形式:/dconlyShort Form: /dconly
/excludeType:<类型 >/excludeType:<type> 指定要从验证中排除的类型的完全限定或程序集限定名称。Specifies the fully-qualified or assembly-qualified name of a type to be excluded from validation.

缩写形式:/etShort Form: /et

元数据下载Metadata Download

可以使用 Svcutil.exe 从运行的服务中下载元数据,并将元数据保存到本地文件。Svcutil.exe can be used to download metadata from running services, and save the metadata to local files. 若要下载元数据,您必须指定 /t:metadata 选项。To download metadata, you must specify the /t:metadata option. 否则,将生成客户端代码。Otherwise, client code is generated. 对于 HTTP 和 HTTPS URL 方案,Svcutil.exe 会尝试使用 WS-Metadata Exchange 和 DISCO 检索元数据。For HTTP and HTTPS URL schemes, Svcutil.exe attempts to retrieve metadata using WS-Metadata Exchange and DISCO. 对于所有其他 URL 方案,Svcutil.exe 只使用 WS-Metadata Exchange。For all other URL schemes, Svcutil.exe only uses WS-Metadata Exchange.

Svcutil 会同时发出以下元数据请求以检索元数据。Svcutil issues the following metadata requests simultaneously to retrieve metadata.

  • 针对所提供地址的 MEX (WS-Transfer) 请求MEX (WS-Transfer) request to the supplied address

  • 针对所提供地址的 MEX 请求(附加有 /mex)MEX request to the supplied address with /mex appended

  • 针对所提供地址的 DISCO 请求(使用 ASMX 中的 DiscoveryClientProtocol)。DISCO request (using the DiscoveryClientProtocol from ASMX) to the supplied address.

默认情况下,Svcutil.exe 使用 MetadataExchangeBindings 类中定义的绑定进行 MEX 请求。By default, Svcutil.exe uses the bindings defined in the MetadataExchangeBindings class to make MEX requests. 若要配置用于 WS-Metadata Exchange 的绑定,你必须在使用 IMetadataExchange 协定的配置中定义一个客户端终结点。To configure the binding used for WS-Metadata Exchange, you must define a client endpoint in configuration that uses the IMetadataExchange contract. 可以在 Svcutil.exe 的配置文件中定义此终结点,也可以在使用 /svcutilConfig 选项指定的另一个配置文件中定义。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>

ArgumentArgument 说明Description
url 可提供元数据的服务终结点的 URL,或是联机承载的元数据文档的 URL。The URL to a service endpoint that provides metadata or to a metadata document hosted online.
epr XML 文件的路径,该文件包含支持 WS-Metadata Exchange 的服务终结点的 WS-Addressing EndpointReference。The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange.

XmlSerializer 类型生成XmlSerializer Type Generation

如果服务和客户端应用程序使用可用 XmlSerializer 进行序列化的数据类型,则会在运行时生成并编译这些数据类型的序列化代码,从而导致启动性能降低。Services and client applications that use data types that are serializable using the XmlSerializer generate and compile serialization code for those data types at runtime, which can result in slow start-up performance.

备注

预生成的序列化代码只能在客户端应用程序中使用,不能在服务中使用。Pre-generated serialization code can only be used in client applications and not in services.

Svcutil.exe 可依据应用程序的已编译程序集生成必要的 C# 序列化代码,因而可提高这些应用程序的启动性能。Svcutil.exe can generate the necessary C# serialization code from the compiled assemblies for the application, thus improving start-up performance for these applications. 有关详细信息,请参阅如何:使用 XmlSerializer 改善 WCF 客户端应用程序的启动时间For more information, see How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer.

备注

Svcutil.exe 只会为输入程序集中的服务协定使用的类型生成代码。Svcutil.exe only generates code for types used by Service Contracts found in the input assemblies.

svcutil.exe /t:xmlSerializer <assemblyPath>*

ArgumentArgument 说明Description
assemblyPath 指定包含服务协定类型的程序集的路径。Specifies the path to an assembly that contains service contract types. 为每个协定中的所有 Xml 可序列化类型生成序列化类型。Serialization types are generated for all Xml Serializable types in each contract.
选项Option 说明Description
/reference:<文件路径 >/reference:<file path> 将指定程序集添加到用于解析类型引用的一组程序集中。Adds the specified assembly to the set of assemblies used for resolving type references.

缩写形式:/rShort Form: /r
/excludeType:<类型 >/excludeType:<type> 指定要从导出或验证中排除的类型的完全限定或程序集限定名称。Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export or validation.

缩写形式:/etShort Form: /et
/out:<文件 >/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.

缩写形式:/oShort Form: /o
/UseSerializerForFaults/UseSerializerForFaults 指定应该使用 XmlSerializer(而不是默认的 DataContractSerializer)来读取和写入错误。Specifies that the XmlSerializer should be used for reading and writing faults, instead of the default DataContractSerializer.

示例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#

以下命令将依据本地架构文档用 Visual Basic 生成数据协定类型。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

以下命令为程序集中任何服务协定使用的 XmlSerializer 类型生成序列化类型。The following command generates serialization types for XmlSerializer types used by any service contracts in the assembly.

svcutil /t:xmlserializer myContractLibrary.exe

最大名称表字符计数配额Maximum Nametable Character Count Quota

使用 svcutil 生成服务的元数据时,您会收到以下消息:When using svcutil to generate metadata for a service, you may get the following message:

错误:无法从 http://localhost:8000/somesservice/mex 中获取元数据,因为读取 XML 数据时超过了最大字符数字符计数配额(16384)。Error: Cannot obtain Metadata from http://localhost:8000/somesservice/mex The maximum nametable character count quota (16384) has been exceeded while reading XML data. 名称表是用于存储在处理 XML 时所遇到的字符串的数据结构 - 具有非重复元素名称、特性名称和特性值的长 XML 文档可能会触发此配额。The nametable is a data structure used to store strings encountered during XML processing - long XML documents with non-repeating element names, attribute names and attribute values may trigger this quota. 通过更改在创建 XML 读取器时所使用的 XmlDictionaryReaderQuotas 对象的 MaxNameTableCharCount 属性,可增加此配额。This quota may be increased by changing the MaxNameTableCharCount property on the XmlDictionaryReaderQuotas object used when creating the XML reader.

如果您请求某个服务的元数据时返回大 WSDL 文件,则该服务会导致此错误。This error can be caused by a service that returns a large WSDL file when you request its metadata. 问题在于超过了 svcutil.exe 工具的字符配额。The problem is that the character quota for the svcutil.exe tool is exceeded. 设置此值是为了帮助防止遭受拒绝服务 (dos) 攻击。This value is set to help prevent denial of service (dos) attacks. 您可以通过为 svcutil 指定下面的配置文件来增加此配额。You can increase this quota by specifying the following config file for svcutil.

下面的配置文件演示如何设置 svcutil 的读取器配额The following config file shows how to set the reader quotas for svcutil

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <system.serviceModel>
        <bindings>
            <customBinding>
                <binding name="MyBinding">
                    <textMessageEncoding>
                        <readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
                            maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
                    </textMessageEncoding>
                    <httpTransport maxReceivedMessageSize="2147483647" maxBufferSize="2147483647" />
                </binding>
            </customBinding>
        </bindings>
        <client>
            <endpoint binding="customBinding" bindingConfiguration="MyBinding"
                contract="IMetadataExchange"
                name="http" />
        </client>
    </system.serviceModel>
</configuration>

新建一个名为 svcutil.exe.config 的文件,再将 XML 示例代码复制到该文件中。Create a new file called svcutil.exe.config and copy the XML example code into it. 然后将该文件放到与 svcutil.exe 相同的目录中。Then place the file in the same directory as svcutil.exe. 下次运行 svcutil.exe 时,它会选取新的设置。The next time svcutil.exe is run it will pick up the new settings.

安全问题Security Concerns

您应使用适当的访问控制列表 (ACL) 来保护 Svcutil.exe 的安装文件夹、Svcutil.config 以及 /svcutilConfig 所指向的文件。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.

此外,为了最大限度地减少安全漏洞的可能性,不应将不受信任的扩展添加为系统的一部分,或者使用 Svcutil.exe 的不受信任的代码提供程序。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.

另请参阅See also