Web 服务编译器工具

项目
06/13/2023

为了支持服务模型，wsutil.exe会生成要同时在客户端和服务端中使用的标头。它根据需要为客户端生成 C 代理文件，为服务端生成 C 存根文件。

为了支持序列化，编译器为全局元素定义的元素说明生成标头，以及代理文件中要由序列化引擎使用的所有类型定义信息。

使用情况

WsUtil.exe [命令行开关 [switch-options]：]<filename>

command-line-开关

指定WsUtil.exe编译器选项。开关可以按任意顺序显示。短划线 ('-') 和斜杠 ('/') 被视为相同。

命令行选项列表

@filename 指定应将输入文件视为响应文件。此选项可以在参数列表的任何位置多次使用。
/wsdl：<filename>：<optional_url> 指定应将输入文件视为 wsdl 文件。允许多个 wsdl 输入，并处理所有指定的 wsdl 文件。 optional_url指定从中检索元数据的位置。如果未指定optional_url，Wsutil 会在内部生成唯一 URL。另请参阅策略支持。
/xsd：<filename> 指定应将输入文件名视为架构文件。允许多个 xsd 输入，并处理所有指定的架构文件。
/wsp：<filename>：<optional_url> 指定应将输入文件名视为策略元数据。允许多个 wsp 输入，并处理所有指定的策略文件。 optional_url指定从中检索元数据的位置。如果未指定optional_url，Wsutil 会在内部生成唯一 URL。如果指定了 /nopolicy 标志，则会忽略策略文件。另请参阅策略支持。
/nopolicy 禁用策略处理。
/out：<dirname> 指定输出文件的目录名称
/noclient 不生成客户端存根。
/noservice 不生成服务端存根。
/prefix：<string> 将指定的字符串追加到所有生成的标识符。
/fullname 将规范化文件名追加到生成的标识符。默认情况下，仅使用“name”属性中指定的名称来生成相关说明的标识符。
/string：<WS_STRING>|<WCHAR*> 默认情况下，wsutil 为 xsd：string 类型生成 WCHAR* 。应用程序可以使用此标志覆盖该行为，并改为为 xsd：type 生成WS_STRING。
/help 显示帮助消息
/? 与 /help 相同
/W：x 错误处理选项。可以是 W：0-W：4 |Wx
/nologo 不生成有关控制台输出的编译器特定信息。
/nostamp 不生成有关生成的文件的编译器特定信息。

默认情况下，编译器为 WSDL 文件或从元数据交换返回的 WSDL 生成以下文件：

客户端代理 ({inputfilename}.c)
服务存根 ({inputfilename}.c)
头文件 ({inputfilename}.h)

生成的文件名的根是输入文件名。保留原始输入文件扩展名以防止生成的文件的文件名冲突。默认情况下，客户端和服务存根在同一文件中生成，服务存根代码在代理代码之后生成。

默认情况下，编译器为从元数据交换返回的架构的 XSD 文件生成以下文件：
序列化说明 ({inputfilename}.c)
头文件 ({inputfilename}.h)

文件名的根是服务名称。

Wsutil.exe在所有生成的文件的开头生成“标记”部分，指示编译器选项、工具版本、命令行选项适用等。可以使用 /nostamp 选项关闭此部分，以避免与生成的文件进行比较时产生干扰。

Wsutil 不支持下载元数据

Wsutil 编译器仅适用于本地元数据文件。该工具不支持从正在运行的 Web 服务下载元数据。开发人员可以使用其他受支持的 Web 服务工具（如 svcutil）将元数据下载到本地计算机、检查保存的文件，并将这些文件传递到wsutil.exe进行编译。

多输入/输出文件支持

WSDL 和 XML 架构允许从其他位置/文件中指定的其他名称空间包含/导入定义。 Wsutil 支持多个 schema/wsdl/policy 输入，并为每个输入文件生成一组存根/标头。 Wsutil 不遵循 include 和 import 语句。相反，应用程序应将包含所有必要命名空间的文件传递到 wsutil，以便该工具可以在编译期间解析所有依赖项。

