How-to

The following tasks give a comprehensive overview of what you can perform for a PowerServer project:

  1. Create the PowerServer project.

  2. Define the PowerServer project.

  3. Configure the Web server for deployment.

  4. Upload the cloud app launcher and the runtime files.

  5. Configure the Web API server settings.

  6. Configure the database connection.

  7. Import license and activate PowerServer.

  8. Analyze the unsupported features.

  9. Build and deploy the PowerServer project.

  10. Compile and run the Web APIs.

  11. Run the installable cloud application.

  12. Customize the app entry page.

  13. Package the installable cloud application.

  14. Change the Web API URL for an application.

  15. Build and deploy the PowerServer project with commands.

  16. Get/Kill user sessions.

  17. Undeploy the PowerServer project.

  18. Uninstall the PowerServer project.

Create the PowerServer project

Recommendation: It is recommended that you launch PowerBuilder IDE as an administrator; otherwise PowerBuilder IDE may not have full permissions to read/write the folder under the Web server.

To create a PowerServer project:

  1. Select File>New or click the New button in the PowerBar to open the New dialog box.

  2. Select the Project tab.

  3. Select the target in which you want to create the project from the Target drop-down list.

  4. Select the PowerServer project type and click OK.

    The Project painter for PowerServer opens so that you can specify the various properties of your application.

  5. When you have finished defining the project object, save the object by selecting File>Save from the menu bar or by clicking the Save button () in the toolbar. PowerBuilder saves the project as an independent object in the specified library. Like other objects, projects are displayed in the System Tree and the Library painter.

Define the PowerServer projects

Once you have created a PowerServer project, you can open it from the System Tree and modify the properties if necessary. The Project painter for the PowerServer project looks like this.


The following table describes each of the options you can specify in the Project painter for PowerServer.

Page or Option

What you specify

General page

App name

Specify a name for the application.

PBR file name

(Optional) Specify a PowerBuilder resource file (PBR) for your application if you dynamically reference resources (such as bitmaps and icons) in your scripts and you want the resources included in the application instead of having to distribute the resources separately.

You can type the name of a PBR file in the box or click the button next to the box to browse your directories for the PBR file you want to include. The PBR file as well as the resources it references must reside in the application directory or subdirectory; and only relative paths of the PBR file and the resources will be accepted.

For more about PBRs, see the section called “Distributing resources” in Users Guide.

Windows classic style

Select this to add a manifest file to the application that specifies the appearance of the controls as an application resource.

By default, this option is not selected, which means the Windows flat style is used and the 3D effect of some controls will be removed to have a "flat" look, for example, the 3D lowered border of Column and Computed Field in the DataWindow object, the background color of Button, the BackColor and TextColor of tooltip, and the TabBackColor of tab header will not take effect. If you still want the 3D effect, you should select the "Windows classic style" option when deploying the application.

Note

If you have applied a theme to the application, you should not check the "Enable Windows Classic Style in the IDE" option in the System Options or the "Windows classic style" option in the project painter and the PB.INI file (if any) should not contain such setting, otherwise, the application UI will be rendered in the Windows classic style instead of the selected theme.

Rebuild

Specify either Full or Incremental to indicate whether you want to regenerate and redeploy all object files to the Web server. If you choose Incremental, PowerBuilder regenerates and redeploys only objects that have changed, and objects that reference any objects that have changed, since the last time you built the application.

As a precaution, regenerate all objects before rebuilding your project.

Enable DEBUG symbol

Select to enable any code that you placed in DEBUG conditional code blocks. For more information, see the section called “Using the DEBUG preprocessor symbol” in Users Guide.

Encrypt all the compiled p-code files

Select whether to encrypt the object files when compiled from the PowerBuilder dynamic libraries.

Platform

Select if the application can run on 32-bit or 64-bit machines.

Manifest Information

Select whether to generate a manifest file (either external or embedded) and to set the execution level of the application.

For further information, see the section called “Attaching or embedding manifest files” in Users Guide.

Properties displayed for executable

Specify your own values for the Product name, Company name, Description, Copyright, Product version, and File version fields associated with the application file and with machine-code DLLs. These values become part of the Version resource associated with the application file, and most of them display on the Version tab page of the Properties dialog box for the file in Windows Explorer. The Product and File version string fields can have any format.

Executable version used by installer

Specify the product version and file version (in numeric values) that will be used by Microsoft Installer to determine whether a file needs to be updated.

The four numbers can be used to represent the major version, minor version, point release, and build number of your product. They must all be present. If your file versioning system does not use all these components, you can replace the unused numbers with zeros. The maximum value for any of the numbers is 65535.

Libraries page

Specify a PBR file for a dynamic library if it uses resources (such as bitmaps and icons) and you want the resources included in the dynamic library instead of having to distribute the resources separately.

You can type the name of a PBR file in the box or click the button next to the box to browse your directories for the PBR file you want to include. The PBR file as well as the resources it references must reside in the application directory or subdirectory; and only relative paths of the PBR file and the resources will be accepted.

External Files page

Specify the custom user external files and/or the resource files that are referenced in the PowerScript. Make sure all these files are placed in the same folder or sub-folder of the application target (.pbt) file.

Files preloaded as compressed packages and Files preloaded in uncompressed format

The custom user external files will be downloaded from the server before the application starts. It is recommended that you deploy the files which stay unchanged most of the time (such as UI theme files) as one compressed package, so that it can be transferred faster; and deploy the files which may be modified frequently (such as INI files) as individual files, or deploy them as a separate package.

  • To deploy files as one compressed package, select Files preloaded as compressed packages from the list box, then click Create Package to create a package, and then click Add Folder or Add Files to add the folder or files under this package.

  • To deploy files as individual files, select Files preloaded in uncompressed format from the list box, and then click Add Folder or Add Files to add the folder or files under it.

