Welcome!

PowerBuilder Authors: Chris Pollach, Yeshim Deniz, Jayaram Krishnaswamy, Kevin Benedict, Avi Rosenthal

Related Topics: PowerBuilder, SOA & WOA, .NET

PowerBuilder: Article

Creation and Consumption of Web Services with PowerBuilder

Web services support has been significantly enhanced in PowerBuilder.NET

PowerBuilder 12.5 introduced a number of significant enhancements to web services support, both for creation and consumption. In particular, the following were introduced as new features in PowerBuilder.NET:

  • WCF client proxy
  • WCF service target
  • REST client proxy

We're going to look at what those new features provide and how to use them. We're also going to look at how we can package some of that functionality so that it can be used from PowerBuilder Classic applications as well.

Windows Communication Foundation (WCF)
First though, some background. When support for a web service client was first introduced in PowerBuilder 9, it was done based on an open source library called EasySOAP. There were some limitations with that implementation, primarily because the EasySOAP library only supported SOAP 1.1, was limited to XML over HTTP transport, and provided no support for ancillary web services standards such as WS-Security.

The situation was improved considerably when a web service client based on the .NET Framework classes (System.Web.Services) was introduced with PowerBuilder 10.5. That updated the support for SOAP to version 1.2, although it was still limited to XML over HTTP for transport. In addition, support for ancillary web services standard such as WS-Security was still lacking. Such support was available for Visual Studio, but only through an add-in that PowerBuilder could not take advantage of.

PowerBuilder 11 provided some of the same advances in terms of web service creation with the introduction of a .NET web service target type. One particular disadvantage of that implementation was that it required IIS to be installed on the developer's local machine and deployed the web service to it during development.

With PowerBuilder 12.5, web services support has been updated to the Window Communication Foundation that was introduced to .NET in version 3.0. Basing the web services support on these new set of classes (System.ServiceModel) provides a number of important advantages:

  • Support for bindings other than HTTP
  • Support for other message formats (e.g., JSON)
  • Support for WS-Security and other WS-* standards (WS-Policy, WS-Addressing, WS-SecureConversation, WS-Trust, WS-ReliableMessaging, WS-AtomicTransaction, WS-Coordination)
  • Supports self-hosting of services (no need to install IIS on development machines)

Representative State Transfer (REST)
One of the things that SOAP-based web services have drawn fire for recently is their complexity. When things like message security are important (e.g., WS-Security), SOAP provides significant advantages. But many people found the complexity of SOAP too cumbersome and have instead opted for implementing web services through REST. REST web services are accessed through standard URIs using standard HTTP methods (POST, GET, PUT, DELETE) and return data in Internet standard media types (typically XML or JSON). Because REST is an architecture, not a protocol (like SOAP), there are no official standards for it. One particular disadvantage of REST is that while there are machine readable methods that can be used to describe REST web services such as WSDL 2.0 or Web Application Description Language (WADL), most REST web services rely on human readable descriptions. That makes it a bit problematic for a tool like PowerBuilder to automatically generate client proxies for such services.

Creating a WCF Client Proxy in PowerBuilder.NET
Now that we've covered the background, let's see how we can use these new features. We'll start with the WCF Client Proxy. For this example, we're going to create a client for the Amazon AWSECommerceService web service.[1] Note that you will need an account with Amazon Web Services to call the service, so you should go to their website and create one before trying these samples on your own.[2]

Figure 1

The first thing we will do is create a WCF Client Proxy Target from the New dialog (see Figure 1). The first step in the wizard then prompts us to give our new project a name and indicate a library we want to store it in. The second step is to provide the wizard with the URL for the WSDL file used to describe the service (referenced below). In the third step of the wizard we provide a namespace for the generated proxy classes and indicate the assembly where the .NET generated code will be stored as well as the PowerBuilder library where the PowerBuilder generated client will be stored. After this, we will be shown the one service described by the WSDL and the data classes that PowerBuilder will end up generating. While there are additional optional steps in the wizard, the Finish button is enabled at this point and we can simply use it to close out of the wizard.

Next, generate the actual proxy and supporting .NET assembly by running the proxy project you just created. What you should see as a result is a proxy object in the PowerBuilder library with the methods supported by the proxy (see Figure 2).

Figure 2

What you will also see is an assembly that was automatically added to the References for the target that provides the supporting .NET classes for the proxy (see Figure 3). Note that unlike the web service client in PowerBuilder Classic, the data classes created by the WCF client are stored in the supporting .NET assembly, not in the PowerBuilder library.

Figure 3

For this particular sample, I've added the WCF proxy to an existing WPF target, and will be adding a window to that WPF target that will use the WCF proxy. The first thing I'll do after creating the new window is add a reference to the supporting assembly to the Usings portion of the window to make it easier to use the classes it contains (see Figure 4). Because the generated data classes contain .NET array classes that support the IEnumerator interface but do not provide access through an indexer, I've added a reference in Usings to the Systems.Collection classes as well so I can use them in the new window to loop through those arrays.

Figure 4

Listing 1 provides the code I used to call the web service to search Amazon and then populate a listbox with the data returned by the service. Note that I've dummied up the accessKeyId and secretKey values; you will need to provide the ones that Amazon assigned to you when you registered to use their web services before the sample will work. (Listings 1 through 5 can be downloaded here.)

Some portions of the sample bear some explanation. As indicated earlier, one of the advantages of moving to WCF as the basis for the web service client was support for ancillary standards such as WS-Security. The Amazon Web Services do in fact require that you provide your accessKey as an extra header item, that you sign the request using your secretKey, and that you use transport security to send the message. Those requirements are easily met using the WCF proxy.

After we've created the client proxy, we enable the transport security Amazon requires as follows:

_client.wcfConnectionObject.BasicHttpBinding.Security.SecurityMode = PBWCF.BasicHttpSecurityMode.TRANSPORT!

To add your accessKey as an additional header item, do the following:

_client.wcfConnectionObject.SoapMessageHeader.AddMessageHeaderItem(&
"AWSAccessKeyId",&
"http://security.amazonaws.com/doc/2007-01-01/",&
_accessKeyId,&
PBWCF.WCFHMAC.NONE!,&
"")

And finally, to sign the message with your secretKey, do the following:

_client.wcfConnectionObject.SoapMessageHeader.AddMessageHeaderItem(&
"Signature",&
"http://security.amazonaws.com/doc/2007-01-01/",&
_secretKey,&
PBWCF.WCFHMAC.HMACSHA256!,&
"")

Also note that the proxy is self-contained. Unlike the web service clients that we would generate in PowerBuilder Classic, we don't have to import any PBNI extensions into our library or use any system classes (e.g., SoapConnection). Everything we need to call the web service was generated by the proxy and can be used directly.

More Stories By Bruce Armstrong

Bruce Armstrong is a development lead with Integrated Data Services (www.get-integrated.com). A charter member of TeamSybase, he has been using PowerBuilder since version 1.0.B. He was a contributing author to SYS-CON's PowerBuilder 4.0 Secrets of the Masters and the editor of SAMs' PowerBuilder 9: Advanced Client/Server Development.

Comments (2)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.