PowerServer deployment

Key features

PowerBuilder 2021 introduces a new project type: PowerServer. With PowerServer project type, PowerBuilder applications can be deployed as installable cloud applications which have the following features.

  1. The installable cloud app can support almost all of the features of PowerBuilder.

    The installable cloud app is the cloud version of a PowerBuilder application; it is installed on the client, and can be launched directly from the desktop. But different from browser-based apps, installable cloud apps is deployed with native PowerBuilder code (rather than converted to JavaScript) and runs against the PowerBuilder virtual machine (PBVM) on the client. Minimum code changes are required for the app deployment. The PBVM is exactly the same one used by the PowerBuilder classic client/server apps.

  2. The installable cloud app is running in n-tier architecture.

    The installable cloud app makes HTTP or HTTPS calls to the PowerServer and then PowerServer makes connections to the database and executes SQL queries. PowerServer is installed on top of any Web server on a Windows or Linux machine or on the docker or cloud server. PowerServer contains an API server which uses standard REST APIs with REST security to handle the HTTP/HTTPS requests from the client. PowerServer also contains a data server which uses .NET DataStore to handle the data-related requests. Currently .NET DataStore supports ASE, SQL Server, Oracle, SQL Anywhere, PostgreSQL, MySQL, HANA, and SQLite.

  3. The installable cloud app is installed over the Internet and updated automatically and incrementally.

    To install an installable cloud app on the client machine, you access the application URL in a Web browser. You only need to use the Web browser to install the installable cloud app for the first time. After that, you can directly run the app from the desktop. And if any updates are available, the app will be automatically and incrementally updated.

  4. The installable cloud deployment can be a full replacement for the traditional PowerServer Web solution.

    The installable cloud app can be installed on a Windows client, but not on any mobile client such as iOS or Android. The installable cloud deployment option can be used as a replacement for the traditional PowerServer Web solution. But for PowerServer Mobile solution, the user will need to manually implement the client UI logic.

  5. The installable cloud app has these cloud features.

    DataWindows will be deployed as .NET data models. PowerServer 2021 can manage transactions in the cloud environment.

Note

In the Beta and GA release, you must have a PowerBuilder CloudPro license to use the PowerServer deployment features.

Note

You must run PowerBuilder IDE as administrator in order to use the PowerServer deployment features.

You can walk through the following guides and tutorials to get familiar with the PowerServer deployment method:

Architecture

The installable cloud apps must be deployed against PowerServer 2021. PowerServer 2021 is a brand new PowerServer which is totally different from the traditional PowerServer. For more information, refer to this whitepaper: Deploying PowerBuilder Apps to the Cloud.


The following table introduces PowerServer 2021.

-

Web Server

Implementations

Supported Database Types

PowerServer 2021

IIS/Apache/Nginx/Kestrel on a Windows/Linux machine or on the docker or cloud server.

PowerServer 2021 contains an API server which uses standard REST APIs with REST security to handle the HTTP/HTTPS requests from the client.

PowerServer 2021 also contains a data server which uses .NET DataStore to handle the data-related requests.

ASE, MySQL, Oracle, PostgreSQL, SQL Anywhere, and SQL Server


The following table introduces the installable cloud apps.

-

Architecture

App Type

Client Type

Deployment Technology

Client Plug-in

Code Changes

Other Features

Installable Cloud Apps

N-tier architecture.

Installed over the Internet and updated automatically and incrementally.

The installable cloud version of a PowerBuilder application; it is installed as a desktop app on the client, and can be launched directly from the desktop.

Windows

Deployed with native PowerBuilder code and runs against the PowerBuilder virtual machine (PBVM) on the client. The PBVM is exactly the same one used by the PowerBuilder classic client/server apps.

No plug-in is required.

Supports almost all of the features of PowerBuilder, therefore minimum code changes are required.

DataWindows will be deployed as .NET data models.

PowerServer 2021 supports to manage transactions in the cloud environment.


The following describes the database connection of the installable cloud app.