The custom user external files may include the following:

  • INI files (including pb.ini, pblab.ini, pbodb.ini etc.)

  • DLL/OCX files

  • XML files or image files used by the UI theme or external functions

  • text files, PDF files or any other files used by the external function

Images/videos dynamically loaded

The resource files (such as images, videos etc.) are downloaded from the server at the moment when they are used by the application. You can select Images/videos dynamically loaded and then click Add Folder or Add Files to add the folder or files under it.

Note

The read-only files added under Files preloaded in uncompressed format or Images/videos dynamically loaded will lose its read-only attribute after transferred to the server via FTP. This seems to be a common issue with FTP transfer.

DLL & OCX Registration

If the DLL/OCX files need to be registered and can be registered by Regsvr32, you can click DLL & OCX Registration to select the DLL/OCX files so that they can be registered by Regsvr32 automatically before the application starts; if the DLL/OCX files need to be registered but cannot be registered by Regsvr32, you can specify the registration commands in Preload Event in the Run Options tab.

INI Configuration

When the application is updated, the INI file can be updated with the specified strategy. Click the INI Configuration button and then select one or more INI file and configure the strategy for them at one time; or select and configure for the INI file one by one.

  • Overwrite update -- The INI file on the client will be updated if the INI file downloaded from the server has been updated, and changes made to the local INI file will be lost.

  • Merge update -- The INI file on the client will be merged with the INI file downloaded from the server, so changes made to the local INI file will be preserved and merged into the INI file downloaded from the server. But notice that any setting that exists in the local INI file while does not exist in the downloaded INI file will be removed.

  • Do not update -- Once the INI file is downloaded to the client, it shall never be updated with the INI file downloaded from the server.

Note

The external files cannot contain any file that has the same name as the application, or the PBD or p-code file to be generated, otherwise duplicate name error occurs.

For example, [appname].exe, [appname].xml, [appname].manifest file etc. cannot be added to External Files.

For another example, test.pbl will be deployed as test.pbd, therefore, test.pbd cannot be added to External Files.

Runtime page

Select the runtime files according to the features used in the application. The files will be downloaded from the server to the client, for the application to run.

The deployment tool does not actually deploy the files, instead it notifies the application to download such files (corresponding to the runtime version displayed) from the server directly. The runtime version displayed on this page can be configured in the IDE > System Options dialog. And you will need to make sure the corresponding version of PowerBuilder Runtime is uploaded to the server when you upload the Cloud App Launcher to the server.

Signing page

Select whether to digitally sign the application executable file (appname.exe).

If you want to digitally sign the application executable file, you can specify the settings required for signing under the "Use the SignTool utility from the Windows SDK" option, for example, SignTool location, signing certificate, certificate password, signature algorithm, and URL of the time stamp server. And make sure Microsoft’s SignTool has been installed on the current machine.

Or you can place the signing scripts in a file (with file extension as .cmd) and then select the file for the "Use your own signing script" option. For example, to sign the application executable file (appname.exe) using Microsoft’s SignTool, you may create a cmd file that includes the following scripts:

signtool.exe sign /f mycert.pfx /p password /d "My application" /du http://www.mytest.com /fd sha256 /tr "http://timestamp.digicert.com" /td sha256 mytest.exe

After the executable file is generated and before it is deployed to the server, PowerBuilder will sign the executable file using your own signing scripts or using the SignTool settings you specified.

Client Deployment page

Deployment Server

Select to deploy the application to a local server or a remote server. If you have not configured the server yet, click the Server Configuration button and follow instructions in Configuring the Web server for deployment to configure the server.

If the option "Check the availability of Cloud App Launcher on the server during the deployment process" is selected, the deployment process will be terminated if no Cloud App Launcher is detected on the target server. For how to upload the app launcher and runtime files, refer to Uploading the app launcher and runtime files.

You can also choose to package the application as an executable installer or a zipped file, and then install the application to the Web servers. For more about packaging an application, refer to Package the installable cloud application.

Deployment version

The deployment version number is used by the server to determine whether to perform an install or update for the application.

It is recommended to increment the deployment version number every time when the application is updated and re-deployed.

Available time and Expiration time

Schedule the time for the deployment version to be accessible or inaccessible to end users.

However, if the available time or expiration time is reached and the app is still open, the app will not get updated, until the app is closed or the session times out. Therefore, it is recommended that the session timeout feature should be enabled (for apps deployed via PowerServer) or implemented (for apps deployed via PowerClient).

Minimum compatible version

Specify the lowest compatible version for the application. If the current version installed is older than it, a forced update will be performed, or the application will stop running.

Download options

Specify when to download the application files -- before the application starts or at the moment when they are called by the application at runtime.

If you select "Download the app files as necessary", the following files will be downloaded before the app runs: 1) the PowerBuilder Runtime files, 2) the application executable, and 3) the files you selected to be preloaded in the External Files page; the other files will be downloaded at the moment they are called by the app.

If you select "Download all the app files at app startup", the runtime files, app executable, the application files, and external files are all downloaded at the startup, except for the image files that are set to be dynamically loaded in the External Files settings.

App entry page settings

Specify which mode (with or without background service) will be run by default when the user accesses the application by inputting http://IPAddress/AppName.

