C H A P T E R 2 9 Building a Web Services Client
29章 構建一個Web Services 客戶端
About this chapter This chapter describes how to use Web services in a PowerBuilder
application. Reference information for the objects described in this
chapter is in the PowerBuilder Extension Reference and in the online Help.
關於本章 本章介紹瞭如何在PowerBuilder中使用Web Services。在本章中描述對象的參考信息在在線幫助和PowerBuilder Extension Reference中。
Contents
內容
Topic Page
主題
About Web services 549
Importing objects from an extension file 553
Generating Web service proxy objects 555
Connecting to a SOAP server 560
Invoking the Web service method 561
Using .NET Web services with custom headers 562
Using cookies with the Web service client 563
Exception handling 564
Using the UDDI Inquiry API 564
關於Web services 549頁
在擴展文件中導入對象 553頁
生成Web service 代理對象 555頁
連接到一個SOAP服務器 560頁
調用Web service 方法 561頁
使用.NET Web services 帶自定義頭 562頁
使用cookies的Web service客戶端 563頁
異常處理 564頁
使用UDDI查詢API 564頁
About Web services
關於Web services
Web services allow you to use preexisting components (available on the
Internet or on a local network) instead of writing new business logic to
perform common tasks invoked by the applications that you develop. Web
services originated when the Simple Object Access Protocol (SOAP) was
introduced. SOAP leverages Extensible Markup Language (XML) and
usually employs Hypertext Transfer Protocol (HTTP) as the transport.
Invoking Web services through SOAP requires serialization and
deserialization of datatypes, and the building and parsing of SOAP
messages.
Web services允許您使用預先存在的組件(可在互聯網或者本地網絡)，而不是通過你開發的應用程序編寫新的業務邏輯來執行常用的任務調用。Web services源於簡單對象訪問協議(SOAP)引入。SOAP利用可拓展標記語言(XML)和通常採用超文本傳輸協議(HTTP)進行傳輸。通過SOAP調用Web services需要序列化和反序列化的數據類型，SOAP消息的構建和解析。
Part of the value of Web services comes from the Web Services Description
Language (WSDL), which enables a service to be self-describing. WSDL
defines an XML grammar for describing Web services as collections of
communication endpoints capable of exchanging messages. WSDL service
definitions provide documentation for distributed systems and serve as a recipe
for automating the details involved in applications communication.
Web services 部分價值來自於Web Services 描述語言(WSDL),這使服務能夠自我描述。WSDL定義XML語法描述網絡服務集合，終端獲得交換信息的能力。WSDL 服務定義提供文檔爲分佈系統和服務進行自動化的應用程序通訊提供方案。
With SOAP and WSDL, using third-party components is easier because
interfaces between applications become standardized across disparate
platforms.
隨着SOAP和WSDL，跨平臺和應用程序的接口變成標準化，使用第三方組件是容易的。
PowerBuilder supports the following Web services standards:
• SOAP 1.1
• WSDL 1.1
• HTTP or HTTPS
• XSD (XML Schema Document) 1.0
PB支持以下Web services標準：
• SOAP 1.1
• WSDL 1.1
• HTTP or HTTPS
• XSD (XML Schema Document) 1.0
Producing a Web service
PowerBuilder provides tools for developing custom class (nonvisual) user
objects and deploying them as EAServer components and exposing them as
Web services. You can deploy a component to an EAServer host running on
Windows and UNIX operating systems. For more information, see Chapter 23,
“Building an EAServer Component.”
製作一個Web service
PB提供開發工具，開發自定義類(不可見)用戶對象和部署他們作爲EAServer組件並且發佈它們爲Web services。你可以部署一個組件作到運行在Windows和UNIX操作系統的EAServer主機。關於更多的信息，查看23章，“構建一個EAServer 組件”
About building a Web services client
A PowerBuilder application can act as a client consuming a Web service that
is accessed through the Internet. Using SOAP and WSDL, a collection of
functions published remotely as a single entity can become part of your
PowerBuilder application. A Web service accepts and responds to requests sent
by applications or other Web services.
Invoking Web services through SOAP requires serialization and
deserialization of data types, and the building and parsing of XML-based
SOAP messages. Using objects from an extension file or dynamic library that
installs with PowerBuilder, the Web services client proxy performs these tasks
for you—thereby eliminating the need to have extensive knowledge of the
SOAP specification and schema, the XML Schema specification, or the WSDL
specification and schema.
關於構建一個Web Services客戶端
PB應用程序可以作爲客戶端使用Web 服務，通過互聯網訪問。使用SOAP和WSDL，遠程發佈的函數集合客戶可以成爲你的PB應用程序的功能的一部分。一個Web服務接收和應答通過程序或者其他Web服務發送的請求。
通過SOAP調用Web服務需要序列化和發序列化的數據類型，構建和解析基於XML的SOAP消息。使用來自PB安裝的拓展文件或者動態庫裏的對象，Web服務客戶端代理執行這些任務，爲你排除了對SOAP規範和模式、XML Schema規範、WSDL規範和模式等的廣泛的知識的需要。
Choosing a Web service engine
PowerBuilder lets you choose between the .NET Web service engine and the
EasySoap Web service engine to construct SOAP requests and parse the SOAP
messages returned from a Web service.
選擇一個Web服務引擎
PB讓你在.NET Web服務引擎和EasySoap Web服務引擎之間選擇去構建和解析Web服務返回的SOAP消息。
Using the .NET Web service engine
使用.NET Web服務引擎
Generating a .NET assembly
生成.NET程序集
The .NET Web service engine supports the latest Web service standards. To use
this engine, you must have the wsdl.exe Web service tool on the development
machine. This tool is required to parse WSDL files and generate C# code for a
.NET assembly. The wsdl.exe file installs with the .NET SDK. It is not required
on deployment machines, although deployment machines must have the .NET
Framework to consume a Web service that depends on the .NET Web service
engine.
.NET Web服務引擎支持最新的網絡服務標準。使用這個引擎，在開發機器上你必須有wsdl.exe Web 服務工具。這個工具需要解析WSDL文件並且爲.NET程序集生成c#代碼。這個wsdl.exe文件可使用.NET SDK安裝。在部署的機器不需要它，但是部署的機器必須有.NET Framework，依賴它使用.NET 網絡服務引擎的網絡服務。
If you select the .NET Web service engine in the Web Service Proxy wizard,
the wizard generates a .NET assembly (DLL) in addition to a proxy object. To
use the Web service at runtime, you must deploy the wizard-generated DLL
along with your application.
如果你在Web Service 代理嚮導選擇.NET 網絡服務引擎，這個嚮導除了代理對象外生成一個.NET 程序集(DLL)。在運行時使用Web 服務，你必須部署這個嚮導生成的DLL和你的程序一塊。
You can also select the .NET Web service engine in the Project painter for a
new Web service proxy. If you select the .NET Web service engine on the Web
Service tab of the Properties dialog box for the Web Service Proxy Generator,
PowerBuilder attempts to generate an assembly DLL after you click Apply or
OK. You cannot use the Properties dialog box to change the Web service engine
for a proxy that you already generated with the Web Service Proxy wizard.
爲一個新Web服務代理，你可以在項目畫板選擇.NET Web 服務引擎。在Web Service代理生成器的屬性對話框你選擇.NET網絡服務引擎，你點擊應用或者確定後，PB試圖生成程序集DLL。你已經通過網絡服務代理嚮導生成的代理，不能使用屬性對話框更改Web服務引擎。
Naming the DLL
命名DLL
You can name the DLL generated by the Web Service Proxy wizard or by the
Project painter in the Proxy Assembly Name text box. You do not need to
include the DLL extension. The name of the wizard-generated assembly is
Web_service.DLL, where Web_service is the name you provide in the Proxy
Assembly Name field. If you do not provide a name, the assembly takes the
name of the Web service to be consumed by the DLL. The assembly is
generated in the current target directory.
你可以在Web服務代理嚮導或者項目畫板代理程序集名稱文本框內命名DLL。你不需要包含DLL擴展名。你在代理程序集名稱字段提供的名字是web_service，則嚮導生成的程序集是web_service.DLL。如果你沒有提供名稱，這個程序集使用Web Service的名稱。這個程序集是生成到當前的目標目錄。
Deploying the DLL
部署DLL
You must deploy the DLL created for your Web service project to the directory
where you deploy the client executable. You must also copy the
Sybase.PowerBuilder.WebService.Runtime.dll and the
Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll system
assemblies to this directory.
你必須部署你的Web服務項目目錄中創建的DLL到程序可執行文件的地方。你還必須複製Sybase.PowerBuilder.WebService.Runtime.dll 和Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll系統程序集到該目錄。
Extension objects
擴展對象
Although you use the same SOAP connection and exception-handling objects
for the .NET Web service engine as for the EasySoap Web service engine, the
objects that reference the .NET Web service engine require a different
extension file or library.
雖然你使用相同的SOAP connection 和異常處理對象。.NET Web 服務引擎爲EasySoap Web服務引擎，引用該對象的.NET Web服務引擎需要不同的擴展文件或者庫。
The methods available on the SoapConnection object depend on which
extension file or library you are using and on which Web service engine you
are using. The methods for a .NET Web service engine allows you to include
security information in the SOAP client header.
在SoapConnection對象哪些方法是可用的，取決於你使用的Web Service引擎的擴展文件或者庫。對於.NET Web service引擎的方法允許你在SOAP客戶端頭中包含安全信息。
For more information, see “Importing objects from an extension file.”
關於更多的信息，請看“從擴展文件導入對象”
Temporary directory access requirement
臨時目錄訪問需求
The .NET Web service engine requires client applications to access the system
defined temporary directory on the client computer. The client must have
read/write permission for the temporary directory or a "Cannot invoke the web
service" error occurs. The temporary directory is set by the TEMP user
environment variable.
.NET Web service引擎需求客戶端程序去訪問客戶端電腦上系統定義的臨時目錄。客戶端程序必須有臨時目錄的讀寫權限，或者發生一個“不能執行web 服務”的錯誤。臨時目錄由臨時用戶環境變量設置。
Using the EasySoap Web service engine
使用EasySoap Web 服務引擎
If you decide not to use the .NET SOAP engine, PowerBuilder uses the
EasySoap Web service engine. Earlier releases of PowerBuilder supported the
EasySoap Web service engine only. Unlike the .NET Web service engine, the
EasySoap engine does not support the XML-type array datatype or header
sections in SOAP message envelopes. The EasySoap Web service engine is
retained for backward compatibility and for use with targets deployed to UNIX
machines.
如果你決定不使用.NET SOAP引擎，PB使用EasySoap Web服務引擎。早期版本的PB只支持EasySoap Web服務引擎。不像.NET Web 服務引擎，EasySoap引擎不支持xml的數組類型或者在頭部分的SOAP消息信封。EasySoap Webb服務引擎是爲了保證向後兼容和用於部署到UNIX機器的目標。
You set the Web service engine that you want to use on the first page of the Web
Service Proxy Wizard or on the Web Service tab of the Property sheet for a Web
service project. The Use .NET Engine check box is selected by default for new
Web service projects. You must clear the check box if you are developing a
Web service application that you intend to deploy to UNIX machines.
你在Web服務代理嚮導的第一頁或者在Web服務標籤的屬性頁設置Web服務引擎。對於新網絡服務項目，使用.NET引擎複選框默認是選中的。如果你開發的Web服務程序打算部署到UNIX機器，必須清除複選框。
Assigning firewall settings to access a Web service
分配防火牆設置訪問Web服務
When you add a Web service at design time and your development machine is
behind a firewall, you must assign proxy server settings to connect to the
Internet.
當你設計的時候添加一個Web service，並且你的開發機器在防火牆後邊，你必須分配代理服務器設置以連接互聯網。
Table 29-1 displays the design-time proxy server settings that you can enter on
the Firewall Settings page of the PowerBuilder System Options dialog box. To
enter runtime proxy server settings, you must use the SoapConnection
SetProxyServer or the SetProxyServerOptions methods.
表29-1顯示設計時的代理服務器設置，你可以輸入對PB系統選項對話框的防火牆設置頁。進入運行代理服務器設置，你必須使用SOAPconnection的setproxyserver或者setproxyserveroptions方法。
For information about the SetProxyServer or the SetProxyServerOptions
methods, see the PowerBuilder Extension Reference in the online Help.
關於SetProxyServer或者SetProxyServerOptions方法的更多消息，請看在線幫助PowerBuilder Extension Reference 。
Table 29-1: Design-time firewall settings
Firewall setting Description
Proxy host Name of the proxy server that you use to access Webpages
Port The port used for connecting to the proxy server
User name User name for accessing the proxy server
Password Password for the user accessing the proxy server
表29-1：設計時防火牆設置
防火牆設置 說明
代理主機 你用於訪問網頁的代理服務器名稱
端口 連接代理服務器所用的端口
用戶名 訪問代理服務器的用戶名
密碼 訪問代理服務器的用戶的密碼
PowerBuilder uses the values you enter for the proxy server settings only if you
also select the Use Above Values as System Defaults check box on the Firewall
Setting page. The type of engine you select for consuming a Web service can
also affect the settings that PowerBuilder uses to connect to the Internet at
design time.
PB僅使用你輸入的值作爲代理服務器設置，當你在防火牆設置頁選擇使用上面的值作爲系統默認的複選框。你選擇的引擎類型可用使用Web 服務，也對PB在設計時訪問互聯網有影響。
.NET Web service engine If the development machine is located behind a
firewall but you do not select the Use Above Values as System Defaults check
box, PowerBuilder attempts to connect to the Internet using settings entered in
the Internet Options dialog box of the Internet Explorer browser. The selections
you make on the Firewall Setting page have no effect if the development
machine is not located behind a firewall.
.NET Web 服務引擎 如果開發機器在防火牆之後，不過你不選擇使用上面設置作爲系統默認的複選框，PB使用IE瀏覽器的Internet選項內的設置嘗試連接互聯網。如果開發機器沒有在防火牆後邊，則在防火牆設置頁上的選擇沒有效果。
EasySoap Web service engine If you do not select the Use Above Values as
System Defaults check box, PowerBuilder assumes that the development
machine is not behind a firewall and makes no attempt to use settings from the
Internet Options dialog box of the Internet Explorer browser. If you select the
Use Above Values as System Defaults check box, but the development
machine is not located behind a firewall, the Web service invocation can fail.
EasySoap Web 服務引擎 如果你沒有選擇使用上面設置作爲系統默認的複選框，PB假設開發機器沒有在防火牆後邊，不會使用IE瀏覽器的Internet選項內的設置嘗試連接互聯網。如果你選擇使用上面設置作爲系統默認的複選框，不過開發機器沒有在防火牆後邊，Web 服務調用會失敗。
Importing objects from an extension file
從擴展文件中導入對象
Invoking Web services through SOAP requires serialization and
deserialization of datatypes, and the building and parsing of XML-based SOAP
messages.
通過SOAP調用Web服務，需要序列化和反序列化的數據類型，並且構建和解析基於XML的SOAP消息。
The pbwsclient125.pbx file contains objects for the .NET Web service engine
that enable you to perform these tasks without extensive knowledge of the
SOAP specification and schema, the XML Schema specification, or the WSDL
specification and schema. You can use these objects after you import the
extension file into a PowerBuilder Web service application.
這個pbwsclient125.pbx 文件包含用於.NET Web服務引擎對象，他能讓你處理這些任務，不需要對SOAP規範和模式、XML Schema規範、WSDL規範和模式等的廣泛的知識的需要。從擴展文件導入一個PB Web 服務程序的後你可以使用這些對象。
If you use the EasySoap Web service engine, you can import the
pbsoapclient125.pbx file or the pbwsclient125.pbx file into your PowerBuilder
applications. However, the pbwsclient125.pbx file requires the .NET 2.0
Framework on design-time and runtime machines, even if you are not using the
.NET Web service engine. Both extension files contain the same objects, and
you use these objects and their methods in similar ways.
如果你使用EasySoap Web 服務引擎，你可以導入pbsoapclient125.pbx文件或者pbwsclient125.pbx文件到你的PB應用程序中。不過pbwsclient125.pbx文件在設計和運行機器上需要 .NET 2.0 Framework，即使你不使用.NET Web服務引擎。兩個擴展文件包含相同的對象，並且你可以用類似的方式使用這些對象和方法。
Using a PBD file
使用PBD文件
In earlier releases of PowerBuilder, instead of importing an extension file, you
needed to add a PBD file to the application library list. Although this is no
longer necessary, the setup program installs PBD files (containing the same
SoapConnection and SoapException objects as the extension files) in the
Sybase\Shared\PowerBuilder directory. You can use the pbwsclient125.pbd or
the pbsoapclient125.pbd instead of importing object definitions from the
pbwsclient125.pbx or pbsoapclient125.pbx file.
在早期PB版本，不是導入擴展文件，你需要添加一個PBD文件到應用程序庫列表。雖然這不是必要的，安裝程序依然在Sybase\Shared\PowerBuilder 目錄安裝PBD文件（和擴展文件包含一樣的soap連接和soap異常對象）。你可以使用pbwsclient125.pbd 或者pbsoapclient125.pbd 代替從pbwsclient125.pbx 或者 pbsoapclient125.pbx文件導入對象。
To add definitions from a PowerBuilder extension file to an application library,
right-click the library in the System Tree and select Import PB Extensions from
the pop-up menu. Browse to the Sybase\Shared\PowerBuilder directory and
select the extension file that you want to use.
從PB擴展文件添加定義到應用程序庫，在系統樹庫右鍵，在彈出快捷菜單選擇導入PB擴展。瀏覽ybase\Shared\PowerBuilder 目錄，並且選擇你想要的擴展文件。
After you import the PBWSClient125.pbx or the PBSoapClient125.pbx file to
your application, the following objects display in the System Tree:
你導入PBWSClient125.pbx 或者PBSoapClient125.pbx 文件到你的應用程序之後，在系統樹顯示下列的對象。
Object Description
soapconnection Used to connect to a SOAP server
soapexception Used to catch exceptions thrown from soapconnection
對象 說明
Soapconnection 用於連接到一個SOAP服務器
Soapexception 用於捕獲soapconnection拋出的異常
When you create a Web service client application, you must deploy the
extension file that you use along with the client executable to a directory in the
application’s search path. You can use the Runtime Packager tool to
automatically include the extension files required by your Web service
applications.
當你創建一個Web service客戶端程序，你必須部署擴展文件到應用程序的檢索路徑，你使用客戶端可執行程序的目錄。你可以使用運行時打包工具自動包含你的網絡應用程序所需要的擴展文件。