The installable cloud app does not directly connect with the database server; instead, the PowerBuilder Runtime component which resides on the Web server communicates with the .NET Core Web API via WinHttp and the .NET data models and ESQLs included in the Web API connects with the database server. The .NET Core Web API supports OAuth 2.0 or JWT to prevent unauthorized access; and the database server can be placed behind the corporate firewall. The database connections are stored in a connection pool, and used only when needed. It is a short-lived connection; it is more secure and less vulnerable to network condition compared to a long-running connection.

PowerServer components

PowerServer 2021 contains two parts:

  • PowerServer Compiler -- Provides utilities for 1) establishing database connections; 2) converting DataWindows to data models and generating the RESTful Web APIs; 3) generating and deploying the installable cloud apps to the server; 4) changing the Web API URL for the installed apps.

    PowerServer Compiler is provided as a component in the PowerBuilder Installer and installed as a plug-in to the PowerBuilder IDE. For how to run the PowerBuilder Installer, refer to Installation Guide for PowerBuilder IDE. The PowerServer Compiler is by default installed to %AppeonInstallPath%\Common\PSCompiler\[version]\


  • The PowerServer NuGet packages -- The runtime library for the RESTFul Web APIs that supports data processing, authorization, licensing etc. When you launch the PowerServer Web API solution, the PowerServer NuGet packages will be automatically downloaded and installed from the NuGet website (https://www.nuget.org). Please make sure the computer can connect with the NuGet website (https://www.nuget.org).

    The PowerServer NuGet packages can be downloaded to SnapDevelop or any other .NET IDE such as Visual Studio. No matter which .NET IDE you are using, the instructions on how to install, update, and uninstall the PowerServer packages are the same as all the other NuGet packages. For detailed instructions, please refer to this documentation https://docs.microsoft.com/nuget/quickstart/install-and-use-a-package-in-visual-studio.

    The PowerServer NuGet packages are free to download but must be activated using a PowerBuilder CloudProd license before it can work properly. For more, refer to Import license and activate PowerServer.


Note

PowerServer 2021 will only work with PowerBuilder 2021. Before deploying your application with PowerServer 2021, make sure 1) your application is upgraded to be compatible with PowerBuilder 2021; and 2) you have a PowerBuilder CloudPro license (paid or trial).

Installation requirements

Client PC

To run the installable cloud app, install the following OS and Web browser:

  • Windows 10 or 8.1, or Windows Server 2019, 2016, or 2012 R2

  • Google Chrome, Mozilla Firefox, or Microsoft Edge (Chromium-based)

Development PC

To build and deploy the PowerServer project, install the following OS and products/components:

  • Windows 10 or 8.1

  • PowerBuilder IDE 2021 *

  • PowerBuilder Runtime 2021 *

  • PowerServer Compiler 2021 *

  • PowerBuilder Compiler 2021 *

    For installation instructions, refer to Installation Guide for PowerBuilder IDE.

It is recommended that PowerBuilder IDE, PowerBuilder Runtime, PowerServer Compiler, and PowerBuilder Compiler are the same version and build.

To build and deploy the PowerServer project with the PBAutoBuild210.exe command, install the following OS and products/components:

  • Windows 10 or 8.1, or Windows Server 2019, 2016, or 2012 R2

  • PowerBuilder Runtime 2021 *

  • PowerServer Compiler 2021 *

  • PowerBuilder Compiler 2021 *

It is recommended that PowerBuilder Runtime, PowerServer Compiler, and PowerBuilder Compiler are the same version and build.