IMPORTANT: This setting must be consistent with the app launcher which is uploaded to the server, otherwise the application will fail to run. If you have changed the mode and uploaded the launcher again, make sure you also change the mode here accordingly, and ask the end user to clear the browser cache if the app launcher fail to run on the client.

  • If you have uploaded the app launcher with background service, then you should select "Startup with background service" (and keep "Deploy auto.html..." selected and "Deploy manual.html..." unselected).

    In such case, the user can input http://IPAddress/AppName or http://IPAddress/AppName/auto.html to access the application.

    The user should not input http://IPAddress/AppName/manual.html, otherwise it will lead to a "page not found" error or an infinite searching for files.

  • If you have uploaded the app launcher without background service, then you should select "Startup without background service" (and keep "Deploy manual.html..." selected and "Deploy auto.html..." unselected).

    In such case, the user can input http://IPAddress/AppName or http://IPAddress/AppName/manual.html to access the application.

    The user should not input http://IPAddress/AppName/auto.html, otherwise it will lead to a "page not found" error or an infinite searching for files.

  • If you have uploaded the app launcher with and without background service, then you can choose the default startup mode between "Startup with background service" and "Startup without background service" and then select both the "Deploy manual.html..." and "Deploy auto.html..." options.

    In such case, the user can input http://IPAddress/AppName/manual.html to run the application without background service, and input http://IPAddress/AppName/auto.html to run the application with background service; or input http://IPAddress/AppName to run the application in the default startup mode.

The visual displays of the app entry page are customizable. For how, refer to Customize the app entry page.

Run Options page

Commandline arguments

Specify the command line arguments for the application. The arguments will be directly passed to the application when the application is run. And the arguments will be automatically saved and updated to the app startup icon on the desktop and the app shortcut menu in Windows start.

