创建 XML Web services 代理

项目
02/28/2011

本主题专门介绍一项旧有技术。现在应通过使用以下链接来创建 XML Web 服务和 XML Web 服务客户端： Windows Communication Foundation.

按照定义，可以使用包括 SOAP 在内的行业标准协议通过网络与 Web 服务通信。也就是说，客户端与 Web 服务使用 SOAP 消息进行通信，这些消息将 in 和 out 参数作为 XML 封装。幸运的是，对于 Web 服务客户端，将参数映射至 XML 元素、然后通过网络发送 SOAP 消息的工作由代理类进行处理。

只要服务说明存在并且符合 Web 服务描述语言 (WSDL)，就可以生成代理类。服务说明定义与 Web 服务进行通信的方式。依据服务说明，可以使用 Wsdl.exe 工具创建代理类。随后，Web 服务客户端便可以调用该代理类的方法，这些方法通过处理发往和来自 Web 服务的 SOAP 消息来通过网络与该 Web 服务进行通信。由于代理类通过 Internet 与 Web 服务通信，因此最好验证该代理类的 Url 属性是否引用受信任的目标。

默认情况下，代理类使用 SOAP over HTTP 与 Web 服务通信。但是，Wsdl.exe 可以生成使用 HTTP-GET 协议或 HTTP-POST 协议与 Web 服务通信的代理类。若要指定该代理类应使用 HTTP-GET 或 HTTP-POST，请向 Wsdl.exe 工具提供 /protocol 开关，如下表所述。

使用 Wsdl.exe 生成 XML Web services 代理类

可以使用 Web 服务描述语言工具 (Wsdl.exe) 从命令提示符处创建代理类，并（至少）指定 Web 服务或服务说明的 URL，或者指定已保存的服务说明的路径。

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

注意：
此处列出的参数是 Wsdl.exe 的常用参数。有关 Wsdl.exe 的完整语法，请参见 Web 服务描述语言工具 (Wsdl.exe)。

参数	值
<URL 或路径>	服务说明的 URL 或路径，服务说明是一个用 Web 服务描述语言描述 Web 服务的文件。如果指定一个文件，请提供包含服务说明的文件。例如： mywebservice.wsdl 如果指定 URL，该 URL 必须引用 .asmx 页面或者返回服务说明。对于使用 ASP.NET 创建的 Web 服务，可以通过向 Web 服务的 URL 追加 ?WSDL 来返回服务说明。例如： https://www.contoso.com/MyWebService.asmx?WSDL。
/language:语言	生成代理类时使用的语言，可用选项包括 CS、VB 和 JS，它们分别指代 C#、Visual Basic .NET 和 JScript .NET。默认语言是 C#。（可选）
/protocol:协议	用来与 Web 服务方法进行通信的协议。可用选项包括 SOAP、HTTP-GET 和 HTTP-POST。默认协议是 SOAP。（可选）
/namespace:我的命名空间	生成的代理的命名空间。默认值是全局命名空间。（可选）
/out:文件名	要创建的包含代理类的文件的名称。默认名称基于实现该 Web 服务的类的名称。（可选）
/username:用户名	连接到要求身份验证的 Web 服务器时要使用的用户名。（可选）
/password:密码	连接到要求身份验证的 Web 服务器时要使用的密码。（可选）
/domain:域	连接到要求身份验证的 Web 服务器时要使用的域。（可选）

生成的代理类的详细信息

当使用 Wsdl.exe 生成代理类时，会用指定的语言生成一个源文件。此文件包含一个代理类，该代理类为 Web 服务的每个 Web 服务方法公开同步和异步方法。例如，如果某个 Web 服务包含一个名为 Add 的 Web 服务方法，代理类将具有以下方法用来调用 Web 服务方法 Add：Add、BeginAdd** 和 EndAdd。代理类的 Add 方法用来与 Web 服务方法 Add 进行同步通信，而 BeginAdd 和 EndAdd 方法用来与 Web 服务方法进行异步通信。有关与 Web 服务方法进行异步通信的更多信息，请参见与 XML Web services 进行异步通信。

所生成的代理类的每种方法都包含相应的代码，以便与 Web 服务方法进行通信。如果在与 Web 服务和代理类进行通信的过程中发生错误，则将引发一个异常。有关如何处理异常的更多信息，请参见在 XML Web services 中处理和引发异常。

在 Web 服务方法与代理类的关联方法之间，定义的参数顺序可能不同。在大多数情况下参数顺序都匹配。但是，如果 Web 服务需要 Document 格式的 SOAP 消息，则会出现一种参数顺序不匹配的情况。如果 Web 服务方法在定义 in 参数之前定义了 out 参数，则在代理类中 out 参数将放在所有 in 参数之后。例如，在下面的代码示例中，Web 服务方法 MyWebMethod 在声明 in 参数 inStr 之前先声明了 out 参数 outStr。但是，在代理类中，inStr 参数先于 outStr 参数声明。

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

在某些情况下，Wsdl.exe 生成的代理类使用最小公分母方式将对象强制转换为服务说明中指定的类型。因此，代理类中的生成类型可能不是开发人员想要或预期的类型。例如，当 Wsdl.exe 遇到服务说明中的 ArrayList 类型时，它会在生成的代理类中创建一个 Object 数组。若要确保对象类型强制转换正确，请打开包含生成的代理类的文件，然后将所有不正确的对象类型更改成所需的对象类型。

Wsdl.exe 引发的警告

向 Wsdl.exe 提供多个服务说明时，可能会引发下面的两条错误消息：

警告：忽略来自位置 <架构 URI>、具有 TargetNamespace=<架构命名空间> 的重复服务说明。

指示所提供的两个或更多个服务说明的 TargetNamespace 是相同的。由于 TargetNamespace 应该是特定 XML 文档（在此情况下是服务说明）的唯一标识符，因此 Wsdl.exe 假定两个服务说明是相同的。进行该假定后，Wsdl.exe 仅为其中一个服务说明生成一个代理类。如果这不是您想要的结果，您可以更改此结果。对于表示用 ASP.NET 创建的 Web 服务的服务说明，可以将指定唯一 Namespace 属性的 WebService 特性应用于实现 Web 服务的类。之后，该 Namespace 属性在服务说明中作为 TargetNamespace 来唯一地标识该 Web 服务。
警告：忽略来自位置 <架构 URI>、具有 TargetNamespace=<架构命名空间> 的重复架构。

指示在提供的服务说明中有两个或更多个 XML 架构的 TargetNamespace 相同。由于 TargetNamespace 应该是特定 XML 文档（在此情况下是 XML 架构）的唯一标识符，因此 Wsdl.exe 假定两个 XML 架构是相同的。进行该假定后，Wsdl.exe 仅为其中一个架构生成一个类。如果这不是想要的结果，必须将每个 XML 架构的 TargetNamespace 更改为唯一的 URI。TargetNamespace 的确切修改方式取决于特定 XML 架构的来源。

另请参见

Share via