Table of Contents

Installation

PowerServer components

Architecture

Installation requirements

Client PC

Development PC

Web Server

.NET Server

Database Server

Network requirements

Quick Start

Overview

Preparing a local development environment

Installing IIS in Windows 10

Verifying the example sales app

Minimal efforts: Deploying the sample PowerServer project

Adjusting the sample PowerServer project according to your environment

Building and deploying the PowerServer project

Starting the Web APIs

Running the installable cloud application

Full experience: Creating and deploying a new PowerServer project

Creating the PowerServer project

Creating a new PowerServer project

Configuring the General tab

Configuring the External Files tab

Configuring the Runtime tab

Configuring the Client Deployment tab

Configuring the Web APIs tab

Importing the PowerServer license

Building and deploying the PowerServer project

Starting the Web APIs

Running the installable cloud application

How-to Guides

Overview

Create the PowerServer project

Define the PowerServer projects

Configure the Web server for deployment

Upload the cloud app launcher and the runtime files

About cloud app launcher

Customize cloud app launcher

Configure the Web API settings

Configure the database connection

Select the database driver

Configure the database connection in the Database Configuration dialog

Map the transaction object with the cache

Create DB connection profiles

Manually change the database connection in the ServerAPIs project

Import license and activate PowerServer

Analyze the unsupported features

Build and deploy the PowerServer project

What is the PowerServer C# solution

What settings will be deployed to the solution

Build & deploy using commands

Run the ServerAPIs.Tests project

Compile and run the Web APIs

Check the status of Web APIs

Run the installable cloud application

Customize the app entry page

Customize the deployed app using commands

Change the Web API URL

Change the External Files

Encrypt the password

Support cookie validation

View documentations for PowerServer Management APIs

Get/Kill user sessions

Package the client app

Undeploy the client app

Uninstall the client app

Roll back to an earlier version of app

Tutorials

Tutorial 1: Deploying your PowerServer project to remote servers

Overview

Task 1: Setting up the client machine

Task 2: Setting up the database server

Preparations

Configuring Windows Defender Firewall

Starting the database

Task 3: Setting up the Web server

Overview

Preparations

Installing Web Server (IIS)

Deploying app files to Web Server

Task 4: Setting up the development PC

Preparations

Creating the ODBC data source for the remote database

Creating a Web server profile for remote deployment

Uploading the cloud app launcher and the runtime files to the remote server

Modifying and re-deploying the PowerServer project

Task 5: Setting up the auth server

Task 6: Setting up the .NET server

Preparations

Creating the ODBC data source

Publishing the Web APIs

Tutorial 2: Hosting Web APIs in Docker Containers

Overview

Task 1: Setting up Docker

Setting up a docker host (Docker Engine)

Setting up a docker registry

Task 2: Setting up the database server

Preparations

Starting the database

Task 3: Publishing to Docker

Preparing the development PC

Modifying and re-deploying the PowerServer project

Publishing and deploying Web APIs to Docker

Tutorial 3: Hosting Web APIs in IIS (in-process hosting)

In-process hosting vs. out-of-process hosting

Preparations

Installing IIS

Windows Server OS

Windows Desktop OS

Creating an IIS website

Configuring IIS

Configuring SSL on IIS

Installing Web Deploy

Installing ASP.NET Core Hosting Bundle

Publishing and deploying Web APIs to IIS

Using the Web Deploy method

Using the File System method

Tutorial 4: Hosting Web APIs in Kestrel (using reverse proxy server)

Overview

About PowerServer Web APIs and Kestrel

Running Web APIs on Kestrel

Using a reverse proxy server

Configuring Apache reverse proxy server (Windows)

Configuring Apache reverse proxy server (Linux)

Configuring Nginx reverse proxy server (Windows)

Configuring Nginx reverse proxy server (Linux)

Configuring IIS reverse proxy server

Tutorial 5: Load-balancing PowerServer Web APIs

Overview

Configuring Nginx as a load balancer

Using Nginx Sticky Module

Using Nginx Plus

Using IP hash load-balancing

Configuring IIS as a load balancer

Configuring Apache as a load balancer

Tutorial 6: Authenticating your apps

Overview

Using JWT

Preparations

Modifying the PowerBuilder client app