WsUtil.exe /xsd：stockquote.xsd /wsdl：stockquote.wsdl /wsdl：stockquoteservice.wsdl

wsutil 生成三组输出文件：

stockquote.xsd.c stockquote.xsd.h
stockquote.wsdl.c stockquote.wsdl.h
stockquoteservice.wsdl.h stockquoteservices.wsdl.c

输出文件格式

对于每个输出文件，wsutil 会在头文件中生成外部可用的定义。除 C 结构定义和存根函数原型外，所有其他 Web 服务相关定义都封装在名为的全局结构中，具有规范化文件名。

typedef struct _stockquote_wsdl {
  struct {
  ... // list of WS_STRUCT_DESCRIPTION for all global complex types.
  } globalTypes;
  struct {
  ... // WS_ELEMENT_DESCRIPTION for all global elements.
  } globalElements;
  struct {
  ...
  } messages;
  struct {
  ...
  } contracts;
} _stockquote_wsdl;

EXTERN_C _stockquote_wsdl stockquote_wsdl;

请注意，并非所有字段都是为全局结构生成的。仅当在输入文件中指定了相关定义时，才会生成顶级字段。例如，不会为 xsd 文件生成消息、操作和协定字段。

警告级别和错误级别

与 C 编译器类似，WsUtil.exe支持四个警告级别和一个错误级别：

WsUtil.exe会生成具有不可恢复故障的错误，例如 wsdl 文件无效、编译器选项无效等。
WsUtil 生成 W1 警告，其中包含严重的可恢复问题。编译器可以进行，但用户应注意此问题。例如，如果 wsdl 中存在不影响代码生成的不受支持的属性（例如某些 WSDL 方面），则会生成 W1 警告。
WsUtil 生成具有不太严重问题的 W2 警告。功能不会丢失，但应用程序开发人员可能想知道这一点。喜欢可能不同于其他平台的行为。
WsUtil 生成 W3 警告，对生成的代码的影响最小。例如，当规范化字符串不同于原始字符串时，wsutil.exe会生成 W3 警告。
W4 警告更像是“信息性”警告，WsUtil 在 WSDL 中忽略文档属性等情况下发出 W4。
WX 指示编译器将警告视为错误。例如，如果指定了 /W：1 /WX，wsutil 会为所有 W1 警告生成错误。

/W：{N} 指定应生成哪个级别的警告消息。 /W：1 表示应生成警告级别 1 警告，应屏蔽警告级别 2 及更低级别的警告，而不是由该工具生成。

/fullname

此选项指示WsUtil.exe为标识符生成全名，以避免潜在的名称冲突。例如，在 example.xsd 中，我们有：

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://Example.org" 
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" targetNamespace="http://Example.org" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
 <wsdl:types>
  <xs:element name="SimpleStruct">
   <xs:complexType>
    <xs:sequence>
     <xs:element name="a" type="xs:int" />
     <xs:element name="b" type="xs:int" />
    </xs:sequence>
   </xs:complexType>
  </xs:element>
 </wsdl:types>
</wsdl:definitions>

默认情况下，WsUtil.exe生成：

typedef struct SimpleStruct {
  int a;
  int b;
};

但是，如果指定了 /fullname 命令行选项，WsUtil.exe会改为生成以下结构定义：

typedef struct exmaple_xsd_SimpleStruct {
  int a;
  int b;
};

全球化

该工具与语言无关，可以本地化为不同的语言。所有错误消息/控制台输出都可以本地化。但是，命令行选项仍为英语。

环境变量

WsUtil.exe不使用任何环境变量。

平台独立

WsUtil.exe的输出文件与平台无关。存根中没有生成任何与体系结构相关的代码;任何特定于体系结构的内容都将由 C 编译器处理。存根可用于我们支持的所有平台。

有关wsutil.exe输出的说明，请参阅 WSDL 支持和架构支持部分。

通过

Web 服务编译器工具

/fullname

全球化

环境变量

平台独立

反馈

其他资源