首页 > 代码库 > ServiceModel 元数据实用工具 (Svcutil.exe)
ServiceModel 元数据实用工具 (Svcutil.exe)
ServiceModel 元数据实用工具用于依据元数据文档生成服务模型代码，以及依据服务模型代码生成元数据文档
一、SvcUtil.exe
ServiceModel 元数据实用工具可在 Windows SDK 安装位置中找到，具体位置为 C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin
功能
下表概括了此工具提供的各种功能，以及论述如何使用该工具的对应主题。
| 任务 | 主题 |
| 依据运行的服务或静态元数据文档生成代码 | 根据服务元数据生成 WCF 客户端 |
| 从编译的代码中导出元数据文档。 | 如何：使用 Svcutil.exe 将元数据从已编译的服务代码中导出 |
| 验证编译的服务代码。 | 如何：使用 Svcutil.exe 验证已编译的服务代码 |
| 从运行的服务中下载元数据文档。 | 如何：使用 Svcutil.exe 下载元数据文档 |
| 生成序列化代码 | 如何：使用 XmlSerializer 改善 WCF 客户端应用程序的启动时间 |
警告
如果以参数形式提供的名称相同，Svcutil 将覆盖磁盘上的现有文件。 这可能包括代码文件、配置或元数据文件。 若要在生成代码和配置文件时避免这种情况，请使用/mergeConfig 开关。此外，用于引用类型的 /r 和 /ct 开关将用于生成数据协定。 使用 XmlSerializer 时，这些开关不起作用。超时该工具在检索元数据时有 5 分钟的超时。 此超时仅适用于通过网络检索元数据的操作。 它不适用于该元数据的任何处理操作。
多目标
该工具不支持多目标。 如果希望从 svcutil.exe 生成 .NET 4 项目，则必须使用 .NET 4 SDK 中的 svcutil.exe。 若要生成 .NET 3.5 项目，请使用 .NET 3.5 SDK 中的可执行文件。
访问 WSDL 文档
使用 Svcutil 来访问具有对安全令牌服务 (STS) 的引用的 WSDL 文档时，Svcutil 将对 STS 执行 WS-MetadataExchange 调用。 但是，服务可以使用 WS-MetadataExchange 或 HTTP GET 来公开其 WSDL 文档。 因此，如果 STS 仅使用 HTTP GET 公开 WSDL 文档，则用 WinFX 编写的客户端将失败。 对于用 .NET Framework 3.5 编写的客户端，Svcutil 将尝试使用 WS-MetadataExchange 和 HTTP GET 来获取 STS WSDL。
使用 SvcUtil.exe
常见用法
下表显示了此工具的一些常用选项。
选项
说明
/directory:<目录>
要在其中创建文件的目录。
默认设置：当前目录。
缩写形式：/d
/help
显示此工具的命令语法和选项。
缩写形式：/?
/noLogo
取消版权和标题消息。
/svcutilConfig:<配置文件>
指定要取代 App.config 文件使用的自定义配置文件。 可以使用该自定义配置文件来注册 system.serviceModel 扩展，而无需更改工具的配置文件。
/target:<输出类型>
指定要由工具生成的输出。
有效的值为代码、元数据或 xmlSerializer。
缩写形式：/t
代码生成
Svcutil.exe 可以依据元数据文档为服务协定、客户端和数据类型生成代码。 这些元数据文档可以位于持久存储区上，也可以联机检索。 联机检索采用 WS-Metadata Exchange 协议或 DISCO 协议（有关详细信息，请参见“元数据下载”一节）。
可以使用 SvcUtil.exe 工具生成基于预定义的 WSDL 文档的服务和数据的合同。 使用 /serviceContract 开关并指定位置下载或者发现 WSDL 文档的 URL 或文件位置。 这将生成的服务和数据的合约，然后可以用来实施投诉服务的 WSDL 文档中定义。 有关详细信息，请参阅如何：检索元数据并实现兼容服务。.
而对于使用 BasicHttpContextbinding 终结点的服务，Svcutil.exe 将生成 allowCookies 属性设置为 true 的 BasicHttpBinding。 Cookie 用于服务器上的上下文。 如果在服务使用 Cookie 时，您要管理客户端上的上下文，则可以手动修改配置以使用上下文绑定。
警告
Svcutil.exe 基于 WSDL 或从服务收到的策略文件生成客户端。 用户主要名称 (UPN) 是通过将用户名、“@”和完全限定域名 (FQDN) 串联在一起生成的。 但是，对于在 Active Directory 上注册的用户，此格式无效，并且工具生成的 UPN 将导致 Kerberos 身份验证失败，错误消息为“登录没有成功”。 若要解决此问题，您应手动修复此工具生成的客户端文件。
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
参数
说明
epr
XML 文件的路径，该文件包含支持 WS-Metadata Exchange 的服务终结点的 WS-Addressing EndpointReference。 有关更多信息，请参见“元数据下载”一节。
metadataDocumentPath
元数据文档（wsdl 或 xsd）的路径，该文档包含要导入代码（.wsdl、.xsd、.wspolicy 或 .wsmex）的协定。
当您为元数据指定远程 URL 时，Svcutil 采用导入和包含的内容。 但是，如果要在本地文件系统上处理元数据文件，则必须在此参数中指定所有文件。 这样，您可以在不能有网络依赖项的生成环境中使用 Svcutil。 可以为此参数使用通配符（*.xsd、*.wsdl）。
url
可提供元数据的服务终结点的 URL，或是联机承载的元数据文档的 URL。 有关如何检索这些文档的更多信息，请参见“元数据下载”一节。
选项
说明
/async
同时生成同步和异步方法签名。
默认设置：只生成同步方法签名。
缩写形式：/a
/collectionType:<类型>
同时生成同步和异步方法签名。
默认设置：只生成同步方法签名。
缩写形式：/a
/config:<配置文件>
为生成的配置文件指定文件名。
默认设置：output.config
/dataContractOnly
只为数据协定类型生成代码。 不生成服务协定类型。
只应为此选项指定本地元数据文件。
缩写形式：/dconly
/enableDataBinding
在所有数据协定类型上实现 INotifyPropertyChanged 接口以启用数据绑定。
缩写形式：/edb
/excludeType:<类型>
指定要从引用的协定类型中排除的完全限定或程序集限定类型名称。
从单独的 DLL 中将此开关与 /r 一起使用时，将引用 XSD 类的全名。
缩写形式：/et
/importXmlTypes
配置数据协定序列化程序，以便将非数据协定类型作为 IXmlSerializable 类型导入。
/internal
生成标记为内部的类。 默认设置：只生成公共类。
缩写形式：/i
/language:<语言>
指定要用于代码生成的编程语言。 您应提供在 Machine.config 文件中注册的语言名称，或继承自 CodeDomProvider 的类的完全限定名称。
值：c#、cs、csharp、vb、visualbasic、c++、cpp
默认设置：csharp
缩写形式：/l
说明
对于 Visual Studio 2005 SP1 附带的代码提供程序，此开关只支持 C++。
/mergeConfig
将生成的配置合并到现有文件中，而不是覆盖现有文件。
/messageContract
生成消息协定类型。
缩写形式：/mc
/namespace:<字符串,字符串>
指定从 WSDL 或 XML 架构 targetNamespace 到 CLR 命名空间的映射。 如果为 targetNamespace 使用“*”，则会映射所有 targetNamespace，而不显式映射到该 CLR 命名空间。
为了确保消息协定名称与操作名称不冲突，您应使用 :: 限定类型引用，或确保名称是唯一的。
默认设置：派生自数据协定架构文档的目标命名空间。 默认命名空间用于所有其他生成的类型。
缩写形式：/n
/noConfig
不生成配置文件。
/noStdLib
不引用标准库。
默认设置：引用 Mscorlib.dll 和 System.servicemodel.dll。
/out:<文件>
为生成的代码指定文件名。
默认设置：派生自某个架构的 WSDL 定义名称、WSDL 服务名称或目标命名空间。
缩写形式：/o
/reference:<文件路径>
引用指定程序集中的类型。 在生成客户端时，使用此选项来指定可能包含类型的程序集，这些类型表示所导入的元数据。
无法使用此开关指定消息协定和 XmlSerializer 类型。
如果引用了 DateTimeOffset，则会使用此类型，而不是生成新类型。 如果应用程序是使用 .NET Framework 3.5 编写的，则 SvcUtil.exe 会自动引用 DateTimeOffset。
缩写形式：/r
/serializable
生成用 Serializable 属性标记的类。
缩写形式：/s
/serviceContract（服务协定）
仅生成服务协定的代码 不会生成客户端类和配置
缩写形式：/sc
/serializer:Auto
生成用 Serializable 属性标记的类。
缩写形式：/s
/serializer:DataContractSerializer
生成使用数据协定序列化程序进行序列化和反序列化的数据类型。
缩写形式：/ser:DataContractSerializer
/serializer:XmlSerializer
生成使用 XmlSerializer 进行序列化和反序列化的数据类型。
缩写形式：/ser:XmlSerializer
/targetClientVersion
指定应用程序针对 .NET Framework 的哪个版本。 有效值为 Version30 和 Version35。 默认值为 Version30。
缩写形式：/tcv
Version30 ：如果为使用 WinFX 的客户端生成代码，则使用 /tcv:Version30。
Version35 ：如果为使用 .NET Framework 3.5 的客户端生成代码，则使用 /tcv:Version35。 如果将 /tcv:Version35 与 /async 开关一起使用，则会同时生成基于事件的异步方法和基于回调/委托的异步方法。 此外，还能够支持启用 LINQ 的数据集和DateTimeOffset。
/wrapped
控制是否对具有包装参数的 document-literal 样式的文档使用特殊大小写。 请使用 /wrapped 切换 ServiceModel 元数据实用工具 (Svcutil.exe) 工具来指定正常大小写。
说明
如果服务绑定是系统提供的绑定（请参见系统提供的绑定）之一，并且 ProtectionLevel 属性设置为 None 或 Sign，Svcutil 将使用 <customBinding> 元素（而不是预期的系统提供的元素）生成配置文件。 例如，如果服务使用 ProtectionLevel 设置为 Sign 的 <wsHttpBinding> 元素，则生成的配置在绑定部分中将有<customBinding>，而不是 <wsHttpBinding>。 有关保护级别的更多信息，请参见了解保护级别。
元数据导出
Svcutil.exe 可以导出已编译程序集中服务、协定和数据类型的元数据。 若要导出服务的元数据，您必须使用 /serviceName 选项指定要导出的服务。 若要导出程序集内的所有数据协定类型，应使用 /dataContractOnly 选项。 默认情况下，将为输入程序集中的所有服务协定导出元数据。
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
参数
说明
assemblyPath
指定程序集的路径，该程序集包含要导出的服务、协定或数据协定类型。 可以使用标准命令行通配符提供多个文件作为输入。
选项
说明
/serviceName:<服务配置名称>
指定要导出的服务的配置名称。 如果使用此选项，则必须传递包含关联配置文件的可执行程序集作为输入。 Svcutil.exe 将为服务配置搜索所有关联的配置文件。 如果配置文件包含任何扩展类型，则包含这些类型的程序集必须位于 GAC 中，或者必须使用 /reference 选项显式提供。
/reference:<文件路径>
将指定程序集添加到用于解析类型引用的一组程序集中。 如果要导出或验证使用在配置中注册的第三方扩展（行为、绑定和绑定元素）的服务，请使用此选项找到不在 GAC 中的扩展程序集。
缩写形式：/r
/dataContractOnly
只对数据协定类型进行操作。 不会处理服务协定。
只应为此选项指定本地元数据文件。
缩写形式：/dconly
/excludeType:<类型>
指定要从导出中排除的类型的完全限定或程序集限定名称。 在为服务或一组服务协定导出元数据时，可以使用此选项来防止导出某些类型。 此选项不能与 /dconly 选项一起使用。
如果有包含多个服务的单一程序集，并且每个服务都使用具有相同 XSD 名称的单独的类，则您应为此开关指定服务名称，而不是 XSD 类名称。
不支持 XSD 或数据协定类型。
缩写形式：/et
服务验证
可以使用验证在不承载服务的情况下检测服务实现中的错误。 必须使用 /serviceName 选项指示要验证的服务。
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
参数
说明
assemblyPath
指定程序集的路径，该程序集包含要验证的服务类型。 程序集必须具有相关联的配置文件才能提供服务配置。 可以使用标准命令行通配符来提供多个程序集。
选项
说明
/validate
验证 /serviceName 选项指定的服务实现。 如果使用此选项，则必须传递包含关联配置文件的可执行程序集作为输入。
缩写形式：/v
/serviceName:<服务配置名称>
指定要验证的服务的配置名称。 Svcutil.exe 将为服务配置搜索所有输入程序集的所有关联配置文件。 如果配置文件包含任何扩展类型，则包含这些类型的程序集必须位于 GAC 中，或者必须使用 /reference 选项显式提供。
/reference:<文件路径>
将指定程序集添加到用于解析类型引用的一组程序集中。 如果要导出或验证使用在配置中注册的第三方扩展（行为、绑定和绑定元素）的服务，请使用此选项找到不在 GAC 中的扩展程序集。
缩写形式：/r
/dataContractOnly
只对数据协定类型进行操作。 不会处理服务协定。
只应为此选项指定本地元数据文件。
缩写形式：/dconly
/excludeType:<类型>
指定要从验证中排除的类型的完全限定或程序集限定名称。
缩写形式：/et
元数据下载
可以使用 Svcutil.exe 从运行的服务中下载元数据，并将元数据保存到本地文件。 若要下载元数据，您必须指定 /t:metadata 选项。 否则，将生成客户端代码。 对于 HTTP 和 HTTPS URL 方案，Svcutil.exe 会尝试使用 WS-Metadata Exchange 和 DISCO 检索元数据。 对于所有其他 URL 方案，Svcutil.exe 只使用 WS-Metadata Exchange。
Svcutil 会同时发出以下元数据请求以检索元数据。
针对所提供地址的 MEX (WS-Transfer) 请求
针对所提供地址的 MEX 请求（附加有 /mex）
针对所提供地址的 DISCO 请求（使用 ASMX 中的 DiscoveryClientProtocol）。
默认情况下，Svcutil.exe 使用 MetadataExchangeBindings 类中定义的绑定进行 MEX 请求。 若要配置用于 WS-Metadata Exchange 的绑定，您必须在使用 IMetadataExchange 协定的配置中定义一个客户端终结点。 可以在 Svcutil.exe 的配置文件中定义此终结点，也可以在使用 /svcutilConfig 选项指定的另一个配置文件中定义。
svcutil.exe /t:metadata <url>* | <epr>
参数
说明
url
可提供元数据的服务终结点的 URL，或是联机承载的元数据文档的 URL。
epr
XML 文件的路径，该文件包含支持 WS-Metadata Exchange 的服务终结点的 WS-Addressing EndpointReference。
XmlSerializer 类型生成
如果服务和客户端应用程序使用可用 XmlSerializer 进行序列化的数据类型，则会在运行时生成并编译这些数据类型的序列化代码，从而导致启动性能降低。
说明
预生成的序列化代码只能在客户端应用程序中使用，不能在服务中使用。
Svcutil.exe 可依据应用程序的已编译程序集生成必要的 C# 序列化代码，因而可提高这些应用程序的启动性能。 有关更多信息，请参见如何：使用 XmlSerializer 改善 WCF 客户端应用程序的启动时间。
说明
Svcutil.exe 只会为输入程序集中的服务协定使用的类型生成代码。
svcutil.exe /t:xmlSerializer <assemblyPath>*
参数
说明
assemblyPath
指定包含服务协定类型的程序集的路径。 为每个协定中的所有 Xml 可序列化类型生成序列化类型。
选项
说明
/reference:<文件路径>
将指定程序集添加到用于解析类型引用的一组程序集中。
缩写形式：/r
/excludeType:<类型>
指定要从导出或验证中排除的类型的完全限定或程序集限定名称。
缩写形式：/et
/out:<文件>
为生成的代码指定文件名。 如果将多个程序集作为输入传递到工具，则会忽略此选项。
默认设置：派生自程序集名称。
缩写形式：/o
/UseSerializerForFaults
指定应该使用 XmlSerializer（而不是默认的 DataContractSerializer）来读取和写入错误。
示例
最大名称表字符计数配额
使用 svcutil 生成服务的元数据时，您会收到以下消息：
错误: 无法从 http://localhost:8000/somesservice/mex 获取元数据。 读取 XML 数据时，超出最大名称表字符计数配额(16384)。 名称表是用于存储在处理 XML 时所遇到的字符串的数据结构 - 具有非重复元素名称、特性名称和特性值的长 XML 文档可能会触发此配额。 通过更改在创建 XML 读取器时所使用的 XmlDictionaryReaderQuotas 对象的 MaxNameTableCharCount 属性，可增加此配额。
如果您请求某个服务的元数据时返回大 WSDL 文件，则该服务会导致此错误。 问题在于超过了 svcutil.exe 工具的字符配额。 设置此值是为了帮助防止遭受拒绝服务 (dos) 攻击。 您可以通过为 svcutil 指定下面的配置文件来增加此配额。
下面的配置文件演示如何设置 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 示例代码复制到该文件中。然后将该文件放到与 svcutil.exe 相同的目录中。下次运行 svcutil.exe 时，它会选取新的设置。
安全问题
您应使用适当的访问控制列表 (ACL) 来保护 Svcutil.exe 的安装文件夹、Svcutil.config 以及 /svcutilConfig 所指向的文件。 这样可以防止恶意扩展注册并运行。
此外，为了将安全性受到危害的可能性降到最低，您不应在系统中添加不受信任的扩展，或将不受信任的代码提供程序用于 Svcutil.exe。
最后，您不应在应用程序的中间层中使用该工具，因为它可能会导致当前进程拒绝服务。
请参见
任务
如何：创建 Windows Communication Foundation 客户端
参考
DataContractAttribute
DataMemberAttribute
ServiceModel 元数据实用工具 (Svcutil.exe)