Appendix

Using OAuth 2.0

Preparations

Modifying the PowerBuilder client app

Appendix

Using Amazon Cognito

Preparations

Creating the Amazon Cognito user pool

Modifying the PowerBuilder client app

Modifying the authentication template

(Optional) Testing the Cognito server

Using other authentication servers (e.g. Azure AD)

Azure Active Directory (AD)

Azure Active Directory (AD) B2C

Tutorial 7: Building your PowerServer project with commands

Task 1: Exporting the build file

Preparing the environment

Exporting the build file

Modifying the build file

Task 2: Building with commands

Preparing the environment

Running the command-line tool

Integrating with Jenkins

Tutorial 8: Packaging & Distributing Installable Cloud Apps (for ISVs)

Packaging & deploying the client app

(Optional) Customizing launcher and app entry page

Packaging launcher, runtime and app

Deploying the client app to Web server (for end users)

Configuring the deployed app on Web server (for end users)

Packaging & hosting the PowerServer Web APIs

Packaging the PowerServer Web APIs

Configuring the PowerServer Web APIs (for end users)

Hosting the PowerServer Web APIs (for end users)

Running the installable cloud app (for end users)

Running the installable cloud app

Uninstalling the client app

Tutorial 9: Load testing installable cloud apps

Load testing installable cloud apps with LoadRunner

Dynamic Values in the Recorded Script

Enclosing Parameters in Angle Brackets “<>”

Running the Application in Test Mode before Recording the Script

Recording

Correlating the Session ID

Correlating the Transaction ID

Parameterizing Static Values in SQLs

Replaying

Load testing installable cloud apps with JMeter

Overview

Preparing the installable cloud application

Recording JMeter scripts

Parameterization and correlation

Tutorial 10: Setting up a Web server

Overview

Setting up IIS

Preparations

Installing Web Server (IIS)

Configuring SSL on IIS

Creating an IIS FTP site

Configuring SSL on FTP server

Setting up Apache on Windows

Preparations

Installing Apache HTTP Server

Configuring SSL on Apache

Installing FTP server

Setting up Apache on Linux

Preparations

Installing Apache HTTP Server

Configuring SSL on Apache

Configuring Apache to be case-insensitive

Packaging and copying the client app

Setting up Nginx on Windows

Preparations

Installing Nginx

Configuring SSL on Nginx

Installing FTP server

Setting up Nginx on Linux

Preparations

Installing Nginx

Configuring SSL on Nginx

Configuring Nginx to be case-insensitive

Packaging and copying the client app

Tutorial 11: Deploying installable cloud apps to Kubernetes

Overview

Before you begin

Configuring Azure Kubernetes Service

Creating a Kubernetes cluster in AKS

Connecting to the Kubernetes cluster

Installing ingress controller

Logging into Azure container registry

Creating a database

Containerizing the installable cloud app

Preparing the application

Creating the container images

Pushing images to Azure container registry

Deploying the application to the Kubernetes cluster

Creating the YAML manifest files

Deploying the application

Configuring the domain name

Testing the application

Tutorial 12: Applying a production license to an existing PowerServer project

Accessing the production license code (Order Owner only)

Importing the production license into the project

After compilation

Before compilation

Tutorial 13: Connecting to the Database

Overview

Part 1: Configuring database connection for project compilation

Introduction

Configuring in PowerBuilder IDE

Part 2: Configuring database connection for app runtime

Introduction

Configuring in PowerBuilder IDE

Configuring in PowerServer

Working with Database Connections

Overview

Supported database connection options

Comparing the runtime database connections between c/s app and installable cloud app

Techniques for supporting various connection scenarios

Supported database types & versions

ASE database

Configuring database caches

Creating database caches in the project settings

Select the database driver

Configure the database connection in the Database Configuration dialog

Create the DB connection profile

Managing database caches in the PowerServer solution

Setting up static database connection for the app runtime

Creating transaction-to-cache mappings in the project settings

Managing transaction-to-cache mappings in the PowerServer solution

Using LogID and LogPass properties

Setting up dynamic database connection for the app runtime

Dynamically mapping transaction object with cache using DBParm

Using CacheGroup property in DBParm

Using LogID and LogPass properties

Making dynamic database connections from the app client

