ServiceModel 元数据实用工具 (Svcutil.exe)

ServiceModel 元数据实用工具用于依据元数据文档生成服务模型代码，以及依据服务模型代码生成元数据文档

一、SvcUtil.exe

ServiceModel 元数据实用工具可在 Windows SDK 安装位置中找到，具体位置为 C:Program FilesMicrosoft SDKsWindowsv6.0Bin

功能

下表概括了此工具提供的各种功能，以及论述如何使用该工具的对应主题。

任务	主题
依据运行的服务或静态元数据文档生成代码	根据服务元数据生成 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