C H A P T E R 2 9 Building a Web Services Client 29章构建一个Web Services 客户端



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客户端程序，你必须部署扩展文件到应用程序的检索路径，你使用客户端可执行程序的目录。你可以使用运行时打包工具自动包含你的网络应用程序所需要的扩展文件。