Managing database connections using APIs

Unsupported Features & Workarounds Guide

How to detect unsupported features

Unsupported features & workarounds

Unsupported features that can be detected

SetTrans

Data pipeline

MobiLink

Oracle RPC arrays

SQLPreview

SQLReturnData property

Unsupported features that cannot be detected

Transaction trace

Unsupported use cases in Embedded SQLs

Retrieve As Needed and Rows to Disk

SyntaxFromSQL

Commit or Rollback Transaction using Dynamic SQL

Data retrieval and SQL operations in the RetrieveRow event

Discrepancies & workarounds

Discrepancies that cannot be detected

DB connection

Alias name

rowsupdated value

DisableBind parameter

TableBlob retrieval

Dynamic DataWindow

TransactionName

Data type in Dynamic SQL Format 4

Decimal data type in static SQL or DataWindow

Timing of transaction rollback

Oracle AutoCommit and Lock

Stored procedure parameter

Transaction commit

Use Describe in Dynamic SQL Format 4

Bit data field

SelectBlob/UpdateBlob supports UTF8 only

SQLNRows property (with Cursor)

SQLCode property (with SP)

Column name from view

Incompatible coding styles

PBLs contain DataWindows with the same name

Object name using C# reserved words

DataWindow name containing special characters

Editing SQL

Column order in data source and Column Specification

One compute expression containing multiple computed columns

Cursor syntax

Syntax after UNION

Troubleshooting Guide

Configuring and deploying PowerServer projects

Permission errors when configuring the Web server profile

Syntax error during the build process

DB driver error during the build process

Error in the Unsupported (DWs) window

Failed to generate the PowerServer Web APIs project

Error uploading application files to FTP

Changed PBL list

Running installable cloud apps

Cloud app launcher and application executable

Failed to get the app publisher from the server

Cannot start cloud app launcher

Application executable disappeared suddenly

Window is slow to open

Models and controls

Cannot retrieve data when data includes null values

PBSELECT DataWindow error

RibbonBar control displays blank

Server

Cannot connect to the server when creating the session

Session creation failed

Session does not exist

App requires login again

File name containing character + cannot be downloaded

"HTTP Error 404.2 - Not Found" error when running the app

Failed to access the *.json file

Failed to connect to the license server: No such host is known

Database

Different results returned from an ASE stored procedure

SelectBlob data truncated

Garbage letters display when retrieving multibyte data

Slow app performance with SQL Anywhere

64-bit database cannot be connected from IIS

License errors

Failed to call the license server API

Failed to login the license server

Cannot access License.json

Others

Failed to update NuGet packages in PowerServer C# solution

Performance Guide

Introduction

Performance suggestions on project compilation and deployment

Performance suggestions on loading installable cloud apps for the first time

Performance suggestions on running installable cloud apps

Debugging the performance

Working against the impact of Internet and slow networks on runtime performance

Hosting Web APIs and database on the same LAN

Web API publishing method

Optimizing database server performance

Tuning excessive server calls

Overview

Technique #1: partitioning transactions via stored procedures

Technique #2: partitioning non-visual logic via server-side REST APIs

Technique #3: eliminating recursive embedded SQLs

Technique #4: eliminating DW computed fields calling user functions that have ESQL

Minimizing large data transmissions

Overview

Technique #1: retrieving data incrementally

Technique #2: minimizing excessive number of columns

Debugging Guide

Overview

Debugging with Fiddler

Installing Fiddler

Configuring Fiddler

Configuring the PowerServer project

Running the PowerServer Web APIs and then Fiddler

Capturing HTTP(S) with Fiddler

Filtering the results

Inspecting the results

Analyzing the performance

Logs and unsupported features report

Deployment log

Unsupported features report

Web file download log

Web API request log

Debugging log in SnapDevelop

PowerServer logs

Log4net logging

Logging with the settings in Logging.json

Debugging case studies

DataWindow related errors

DataWindow retrieve error

SyntaxFromSQL execution error

Different execution results in different databases

Incompatible data type

PBSELECT retrieve error

Embedded SQL related errors

Data type mapping tables

SQL server data type mappings

ASE server data type mappings

SQL Anywhere server data type mappings

Oracle server data type mappings

PostgreSQL data type mappings