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

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

SvcUtil.exe

ServiceModel 元数据实用工具可在 Windows SDK 安装位置中找到，具体位置为 %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin。

功能

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

超时

该工具在检索元数据时有 5 分钟的超时。 此超时仅适用于通过网络检索元数据的操作。 它不适用于该元数据的任何处理操作。

多目标

该工具不支持多目标。 如果要通过 svcutil.exe 生成 .NET Framework 4 工件，请使用 .NET Framework 4 SDK 中的 svcutil.exe。 若要生成 .NET Framework 3.5 工件，请使用 .NET Framework 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

常见用法

下表显示了此工具的一些常用选项：

代码生成

Svcutil.exe 可以依据元数据文档为服务协定、客户端和数据类型生成代码。 这些元数据文档可以位于持久存储区上，也可以联机检索。 联机检索采用 WS-Metadata Exchange 协议或 DISCO 协议（有关详细信息，请参见“元数据下载”一节）。

可以使用 SvcUtil.exe 工具生成基于预定义 WSDL 文档的服务和数据协定。 使用 /serviceContract 开关并指定可以从中下载或找到 WSDL 文档的 URL 或文件位置。 这将生成在 WSDL 文档中定义的服务和数据约定，然后它们可以用来实现投诉服务。 有关详细信息，请参阅如何：检索元数据并实现符合标准的服务。

而对于使用 BasicHttpContextBinding 终结点的服务，Svcutil.exe 将生成 allowCookies 属性设置为 true 的 BasicHttpBinding。 Cookie 用于服务器上的上下文。 如果在服务使用 Cookie 时，你要管理客户端上的上下文，则可以手动修改配置以使用上下文绑定。

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

元数据导出

Svcutil.exe 可以导出已编译程序集中服务、协定和数据类型的元数据。 若要导出服务的元数据，您必须使用 /serviceName 选项指定要导出的服务。 若要导出程序集内的所有数据协定类型，应使用 /dataContractOnly 选项。 默认情况下，将为输入程序集中的所有服务协定导出元数据。

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

服务验证

可以使用验证在不承载服务的情况下检测服务实现中的错误。 必须使用 /serviceName 选项指示要验证的服务。

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

元数据下载

可以使用 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>

XmlSerializer 类型生成

如果服务和客户端应用程序使用可用 XmlSerializer 进行序列化的数据类型，则会在运行时生成并编译这些数据类型的序列化代码，从而导致启动性能降低。

Svcutil.exe 可依据应用程序的已编译程序集生成必要的 C# 序列化代码，因而可提高这些应用程序的启动性能。 有关详细信息，请参阅如何：使用 XmlSerializer 改善 WCF 客户端应用程序的启动时间。

svcutil.exe /t:xmlSerializer <assemblyPath>*

示例

以下命令将依据运行的服务或联机元数据文档生成客户端代码。

svcutil http://service/metadataEndpoint

以下命令将依据本地元数据文档生成客户端代码。

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

以下命令将依据本地架构文档用 Visual Basic 生成数据协定类型。

svcutil /dconly *.xsd /language:VB

以下命令从运行的服务中下载元数据文档。

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

以下命令为程序集中的服务协定和关联的类型生成元数据文档。

svcutil myAssembly.dll

以下命令为程序集中的服务以及所有关联的服务协定和数据类型生成元数据文档。

svcutil myServiceHost.exe /serviceName:myServiceName

以下命令为程序集中的数据类型生成元数据文档。

svcutil myServiceHost.exe /dconly

以下命令验证服务主机。

svcutil /validate /serviceName:myServiceName myServiceHost.exe

以下命令为程序集中任何服务协定使用的 XmlSerializer 类型生成序列化类型。

svcutil /t:xmlserializer myContractLibrary.exe

最大名称表字符计数配额

使用 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。

最后，您不应在应用程序的中间层中使用该工具，因为它可能会导致当前进程拒绝服务。

另请参阅

• DataContractAttribute
• DataMemberAttribute
• 如何：创建客户端