The arguments specified here cannot be modified at runtime. If you want to modify the argument at runtime, you can specify the argument in the application URL (for example, http://localhost/salesdemo/?arg=1).

Create shortcut(s)

Desktop shortcut -- Specify whether to create an application shortcut icon on the client desktop.

Start menu shortcut -- Specify whether to create an application start shortcut menu in the Windows start menu.

App uninstall shortcut -- Specify whether to create an application uninstall shortcut menu in the Windows start menu.

Show the loading animation before the app runs

Specify whether to show an animation (as shown below) when the application prepares for startup. The animation will disappear when the application's first window displays.

This option should not be selected if the application starts with no user interface; otherwise the animation will not disappear.


You can deploy your own animation to replace the default animation (as shown above). For how, refer to Customize the app entry page.

Validate the application integrity before the app runs

Specify whether to validate the hash of every object file before they are loaded, so that files changed illegally will not be run.

Preload Event

(Optional) Specify the commands that will be executed immediately after files are downloaded and before the application starts. For example, you can specify commands to register DLL/OCX files that cannot be registered by Regsrv32; or any commands that need to be executed with administrator rights.

The commands can be any Windows commands or user-defined commands.

For example, suppose there is a DLL file from the application that needs to be registered on the client, you can enter the following commands:

cd /d "C:\Windows\Microsoft.NET\Framework\v4.0.30319"
regasm "%AppData%\Appeon\PBCloud\demo.appeon.com_app1\EncryptDecryptClass.dll" /tlb:testappeon.tlb  /codebase /nologo

Note: As the commands are executed silently, any commands that will pause the execution and wait for user input will cause the application to wait endlessly.

You can specify how often the commands should be executed: for only one time when the application is launched for the first time or when the application is updated, or every time when the application runs.

If the commands need to be executed with the administrator rights, you should select the Run as administrator option.

Running app from IDE

Specify how the application can be launched from the PowerBuilder IDE (when you select the Run PowerServer Project button in the toolbar or from right-clicking the PowerServer project in the System Tree).

You can specify the host name, port number, connection type (HTTP or HTTPS), and/or arguments. You can also specify to start the application from the Cloud App Launcher if the Cloud App Launcher is installed, or from a Web browser if the Cloud App Launcher is not already installed. If the Cloud App Launcher is not installed on the current machine, even if you have specified to start the application from the Cloud App Launcher, the Web browser will start to install the Cloud App Launcher and run the application.

The arguments specified here will be appended to the application URL and then passed to the application via the URL, for example, http://localhost/salesdemo/?arg1&arg2.

Note that the arguments appended to the application URL cannot contain special characters such as "?", "#", as they have special meanings in HTML URL; if you want to use these characters in the argument name or value, you can specify them in the Commandline arguments as static arguments on this same page, so that they can be passed to the application directly instead of being sent as part of the URL.

Web APIs

Web API Generation

Specify the location, name, and namespace for the PowerServer Web API solution. The namespace can only contain characters, numbers, and underscores, and the first character must be a capital letter or underscore.

If the PowerServer solution has already been created before, you can select "Choose an existing solution", and deploy the application to the existing solution; if you re-deploy an application, the application data models will be updated in the solution, and if you deploy a new application, the application data models will be added to the existing solution.

You can also choose whether to overwrite the license and launch settings in the solution. Applications deployed to the same solution can share settings including PowerServer license, Web API URL, database connection settings etc. and can take advantage of additional features such as OAuth authorization, file server etc. that are developed by users.

See Configure the Web API settings for more details.

Web API URL

Specify the URL for accessing the PowerServer Web APIs.

License settings

You can click Auto Import to directly obtain and import the license from the Appeon sites. Make sure the computer can connect with the Appeon sites (https://apips.appeon.com, https://apipsoa.appeon.com, https://apipsinfo.appeon.com, and https://api.appeon.com).

You can also click Import from File to select and import the license file. You will need to get the license file first.

See Import license and activate PowerServer for more details.

Database Configuration

Click the Database Configuration button to configure the database connection for the application deployment and runtime. The database connection is required 1) when converting the PowerBuilder DataWindow objects to C# data models during the deployment process; and 2) when accessing data from the database at application runtime.

See Configure the database connection for more details.


Configure the Web server for deployment

A Web server is required to host the files of the installable cloud app deployed from the PowerServer project. If you have not set up any Web server yet, you can follow this section Installing Web Server (IIS) to install IIS.

Any type of Web server (such as IIS, Apache, Nginx etc.) is supported. You can set up FTP on the server, so that you can remotely deploy the app to the server. For how to configure FTP on a server running against IIS, refer to Configure an FTP server. For how to configure SSL on a server running against IIS, refer to Configure an SSL-based FTP server.

To configure a deployment server:

  1. Select Tools>Web Server Profile from the menu bar to open the Web Server Profile window.

  2. In the Web Server Profile window, click the Add button.


  3. In the Add/Edit Server window, select Local server or Remote server.

    For a local server, set the Web root full path (for example %systemdrive%\inetpub\wwwroot for IIS), and then click Test File Path to ensure the path is valid.

    Note

    If you intend to deploy to a local Web server, make sure you run PowerBuilder as administrator or have write permissions to the specified directory (administrator rights are required when transferring files to a local Web server).

    For a remote server, specify a profile name and the connection settings for the FTP site (including host name, port number, FTP user name, FTP password, and encryption), and then click Test FTP Connection to ensure the connection is successful.

  4. Click OK. The server profile will be created.


The server configuration will be used by all PowerServer projects; therefore if you have changed the server settings, you will need to upload the app launcher if no launcher has been uploaded to that server or directory.

Note

If you intend to deploy to the Web server through a proxy server, make sure the proxy server and the FTP server have the same encoding, otherwise, the multi-byte characters in the file/folder name will become unrecognizable after deployed to the server.

Upload the cloud app launcher and the runtime files

The app launcher and the runtime files must be uploaded to the Web server, and then installed to the client when the application is run for the first time. The app launcher and the runtime files will be used by all apps that are deployed to the same server and directory.

Note: there will be only one app launcher in the specified server and directory, although there can be multiple versions of runtime files. The app launcher will be overwritten without notice by the one uploaded later to the same server and directory.

You can determine which type of the app launcher you want to upload to the server:

  • Launcher without background service: This launcher program does NOT use a background service. As such, it should be easier to install and use and does not require administration rights. However, it has certain dependency on the browser, which may result in different installation experience depending on the browser used and its configuration.

  • Launcher with background service: The launcher program uses a background service. If there are multiple users on a client machine, the launcher requires administrator rights to install and will work together with the background service. This launcher type does NOT have dependency on the browser.

To upload the app launcher and runtime files:

  1. Select Tools>Upload Cloud App Launcher from the menu bar. The Upload Cloud App Launcher and Runtime window appears.

  2. In the Upload Cloud App Launcher and Runtime window, select whether to directly upload the app launcher and runtime files to the server or only create a zip package and manually upload it to the server later.

    • To directly upload the app launcher and runtime files to the server, select the server profile where the app launcher and the runtime files will be uploaded.

    • To create a zip package which will be manually uploaded later, specify where the zip package will be created.

    For detailed information about this window, refer to Uploading the app launcher and runtime files.


Configure the Web API settings

To configure the Web API settings:

  1. Select the Web APIs tab in the PowerServer project painter.

  2. Select "Create a new C# solution" or "Choose an existing solution" and specify the location and name for the PowerServer solution.

    A C# solution (PowerServerApp.sln) will be created under the specified location.

    "Create a new C# solution" vs. "Choose an existing solution"

    Depending on whether multiple applications will use the same one PowerServer or each application will use its own PowerServer, you choose from "Create a new C# solution" and "Choose an existing solution". If you want one PowerServer solution to be used by all applications, you should manually switch the default option "Create a new C# solution" to "Choose an existing solution" and specify the solution name, once after the PowerServer solution is created; and then deploy the application as well as the others to this existing solution. If you re-deploy an application to an existing solution, the application data models will get updated in the solution, and if you deploy a new application to an existing solution, the application data models will be added to the existing solution. You can also select whether to overwrite the license and launcher settings in the existing solution. Applications deployed to the same solution can share settings such as the PowerServer license, Web API URL, database connections etc. and can take advantage of new developments added by the user such as OAuth authorization, file server etc.

    For more information about the PowerServer solution, see About the PowerServer Web API solution.

  3. Input a name as the namespace for the PowerServer C# solution.

    The namespace can only contain characters, numbers, and underscores, and the first character must be a capital letter or underscore.

  4. Specify the Web API URL. This tells the installable cloud app where to call the PowerServer Web APIs.


Configure the database connection

Database connection is required 1) when converting the PowerBuilder DataWindow objects to C# data models during the deployment process; and 2) when accessing data from the database at application runtime.

To configure the database connection:

  1. Click the Database Configuration button at the bottom of the Web APIs tab.

  2. In the Database Configuration dialog, click New in the upper part to create the database connection that will be used by the Web APIs.

    For example, you can establish a connection with the SQL Anywhere database for the PowerBuilder demo using the following settings:

    • Specify any text as the database cache name.

    • Specify SQL Anywhere (ODBC) as the database provider.

    • Select the data source (for example, PB Demo DB V2021).

    • Specify the user name (for example, dba) and password (for example, sql).

    • Click Test Connection to make sure the database can be connected successfully.

    The Advanced button contains additional important settings for the database such as DelimitIdentifier, TrimSpaces, etc. If your database has such settings, make sure to click the Advanced button to configure those settings.


    If you select MySQL or Oracle from the Provider listbox, you will be asked to specify a location for the required driver (MySql.Data 8.0.21 or Oracle.ManagedDataAccess.Core 2.19.101) or allow PowerBuilder to download and install the required driver from the NuGet website.

    The packages downloaded from the NuGet website will be stored to %USERPROFILE%\.nuget\packages and cached in %USERPROFILE%\.sd\19.0\dbDrives\, so they can be automatically loaded when the MySQL or Oracle database connection is created.


  3. Click OK to save settings and go back to the Database Configuration dialog; make sure the check box of the database cache is selected; and then click New in the lower part to map the transaction object with the database cache.

  4. Input the transaction object name (for example "sqlca") that maps to the database cache.


