爱华网欢迎来到 MSDN > Windows 开发
Windows XP 中的 SOAP 客户端概述
发布日期： 7/12/2004 | 更新日期： 7/12/2004
Roger Wolter
Microsoft Corporation
摘要：本文包含了使用 Microsoft Windows XP Professional 中随附的 SOAP 客户端软件来访问使用 SOAP 的 Web 服务的基础知识。本文首先简要介绍了 SOAP 和 WSDL 标准，然后讨论如何实现与启用 SOAP 的 Web 服务进行通讯的客户端。
本页内容
简介
什么是 SOAP？
什么是 WSDL？
构建简单的客户端应用程序
后面的步骤
SOAPClient 对象
简介
Microsoft Windows XP Professional 包含 Microsoft SOAP Toolkit 2.0 的客户端部分，它可以构建 SOAP 客户端应用程序或将应用程序分配给 Windows XP Professional 客户端，而无需分配 SOAP Toolkit 2.0 的客户端部分。本文包含了使用 Windows XP 中随附的 SOAP 客户端软件来访问使用 SOAP 的 Web 服务的基础知识。本文首先简要介绍了 SOAP 和 Web 服务描述语言 (WSDL) 标准，然后讨论如何实现与启用 SOAP 的 Web 服务进行通讯的客户端。
返回页首
什么是 SOAP？
SOAP 是简单对象访问协议的简称，由 http://www.w3.org/TR/SOAP 上的 SOAP 标准进行定义。SOAP 协议定义了用于在系统之间进行通讯的标准 XML 消息的格式。由于该消息格式已标准化并基于 XML 标准，因此可使用 SOAP 在多种计算机体系结构、语言和操作系统之间进行通讯。SOAP 启用了一类新的应用程序，称为 Web 服务，Web 服务以一种标准的方式公开服务，以便应用程序开发人员可以通过将 Web 上来自许多不同源的服务组合到一起，从而创建新的应用程序。
SOAP 规范涵盖了四个主要部分：一个必需的 SOAP 信封格式，定义了包围 SOAP 消息的 XML 内容的信封的外观；一组可选的编码规则，定义了如何将语言类型映射到 SOAP 消息中的 XML（由于这在此规范的第 5 节中定义，因此称为“Section 5 编码”）；一个可选的 RPC 格式，定义了函数调用在 SOAP 消息中的表达方式；一个 HTTP 绑定，定义了如何通过 HTTP 交换 SOAP 消息。HTTP 是该标准定义的唯一通讯协议绑定；因此，几乎所有的 SOAP 实现都包含 HTTP 绑定。请注意，SOAP 并不限制可用于传输 SOAP 消息的其他通讯协议。
以下是一个简单的 SOAP 消息：
<?xml version="1.0" encoding="UTF-8" standalone="no"?><SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAPSDK1:Add xmlns:SOAPSDK1="http://tempuri.org/message/"> <a>333</a> <b>888</b> </SOAPSDK1:Add> </SOAP-ENV:Body></SOAP-ENV:Envelope>
让我们仔细研究一下此消息，以了解 SOAP 消息的格式。第一行是定义 SOAP 文档中使用的字符集的 XML 声明。Envelope 元素是必需的元素，它始终是 SOAP 消息的根，并始终位于“http://schemas.xmlsoap.org/soap/envelope/”命名空间中。
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 属性定义了该消息中使用的编码样式。在此例中，使用了标准的 Section 5 编码。Envelope 元素的 Body 子元素中包含 SOAP 消息。正如 SOAP 规范的第 7 节中定义的那样，Add 元素表示对名为 Add 的操作的调用。Add 的子元素是 Add 方法调用的参数。
对该消息的响应如下所示：
<?xml version="1.0" encoding="UTF-8" standalone="no"?><SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAPSDK1:AddResponse xmlns:SOAPSDK1="http://tempuri.org/message/"> <Result>1221</Result> </SOAPSDK1:AddResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>返回页首
什么是 WSDL？
WSDL 是 Web 服务定义语言的简称。若要成功调用一个 Web 服务，您需要了解如何获得该服务，该服务支持哪些操作，该服务需要哪些参数，以及该服务所返回的内容。WSDL 在一个可被读取或可由机器处理的 XML 文档中提供所有这些信息。
为了解 WSDL 文件的格式，我们来分析一下以下 WSDL 文件：
<?xml version="1.0" encoding="UTF-8" ?> <definitions name="net.xmethods.services.currencyexchange.CurrencyExchange"targetNamespace="http://www.themindelectric.com/wsdl/net.xmethods.services.currencyexchange.CurrencyExchange/" xmlns:tns="http://www.themindelectric.com/wsdl/net.xmethods.services.currencyexchange.CurrencyExchange/"xmlns:electric="http://www.themindelectric.com/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"><message name="getRateRequest1"> <part name="country1" type="xsd:string" /> <part name="country2" type="xsd:string" /> </message><message name="getRateResponse1"> <part name="Result" type="xsd:float" /> </message><portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType"> <operation name="getRate" parameterOrder="country1 country2"> <input message="tns:getRateRequest1" /> <output message="tns:getRateResponse1" /> </operation></portType><binding name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding" type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType"><soap:bindingtransport="http://schemas.xmlsoap.org/soap/http" /> <operation name="getRate"> <soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" /> <input> <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </input> <output> <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </output> </operation></binding><service name="net.xmethods.services.currencyexchange.CurrencyExchangeService"> <documentation> net.xmethods.services.currencyexchange.CurrencyExchange web service </documentation> <port name="net.xmethods.services.currencyexchange.CurrencyExchangePort" binding="tns:net.xmethods.services.currencyexchange. CurrencyExchangeBinding"> <soap:address location="http://206.135.115.109:9090/soap" /> </port></service></definitions>
这是在 Mind Electric 的 Glue 中实现汇率服务的 WSDL 文件。因此，该格式不同于 Microsoft SOAP Toolkit WSDL 文件，但它是兼容的。WSDL 文件的第一个元素是 definitions 元素，它是文件的根元素且通常包含几个命名空间声明：
<definitions name="net.xmethods.services.currencyexchange.CurrencyExchange"targetNamespace="http://www.themindelectric.com/wsdl/ net.xmethods.services.currencyexchange.CurrencyExchange/"xmlns:tns="http://www.themindelectric.com/wsdl/ net.xmethods.services.currencyexchange.CurrencyExchange/"xmlns:electric="http://www.themindelectric.com/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"></definitions>
请注意，xsd 命名空间是 2001 版的。SOAP 工具包默认为 2001 Recommendation 版的 XSD 架构命名空间，但它可以理解以旧版命名空间编写的 WSDL 文件。
如果 WSDL 使用了任何复杂类型，则这些类型的 XSD 架构定义将包含在<types></types> 元素中。由于该 WSDL 文件未使用任何复杂类型，因此没有该元素。
下一部分定义了由该 WSDL 中定义的服务所使用的消息：
<message name="getRateRequest1"> <part name="country1" type="xsd:string" /> <part name="country2" type="xsd:string" /> </message><message name="getRateResponse1"> <part name="Result" type="xsd:float" /> </message>
方法参数的名称和数据类型在此处定义。
portType 元素定义了上一部分中定义的消息和使用它们的操作之间的映射：
<portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType"> <operation name="getRate" parameterOrder="country1 country2"> <input message="tns:getRateRequest1" /> <output message="tns:getRateResponse1" /> </operation></portType>
binding 元素定义了 portType 元素中定义的抽象操作和它们在 SOAP 中的实现方式之间的绑定。这是一个独立元素，因为 WSDL 可以定义其他非 SOAP 协议。这里需要注意几点： 表示该消息使用 SOAP 标准的第 7 节中定义的 rpc 规则。如果指定，则 SOAP 消息的内容将为 XML 文档。transport 属性表示 SOAP 消息将以 SOAP HTTP 消息的形式发送，soapAction 属性定义了 HTTP 包中 soapAction 标头的内容，use="encoded" 属性表示参数值使用了 SOAP Section 5 编码。
<binding name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding"type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType"><soap:binding transport="http://schemas.xmlsoap.org/soap/http" /> <operation name="getRate"> <soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" /> <input> <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </input> <output> <soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </output> </operation></binding>
service 元素将 SOAP 绑定与服务的物理实现联系在一起。服务的 URL 就是在此处定义的。请注意，此服务的端口是 9090 — SOAP 不只是通过端口 80 工作。（如果您的防火墙要求您使用端口 80，则该服务还有一个副本运行在端口 80 上。）
<service name="net.xmethods.services.currencyexchange.CurrencyExchangeService"> <documentation> net.xmethods.services.currencyexchange.CurrencyExchange web service </documentation> <port name="net.xmethods.services.currencyexchange.CurrencyExchangePort" binding="tns:net.xmethods.services. currencyexchange.CurrencyExchangeBinding"> <soap:address location="http://206.135.115.109:9090/soap" /> </port></service>返回页首
构建简单的客户端应用程序
本部分将详细介绍使用 Windows XP 中随附的 SOAP 客户端来构建简单 SOAP 应用程序的过程。示例中使用的 Web 服务是 XMethods 站点上的外汇汇率服务，该服务是可用的 SOAP 服务的联机列表。
该服务可接受两个国家/地区作为参数，并返回它们之间的汇率。描述该服务的 WSDL 文件位于以下位置：http://www.xmethods.net/sd/CurrencyExchangeService.wsdl。
使用高级别 SOAP API 调用此 SOAP 方法所需的步骤如下：创建一个 SOAPClient 对象，用 WSDL 文件初始化该 SOAPClient 对象，然后调用该方法。
以下是完成此操作的简单 VBScript 代码：
dim SOAPClientset SOAPClient = createobject("MSSOAP.SOAPClient")on error resume nextSOAPClient.mssoapinit("http://www.xmethods.net/sd/CurrencyExchangeService.wsdl") if err then wscript.echo SOAPClient.faultString wscript.echo SOAPClient.detail end ifwscript.echo SOAPClient.getRate("England","Japan") if err then wscript.echo SOAPClient.faultString wscript.echo SOAPClient.detail end if
三行加粗的代码行对应于上面提到的三个步骤。mssoapinit 的参数是一个 WSDL 文件规范，该参数可以是一个 URL（如果该 WSDL 文件位于远程系统上），也可以是一个文件路径（如果该 WSDL 文件位于本地机器上）。本地 WSDL 文件更为高效，这是因为检索文件不需要通过网络往返行程。此外，还可以更轻松地管理在使用时加载到所有客户端的单个 WSDL 文件。
要运行该 SOAP 方法，请将此代码键入名为“currency.vbs”的文件，然后用“cscript currency.vbs”执行它。结果如下所示：
C:SOAPDemo>cscript currency.vbsMicrosoft (R) Windows Script Host Version 5.1 for WindowsCopyright (C) Microsoft Corporation 1996-1999. All rights reserved.173.9434
您应该能够轻松地将此代码应用到 VB、C++ 或其他任何已启用 COM 的语言中。以下是在 VB 中实现的同一服务：
Private Sub Form_Load() Dim SOAPClient As SOAPClient Set SOAPClient = New SOAPClient On Error GoTo SOAPError SOAPClient.mssoapinit _ ("http://services.xmethods.net/soap/urn:xmethods-CurrencyExchange.wsdl") MsgBox Str(SOAPClient.getRate("England", "Japan")), _ vbOKOnly, "Exchange Rate"Exit SubSOAPError: MsgBox SOAPClient.faultstring + vbCrLf + SOAPClient.detail, vbOKOnly,_ "SOAP Error"End Sub
注： Windows XP 中随附的 SOAPClient 的版本不适于在 ASP 应用程序中运行。要在 ASP 应用程序中运行 SOAPClient，您必须下载完整版的 SOAP Toolkit 2.0。
返回页首
后面的步骤
现在，您已经了解了如何使用 Windows XP 中的 SOAP 来构建 Web 服务客户端应用程序，您可能希望扩展自己的 SOAP 知识并构建自己的 Web 服务。您可以借助于以下两个较好的信息源：http://msdn.microsoft.com/soap/ 和 http://msdn.microsoft.com/webservices/。这些站点包含指向 SOAP 信息、白皮书、其他 SOAP 站点以及下载页的链接，您可以从下载页下载完整的 SOAP Toolkit 2.0 以开始构建自己的 Web 服务应用程序。请注意，当您安装完整版时，将看到几条警告，报告由于系统文件保护而无法覆盖当前文件。您可以安全地忽略这些错误。您还可以访问 XMethods 并尝试那里的更多服务 — 您只需记住，为了让 SOAP 工具包正常工作，服务必须提供 WSDL 文件。
返回页首
SOAPClient 对象
本部分回顾了由 SOAPClient 对象公开的对象模型，并描述了由 SOAPClient 公开的每个方法和属性。有关详细信息，请参阅 http://msdn.microsoft.com/soap/。
本页内容
简介
什么是 SOAP？
什么是 WSDL？
构建简单的客户端应用程序
后面的步骤
SOAPClient 对象
Mssoapinit 方法
mssoapinit 方法使用 Web 服务描述语言 (WSDL) 文件作为输入来初始化 SOAPClient 对象。在初始化过程中，所标识服务中的所有操作都绑定到 SOAPClient 对象。因此，您可以使用 SOAPClient 对象来调用该服务中定义的操作。
方法定义
HRESULT mssoapinit( [in] BSTR bstrWSDLFile, [in, optional, defaultvalue("")] BSTR bstrServiceName, [in, optional, defaultvalue("")] BSTR bstrPort, [in, optional, defaultvalue("")] BSTR bstrWSMLFile);
参数
bstrWSDLFile bstrWSDLFile 是用于描述服务器所提供服务的 WSDL 文件的 URL。
bstrServiceName
bstrServiceName 是WSDL 文件（包含简单对象访问协议 (SOAP) 请求中指定操作）中的可选服务。如果该参数缺失、为空或是空字符串，则在初始化 SOAPClient 对象时，mssoapinit 方法将使用指定 WSDL 文件中的第一个服务。
bstrPort
bstrPort（也是可选的）是包含 SOAP 请求中指定操作的 WSDL 文件中的端口名称。如果该参数缺失、为空或是空字符串，则在初始化 SOAPClient 对象时，mssoapinit 方法将使用指定服务中的第一个端口。
bstrWSMLFile（也可选）是 Web 服务元语言 (WSML) 文件的 URL。该参数仅在使用自定义类型映射器时才是必需的。
Visual Basic 语法
Sub mssoapinit(bstrWSDLFile As String,_ [bstrServiceName As String],_ [bstrPort As String],_ [bstrWSMLFile As String])
Visual Basic 示例
set soapclient = CreateObject("MSSOAP.SOAPClient") call soapclient.mssoapinit("DocSample1.wsdl", "", "", "")wscript.echo soapclient.AddNumbers(2,3)wscript.echo soapclient.SubtractNumbers(3,2)
备注
mssoapinit 方法是客户端高级别 API 的一部分。要使用此方法，您必须首先在客户端上创建 SOAPClient 对象。然后，使用 WSDL 文件的名称、服务名称和端口名称作为参数来调用 mssoapinit 方法。现在，客户端可以针对所请求的服务或端口来调用 WSDL 文件中定义的任何操作。
ClientProperty 属性
ClientProperty 属性设置和检索特定于 SOAPClient 对象的属性。
方法定义
[propget] HRESULT ClientProperty( [in] BSTR PropertyName, [out, retval] VARIANT* pPropertyValue);[propput] HRESULT ClientProperty( [in] BSTR PropertyName, [in] VARIANT pPropertyValue);
参数
PropertyName PropertyName 是要设置或检索的属性的名称。有关属性列表，请参阅下面的备注部分。以下属性受支持（属性名称区分大小写）：
属性名称说明
ServerHTTPRequest
True/False 值表示是否使用“服务器安全的”XML 组件来加载 Web 服务描述语言 (WSDL) 和 Web 服务元语言 (WSML) 文件。在 Active Server Pages (ASP) 应用程序或 ISAPI DLL 使用 SOAPClient 对象时，请设置为 True。
若 ServerHTTPRequest 设置为 true，则必须使用 WinHTTP 代理配置实用程序来配置 WinHTTP。即使不使用代理服务器，也必须这样做。下载实用程序并遵循下载资料的 ReadMe.txt 文件中提供的使用说明来操作。
ConnectorProgID
指定实现 ISOAPConnector 接口的类的 ProgID。将请求发送给服务时将创建和使用该类的对象。当设置为空字符串（默认值）时，SOAPClient 将使用 SOAPConnectorFactory 对象来创建 WSDL 中指定的传输协议的连接器。
pPropertyValue
pPropertyValue 是该属性的值。
Visual Basic 语法
Property ClientProperty(PropertyName As String) As Variant
Visual Basic 示例
Dim Client As New SOAPClientClient.ClientProperty("ServerHTTPRequest") = TrueConnectorProperty 属性
设置和检索特定于传输协议连接器（由 SOAPClient 对象使用）的属性。
方法定义
[propget] HRESULT ConnectorProperty ( [in] BSTR PropertyName, [out, retval] VARIANT* pPropertyValue);[propput] HRESULT ConnectorProperty ( [in] BSTR PropertyName, [in] VARIANT pPropertyValue);
参数
PropertyName
PropertyName 是要设置或检索的属性的名称。支持哪些属性取决于所使用的连接器。由 Web 服务描述语言 (WSDL) 文件中的 传输属性指定的协议决定要使用的连接器。
pPropertyValue
pPropertyValue 是该属性的值。
Visual Basic 语法
Property ConnectorProperty(PropertyName As String)
Visual Basic 示例
Dim Client As New SOAPClientClient.mssoapinit WSDLFile, Service, PortClient.ConnectorProperty("ProxyUser") = UserClient.ConnectorProperty("ProxyPassword") = Password属性说明
AuthPassword
用于终结点身份验证的密码。
AuthUser
用于终结点身份验证的用户名。
EndPointURL
终结点 URL。
ProxyPassword
用于代理身份验证的密码。
ProxyPort
要使用的代理服务器端口。
ProxyServer
代理服务器的 IP 地址或主机名。
ProxyUser
用于代理身份验证的用户名
SOAPAction
SOAPAction HTTP 标头中使用的值。
SSLClientCertificateName
识别客户端证书以用于安全套接字层 (SSL) 协议的字符串（如果有）。语法为：
[CURRENT_USER | LOCAL_MACHINE[store-name]]cert-name
默认为 CURRENT_USERMY（Microsoft Internet Explorer 所使用的同一存储区）。
Timeout
HttpConnector 的超时。该超时的单位是毫秒。
UseSSL
指定是否使用 SSL 的布尔值（true 或 false）。
Detail 属性
detail 属性是只读属性。它提供简单对象访问协议 (SOAP) 消息中 <Fault>元素的 <detail>元素的值。
方法定义
[propget] HRESULT detail( [out, retval] BSTR* bstrDetail);
参数
bstrDetail
bstrDetail 是错误的详细信息。
Visual Basic 语法
Property detail As StringHeaderHandler (SOAPClient)
为对该客户端实例的下一个调用设置标头处理程序。
方法定义
HRESULT HeaderHandler([in] IDispatch* rhs);
参数
rhs
rhs 是对实现 IHeaderHandler 的 COM 类接口的引用。
Visual Basic 语法
Property HeaderHandler As Object
Visual Basic 示例
Set sc = WScript.CreateObject("MSSOAP.SOAPClient")sc.mssoapinit "http://localhost/DocSample7/DocSample7.wsdl"sc.HeaderHandler = WScript.CreateObject("SessionInfoClient.clientHeaderHandler")Sc.SomeMethod "param1", "param2"Faultactor 属性 (SOAPClient)
faultactor 属性是只读属性，它提供生成该错误的统一资源标识符 (URI)。
方法定义
[propget] HRESULT faultactor( [out, retval] BSTR* bstrActor);
参数
bstrActor
bstrActor 是生成该错误的 URI。
Visual Basic 语法
Property faultactor As String
Visual Basic 示例
wscript.echo soapclient.faultactorFaultcode 属性 (SOAPClient)
faultcode 属性是只读属性。它提供简单对象访问协议 (SOAP) 消息中<Fault> 元素的 <faultcode> 元素的值。
方法定义
[propget] HRESULT faultcode( [out, retval] BSTR* bstrFaultcode);
参数
bstrFaultcode
bstrFaultcode 是 <faultcode>元素的值。
Visual Basic 语法
Property faultcode As String
Visual Basic 示例
wscript.echo soapclient.faultcodeFaultstring 属性 (SOAPClient)
该 faultstring 属性是只读属性。它提供简单对象访问协议 (SOAP) 消息中 <Fault>元素的 <faultstring>元素的值。
方法定义
[propget] HRESULT faultstring( [out, retval] BSTR* bstrFaultstring);
参数
bstrFaultstring
bstrFaultstring 是 <faultstring> 元素的值。
Visual Basic 语法
Property faultstring As String
Visual Basic 示例
wscript.echo soapclient.faultstring
转到原英文页面
返回页首
个人信息中心 |MSDN中文速递邮件 |联系我们
©2005 Microsoft Corporation. 版权所有. 保留所有权利 |商标 |隐私权声明