To compile and publish the PowerServer Web APIs, install the following OS and product:

  • Windows 10 or 8.1

  • SnapDevelop 2021 or Visual Studio 2019

    The development PC must be able to connect with the NuGet site (https://www.nuget.org), in order to download the packages required for compilation.

Web Server

The installable cloud apps support to host the app files in the following Web servers:

  • Windows IIS

    For how to configure IIS 10 in Windows Server 2019, refer to Installing Web Server (IIS) in tutorial 1.

  • Windows/Linux Apache HTTP Server

  • Windows/Linux Nginx

* Kestrel is not recommended to be used as the Web server for hosting app files.

* Any version within the support period is supported.

API Server

The PowerServer Web API is an ASP.NET Core 3.1 app; it can be hosted and deployed like any other ASP.NET Core app.

Following is to highlight the most popular hosting environments:

* Any version within the support period is supported.

For a complete list of supported environments, refer to https://docs.microsoft.com/aspnet/core/host-and-deploy/?view=aspnetcore-3.1.

Database Server

The installable cloud apps can work with the following databases:

  • Oracle 12c, 18c, or 19c

    PowerBuilder and/or PowerServer will automatically download the required driver (Oracle.ManagedDataAccess.Core 2.19.101) from https://www.nuget.org, or you will be asked to specify the location of the driver if https://www.nuget.org cannot be connected.

  • PostgreSQL 11.3, 12, or 13

  • SQL Server 2016, 2017, or 2019

  • SQL Anywhere (ODBC) 16 (16.0.0.2043 or later) or 17

    If SQL Anywhere is on a different machine from PowerBuilder, make sure to enable the connection pooling setting in the ODBC driver. Connection pooling is enabled by default if SQL Anywhere is the same machine as PowerBuilder.

  • ASE (ODBC) 15.0, 15.7, or 16.0 (In-progress feature)

  • MySQL 5.6, 5.7, or 8.0 (In-progress feature)

    PowerBuilder and/or PowerServer will automatically download the required driver (MySql.Data 8.0.21) from https://www.nuget.org, or you will be asked to specify the location of the driver if https://www.nuget.org cannot be connected.

  • Informix (To-do feature)

* In-progress feature means the development is still continuing and will be completed by the GA version. We will fix any reported bugs before GA.

* To-do feature means the development will start after the beta version.

Network

Same as any other web applications, for installable cloud apps, the Web APIs must be published to a PowerServer that locates on the same LAN as the database server. If the database is not on the same network as the Web APIs, every request has to go a long way from PowerServer to the database, it is highly possible that there will be performance and security issues.

Dynamic database connection

It is possible to dynamically map transaction object to data source using CacheName=’xxx’. See CacheName in Connection Reference for more.

For example,

sqlca.dbparm="cachename=Test" //or, Sqlca.dbparm="cachename='Test'"

It is also possible to manually create data caches and build the transaction-object-to-cache mappings in the PowerServer Web API C# solution:

  1. create data caches in the AppConfig > Connection-Cache.json in the ServerAPIs project,

  2. build the mappings in the AppConfig > Application.json.

Note: The manual settings will be overwritten if you deploy project(s) to the solution again. We plan to allow you to select whether to keep or overwrite these settings in the GA version.

Creating data source dynamically (for example, using of_adddatasource function) is not available in the PowerServer 2021 beta yet but will be provided in the GA version.

Using OAuth 2.0 for installable cloud apps

The installable cloud apps deployed with PowerServer can request an access token from the OAuth 2.0 authorization server, extracts the token from the response, and sends the token to the PowerServer Web APIs, as shown in the following diagram.


The following access tokens are supported:

  • JSON Web Token (JWT) (recommended)

  • Bearer token

The following grant types are recommended:

  • Client Credentials

  • Resource Owner Password

The authorization process with Client Credentials and Resource Owner Password can be implemented using the OAuthClient, TokenRequest, and TokenResponse objects. The OAuthClient object obtains the access token and the protected resources. The TokenRequest and TokenResponse objects get or set the access token request and response.

For more, see Tutorial 5: Using OAuth 2.0 for Installable Cloud Apps.

Related features

The following features have been added for the installable cloud app:

  • A system function IsPowerServerApp is added to check if the current application is an installable cloud application deployed using PowerServer.

  • The SystemError event is enhanced to return errors that are specific to the installable cloud application or PowerServer license.

  • The Application object has added the following new functions in order to support OAuth 2.0 authorization server for installable cloud apps:

  • An option "Begin session by code" is added to the Application painter's Properties view.

    This option is not selected by default; which means the session is automatically created when the application starts. If this option is selected, then the session will not be automatically created and the session will be created only when the BeginSession function is executed. Normally you may want to create a session manually using BeginSession after you have obtained the access token, so that the session can include the access token.

  • An option "During compilation, report unsupported PowerScript features for PowerServer deployment" is added to the Application painter's Properties view.

    If this option is selected, the PowerScript features that are unsupported by the PowerServer Web APIs will be detected and reported during the deployment process.

  • The PowerServer Web API solution provides interfaces for getting all user sessions and killing the specified session. For more details, see Get/Kill user sessions.