Import license and activate PowerServer

First of all, make sure you have a valid license for PowerServer 2021 Beta.

  • If you have a preview license, the preview license will no longer work with the beta version.

  • If you already have a PowerBuilder CloudPro license (no matter which version it is), the CloudPro license will automatically work with the beta version.

  • If you have no PowerBuilder CloudPro license, you can apply for a beta license at https://www.appeon.com/ps-beta.

Once you have a valid license for the beta version, you can import the license and deploy it along with the Web APIs project. The license will be validated later when the installable cloud app is run.

To import the license automatically:

  1. Make sure the computer can connect with the Appeon sites (https://apips.appeon.com, https://apipsoa.appeon.com, https://apipsinfo.appeon.com, and https://api.appeon.com).

  2. Go to the Web APIs tab of the PowerServer project, and then click Auto Import to automatically import the license.

    PowerBuilder will automatically obtain the license (according to your PowerBuilder IDE login account) from the Appeon sites and then import the license here.


To import the license manually:

  1. Log into the Appeon User Center, click License Management, and then click My Beta Licenses.


  2. Click View, and then click Export to export the license code to a TXT file ([LicenseKey].txt) and save the file on the local machine.


  3. Go to the Web APIs tab of the PowerServer project, and then click Import form File to select and import the [LicenseKey].txt file.


If there are multiple PowerServer projects that will use different PowerServers, then you must import the license to every project before deployment. The license will be deployed along with the Web APIs project.

The license will be automatically validated when the installable cloud application is run. Please make sure the Web API server can connect with the Appeon website so that the Appeon license server can successfully validate the license and activate the PowerServer packages.

Analyze the unsupported features

The PowerScript features will be analyzed during the build & deploy process; and if any feature is detected to be unsupported by the PowerServer Web APIs, it will be reported as an unsupported feature in the Output window.

However, this unsupported feature analysis capability is disabled by default. To enable this capability, open the Application painter's Properties view, and select the option "During compilation, report unsupported PowerScript features for PowerServer deployment" in the PowerServer tab page.


With this option selected, the scripts will be analyzed

  • when the Build & Deploy PowerServer Project option is selected.

    If any unsupported feature is detected, it will be displayed in the Output window | Unsupported (DWs) tab or Unsupported (PowerServer) tab.



  • when the scripts are saved or compiled.

    If any unsupported feature is detected, it will be displayed as compilation warnings, as shown below.


Make sure to modify the unsupported feature according to the suggested workarounds in Unsupported Features Guide.

Even if there is no unsupported features reported, it is still recommended that you go through Unsupported Features Guide to understand why some features are not working as expected in the installable cloud app.

Build and deploy the PowerServer project

To build and deploy a PowerServer project:

  1. Before building and deploying the application, make sure to close any anti-virus tool on the development machine.

  2. Click the Build & Deploy PowerServer Project button () in the toolbar, or right-click the PowerServer project in the System Tree and then select Build & Deploy PowerServer Project to build and deploy the application to the server. Or select Deploy PowerServer Project if you have already built the application before.

    The application executable file (as well as the PBD files) is generated under %TEMP%\pbappscache\temp\[appname] (for example, C:\Users\appeon\AppData\Local\Temp\pbappscache\temp\pssales) on the development machine, then digitally signed, and deployed to the server.

    The PowerServer Web API solution is generated under the specified location (by default C:\Users\appeon\source\repos).

    Note

    After the application is deployed to the server, do not manually change the application folder name on the server, otherwise the application uninstall program will fail to run.

The build & deploy process is composed of the following tasks:

  1. (Build) Converts PowerBuilder DataWindow objects to C# data models.

  2. (Build) Compiles the scripts and analyzes unsupported features.

  3. (Build) Generates the PBD files and related application files.

  4. (Build) Generates or updates the PowerServer Web API solution.

  5. (Deploy) Adds the project settings (app name, Web API URL, PowerServer license, and database connections) to the ServerAPIs project of the PowerServer Web API solution.

  6. (Deploy or Package) Uploads the application files (PBD files, app executable file, external files etc.) and settings (runtime file list, Web API URL, and other project settings) to the Web server, or creates an application package that include these files and settings.

You can also build and deploy the project using commands (see Build the PowerServer project with commands for details).

About the PowerServer Web API solution

The PowerServer Web API solution is generated during the build process. Clicking the Open C# Solution in SnapDevelop button () in the toolbar can launch the PowerServer Web API solution in SnapDevelop. Or go to the location where the Web API solution is generated; and double click PowerServerApp.sln to launch the solution in SnapDevelop or other C# editor such as Visual Studio.

The PowerServer Web API solution is an ASP.NET Core solution which contains three projects:

  • The PowerServer.Test project contains a tool that can check if the changes made to this solution will prevent the PowerServer Web APIs from running.

  • The AppModels project contains the C# data models (converted from the PowerBuilder DataWindows) and the embedded SQLs (ESQL) from the PowerBuilder application.

  • The ServerAPIs project contains the RESTful Web APIs for database connections, data processing, PowerServer license activation, and advanced features such as OAuth authorization, file server etc.

The ServerAPIs project contains a number of configurable files and a custom controller:

  • Properties\launchSettings.json: See https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-3.1#development-and-launchsettingsjson for details.

  • AppConfig\Applications.json: This file contains the basic information of the deployed applications, including the application name, session timeout value, transaction timeout value, mappings of transactions and connection caches.

  • AppConfig\Connection-Cache.json: This file contains the database connection strings, including the connection cache name, database type, data source settings, and some advanced settings.

  • AppConfig\License.json: This file contains the license information, including product ID, product key, secret key, etc. If you have imported and deployed the license file with the PowerServer project, then the license information will be stored to this file. If you have not imported and deployed the license file, then you should manually configure this file with the license file.

  • AppConfig\log4net.config: This file contains the logging settings for PowerServer. The "Console" section specifies to print the logging information in the console, the "RollingFile" section specifies the location, size, and backup of the log file, the "TraceAppender" section specifies to generate the trace log, the "ConsoleAppender" section specifies to print the logging information in the console and sets the font color of the logging information. For detailed syntax, refer to Apache Log4Net Manual.

  • Controllers\CustomController.cs: This file provides interfaces for getting all user sessions and killing a particular user session. For more information, see Get/Kill user sessions.

  • appsettings.json:

    • Logging: This section specifies the log level: Debug, Information, Warning (default), and Error.

    • AllowedHosts: Not available at the beta version.

    • PowerServer: This section specifies whether to enable authentication (True or False) and the IP address of the proxy server. Login credentials for the proxy server and exception list are not supported at this moment.

    • Email: This section must be configured first if you want to get notifications for license expiration. The settings include the SMTP server settings, sender email settings, and recipients.

    • Statistics: This section determines which type of transaction statistics will be generated and cached in the memory. Some settings are disabled by default to lower memory usages. You can also take advantage of the StatisticsController APIs in PowerServer NuGet package to get the statistics.


Compile and run the Web APIs

The PowerServer Web APIs are created during the deployment process and are ready to compile and run locally immediately after deployment.

To compile and run the Web APIs:

  1. Make sure your computer can connect with the NuGet site (https://www.nuget.org), so that the packages required for compiling and running the Web APIs can be successfully downloaded from the NuGet site.

  2. Click the Compile & Run Web APIs button () in the toolbar to compile and run the Web APIs in the debug mode.

  3. Check the Output window and make sure build is successful.

  4. Make sure the API console window displays "Application started...". Also notice "Now listening on: http://0.0.0.0:5009" in the console window. This is the URL for accessing the Web APIs. The port number can be modified in the launchSettings.json in the PowerServer Web API solution.

    When the installable cloud application is run later, you can view the logs in the console window to check if the requests and responses are processed successfully.


Run the installable cloud application

Note: IE and Edge Legacy (EdgeHTML-based) browsers should not be used to run the installable cloud app, as Microsoft will end support for IE and Edge Legacy soon. You can use one of the following supported browsers: Chrome, Firefox, and the new Edge browser (Chromium-based).

  • (For developers) Run the application by right-clicking the PowerServer project in the System Tree and then select Run PowerServer Project.

    Or click the Run PowerServer Project button () in the toolbar. The Run PowerServer Project button will be available in the toolbar when the Project painter for PowerServer is opened; if more than one Project painter for PowerServer is opened, then the settings in the currently active painter will be used to run the application. And the application will be run in the Web browser or in the Cloud App Launcher according to the configurations in the Run Options tab in the painter. However, if Cloud App Launcher is not installed, then the default Web Browser will be run to install the Cloud App Launcher and run the application.

  • (For developers and end users) Run the application in a Web browser for the first time.

    The user can input the application URL http://IPAddress/AppName in a Web browser to access the application. The IP address should point to the Web server where the installable cloud app is deployed. This URL can run the application with or without background process, depending on which startup mode the developer has selected as the default.

The cloud app launcher and the application must be installed through the Web browser for the first time. After that, users can directly double click the application icon on the desktop or the application shortcut on the Windows Start menu to run the application (the shortcut icon and menu are created by default unless the developer has changed the default settings in the Project painter for PowerServer).

If the application is started without the background service, the user will be asked by the Web browser whether to run the app launcher. This is a browser behavior. Select Allow. Then the following app entry page displays. If the download does not start automatically, click Download the Launcher to download and install the cloud app launcher first, and then click Start the Application to download, install, and start the application.


If the application is started with the background service, the following app entry displays. If the download does not start automatically, click to download and install the cloud app launcher.


You can view the logs in the API console window to check if the Web API requests and responses are successful.

Note

The virus-detection software McAfee WebAdvisor may block the CloudAppLauncher.exe file during the installation process. You can try adding the domain as a trusted site. To add the domain as a trusted site in McAfee WebAdvisor:

1. Right click the WebAdvisor add-on and select Options.

2. Under Manage your trusted sites, add the domain and click the + symbol.

3. Close and re-open the browser and run the installation again.

Note

If there is no response or progress when running the application, the CloudAppLauncher.exe file might be blocked by the Windows SmartScreen. You can try to turn off Windows SmartScreen in Control Panel > System and Security > Security and Maintenance > Change SmartScreen settings.

Note

Every time when the application launches, it needs to connect with the Web server to check updates, therefore, please make sure Web server is running and can be connected all the time.

Customize the app entry page

If you want to customize the license agreement and the visual displays (such as color, icon, text etc.) in the app entry page, you can make changes to the files under the %AppeonInstallPath%\PowerBuilder [version]\HTML folder, and then deploy the application again. The changes will apply to all applications deployed after the change is made.

Or you can directly make changes to the files under the application folder on the server, if you want to change that particular application only; but once you re-deploy that application, the changes will be lost.

  • license.html is the template for license agreement.

  • auto.html, autoconnect.html, autodownload.html, autoinit.html, and index.html are templates for applications started with background service.

  • manual.html, manualconnect.html, manualdownload.html, and index.html are templates for applications started without background service.

Customize the loading animation

You can also deploy your own animation to replace the default animation (if you have selected "Show the loading animation before the app runs").

To deploy your own animation,

  1. Prepare a GIF format of your animation and name the file as "loading_ica.gif". Only GIF format is supported currently.

  2. Place "loading_ica.gif" under the same directory as the application target (.pbt) file.

  3. Add "loading_ica.gif" under Files preloaded as compressed packages or Files preloaded in uncompressed format in the External Files page.

Package the installable cloud application

When deploying the PowerServer project as an installable cloud app, you can choose to package the application as an executable installer or a zipped file, and then install the application to the Web servers.

To package the installable cloud app:

  1. Go to the Client Deployment tab of the PowerServer project, and then click Package the compiled app and manually deploy later.

  2. Specify to generate the package as an executable installer or a compressed zip file, and select whether to package the cloud app launcher and the PowerBuilder Runtime files.

    If you select Zipped file, an appname_Installer.zip file is generated in the specified path. You can copy the zip file to the server and then decompress it to the Web root.

    If you select Executable installer, an appname_Installer.exe file is generated in the specified path. You can copy the executable file to the server and then run it to install the application to the Web root.

  3. Specify the location where the package will be generated.


  4. Save the project settings and then click the Build & Deploy PowerServer Project button () or Deploy PowerServer Project () button in the toolbar to generate the package.

Note

Do not manually change the name of the installed or de-compressed application folder on the server, otherwise the application uninstall program will fail to run.

Change the Web API URL for an application

After the application is deployed or packaged, the Web API URL for this application can be changed using the ChangePowerServer.exe tool.

To change the Web API URL for an application:

  1. Go to the Web server root folder and find the application folder, and then run the ChangePowerServer.exe file in the "1.01" folder under the application folder. You might be required to run the tool using an administrator (by right-clicking it and then selecting "Run as administrator").

    The ChangePowerServer.exe tool is automatically installed when you select to install the PowerServer Compiler in the PowerBuilder Installer; and then it is automatically included in the application when you deploy the application or package the application as an executable installer and/or the zipped file.

    After the application is deployed from the PowerBuilder IDE, or installed from the executable installer or the zipped file, the ChangePowerServer.exe tool exists in the "1.01" folder under the application folder.


  2. Specify the Web API URL and then click Save.

  3. Run the application again. The application will connect with the PowerServer Web APIs using the new URL.

    The ChangePowerServer.exe file can only be run in Windows. For applications installed to Linux, you can change the Web API URL before copying the application package to Linux (by packaging the application as a zipped package, then decompressing the package and running ChangePowerServer.exe to specify the Web API URL, and then compressing the package again and copying the package to Linux).

Build and deploy the PowerServer project with commands

Instead of building and deploying the PowerServer project from the PowerBuilder IDE, you can also build and deploy the project using the PBAutoBuild210 command. For step-by-step guidance, refer to Tutorial 6: Building your PowerServer project with commands. The PBAutoBuild210 command can integrate with Jenkins to automate the build and deployment process for PowerServer projects. Refer to the Jenkins user documentations for how to use Jenkins.

To build and deploy the PowerServer project with commands:

  1. Export the configurations of the PowerServer project to the JSON file.

    1. Make sure the PowerServer project painter is opened.

    2. Click the Export PowerServer Build File button () in the toolbar.

    3. In the Export Build File dialog box, specify where to save the exported file and how to overwrite the settings if the file already exists. Click Export.


    The exported JSON file will not only include the settings required for compiling, packaging and deploying the PowerServer project, but also include

    • Settings for downloading and merging source code from the source control server (including SVN, Git, and/or VSS).

      Locate the "SourceControl" section to configure the settings.

    • In the "SourceControl" and "BuildJob" sections, you could also specify commands that can be executed before and/or after that particular section is executed.

      Locate the "PreCommand" and "PostCommand" keywords to specify the commands or command file, for example,

      "PreCommand": "SourcePre.bat"

      The commands in "PreCommand" and "PostCommand" can be executed in synchronous (default) or asynchronous mode, and the command window can be visible or invisible (default). For example,

      "PostCommand": "D:\\PB2021\\Sales_Demo\\postcmd.bat /show /async"

    Note: Relative paths are not supported well in the beta version. Use absolute path instead.

  2. Execute the PBAutoBuild210.exe file and the JSON file in a command line to automatically build and deploy the project. For example,

    PBAutoBuild210 /f c:\pssales.json

    The PBAutoBuild210.exe file is by default located under the PowerBuilder Compiler installation folder (for example, %AppeonInstallPath%\PowerBuilderCompiler [version]).

    The PBAutoBuild210.exe file supports the following parameters:

    • /f -- specify the configuration file. The configuration file (in JSON format) can be directly exported from the PowerBuilder IDE, as described in step 1.

      PBAutoBuild210 /f c:\pssales.json
    • /p -- specify the password for logging into SVN, Git, or VSS. This will generate an encrypted value based on the password. If the password contains the double quotation mark ("), use the escape character \" to replace ".

      PBAutoBuild210 /p 123456
    • /l -- write the logging information to a file. For example,

      PBAutoBuild210 /f c:\pssales.json /l c:\deploy.log
    • /le -- write the error information to a file.

    • /h or /? -- display the help information. For example,

      PBAutoBuild210 /h


Get/Kill user sessions

The CustomController.cs file in the PowerServer Web API solution provides interfaces for getting all user sessions and killing the specified session.

To get all user sessions, you can write PowerScripts as below:

//-------------------------------------getSession-----------------------------------------
httpclient  lhc_client
string ls_url
string ls_json

lhc_client = create httpclient

//GetSessions
ls_url = "http://localhost:5000/api/custom/getAllsessions"
//This URL should be replaced with the actual IP address and port number of PowerServer Web APIs
//If there are multiple PowerServer Web API servers, obtain one by one
//lhc_client.SetRequestHeader("Authorization", $token, true)  //If authorization is enabled
lhc_client.sendrequest("Get",ls_url)

if lhc_client.getresponsestatuscode() = 200 then
                lhc_client.getresponsebody(ls_json)
                //parse the json
                wf_getsessions(ls_json)
end if

//-------------------------------------------------------------------------------------------------

To kill the specified user session, you can write PowerScripts as below:

Step 1: Get all the user sessions first.

Step 2: Kill the specified session according to sessionid.

The session information returned will look like this:

[{"sessionid":"85b78052-8692-4281-82e9-dbbefed31055","sessionstate":2,"createtime":"2021-05-06T03:35:30.7323321Z","lastvisittime":"2021-05-06T03:39:25.4715132Z"},{"sessionid":"ca54aa7d-5fd6-429a-a2c0-494eb3be820d","sessionstate":2,"createtime":"2021-05-06T03:35:21.0329275Z","lastvisittime":"2021-05-06T03:35:24.5604784Z"}]
//-------------------------------------killSession-----------------------------------------------

httpclient  lhc_client
string ls_url
string ls_sessionid

lhc_client = create httpclient

//GetSessions
//lhc_client.SetRequestHeader("Authorization", $token, true)  //If authorization is enabled
ls_url = "http://localhost:5000/api/custom/KillSession"
//This URL should be replaced with the actual IP address and port number of PowerServer Web APIs

ls_sessionid = lb_sessionlist.selecteditem()
ls_url += "/"+ls_sessionid

lhc_client.sendrequest("post",ls_url)

if lhc_client.getresponsestatuscode() = 200 then
                messagebox("succeed",ls_sessionid +" was killed")
end if
//-------------------------------------------------------------------------------------------------------------------

Undeploy the PowerServer project

To undeploy the PowerServer porject from the server:

  1. Right-click the PowerServer project in the System Tree and then select Undeploy PowerServer Project from the popup menu.

  2. Select whether to remove the entire project (all deployed versions) or only the selected version from the server.


Uninstall the PowerServer project

To uninstall the PowerServer project from the client machine:

  1. Uninstall the application by selecting the Uninstall shortcut menu from the Windows Start | [appname].

    The Uninstall menu and the [appname] menu are available only when the developer selected to create the Start menu shortcut and App uninstall shortcut in the Run Options page of the Project painter for PowerServer. If the Uninstall menu is not available, you can run the Uninstall.exe file in the application folder, for example, %AppData%\PBApps\Applications\localhost_pssales\Uninstall.exe (%AppData%\PBApps is configurable when uploading the Cloud App Launcher and runtime files).

    Note: If the application folder name (which is named after [appname]) on the server has been changed manually, the application uninstall program will fail to run.

    The uninstall program will automatically remove the following:

    • The application shortcuts on the desktop and the Windows start menu.

    • The application folder under %AppData%\PBApps\Applications, for example, %AppData%\PBApps\Applications\localhost_pssales.

      The application folder contains all of the application files and any external files (such as UI theme files, DLLs/OCXs, images/videos, INIs etc.) that are deployed with PowerServer. This folder will be automatically deleted during the uninstall process.

    However, the uninstall program will NOT automatically remove the following:

    • The registration information of DLL/OCX files in the Windows registry.

      If you have selected to register the DLL/OCX files (using Regsvr32 by default), you will need to remove the registry information manually. Follow instructions in step 4 below.

    • The runtime files under %AppData%\PBApps\Applications\Runtime.

      The PowerBuilder Runtime files are used by all deployed apps on the client machine. You can manually delete the runtime files if they are no longer used.

    • The download folder under %AppData%\PBApps, for example, %AppData%\PBApps\Download.

      This folder stores the download statistics of the app and runtime files. It can be manually deleted.

  2. Uninstall the cloud app launcher by uninstalling Cloud App Launcher from Control Panel\Programs\Programs and Features.

    If the cloud app launcher without background service is uninstalled, the %LocalAppData%\Launcher folder will be removed.

    If the cloud app launcher with background service is uninstalled, the %LocalAppData%\LauncherWithService folder will be removed.

  3. Uninstall the cloud app service by uninstalling Cloud App Launcher Service from Control Panel\Programs\Programs and Features.

    The cloud app launcher service is installed only when the launcher with background service which supports multiple Windows users is installed.

  4. Remove the registry information of DLL/OCX files.

    The registry information of DLL/OCX files (or any other files that are installed and registered by your own) will not be automatically removed during the application uninstall process.

    To clean up the registry information of the DLL/OCX files, you can write scripts (a sample shown below) and place them in a file named ManualUninstall.cmd, place the ManualUninstall.cmd file under the same directory as the application target (.pbt) file, add ManualUninstall.cmd under Files preloaded as compressed packages or Files preloaded in uncompressed format in the External Files page, and then deploy the application.

    The scripts in ManualUninstall.cmd will be automatically run when the application uninstall program is run. (If the file requires administrator rights to unregister, you should run the application uninstall program with administrator rights.)

    You can also add scripts in ManualUninstall.cmd to clean up any other files that are installed and registered by your own.

    The following is a sample script for unregistering DLL/OCX files that are registered by Regsvr32:

    set Driver=%~d0
    set HOMEDIR=%~dp0
    %Driver%
    cd %HOMEDIR%
    regsvr32 /u .\dllname
    regasm   /unregister .\AssemblyName