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 describes each of the pages and options you can specify in the Project painter for PowerServer.

General page

Option

What you specify

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 Distributing resources in PowerBuilder User 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 the 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 Using the DEBUG preprocessor symbol in PowerBuilder User 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 Attaching or embedding manifest files in PowerBuilder User 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

Page

What you specify

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

Page

What you specify

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.)

    You can specify the update strategy for the INI file by clicking the INI Configuration button. More details are provided below.

  • DLL/OCX files (requiring no administrator rights to register)

    You can specify which DLL/OCX files can be registered by Regsvr32 or Regasm by clicking the DLL & OCX Registration button. More details are provided below.

  • 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 or Regasm without requiring the administrator rights, you can click DLL & OCX Registration to select the DLL/OCX files so that they can be registered by Regsvr32 or Regasm automatically before the application starts; if the DLL/OCX files need to be registered but cannot be registered by Regsvr32 or Regasm or they need to be registered using administrator rights, 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

Page

What you specify

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

Page

What you specify

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

Option

What you specify

Deployment mode

Select to deploy the client app 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 client app as an executable installer or a zipped file, and then install the client-side to the Web servers. For more about packaging a client app, refer to Package the client app.

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

Option

What you specify

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).

You can also pass arguments to the EXE directly. If there are multiple arguments, please include them in quotation marks or separate them with a delimiter (instead of a space), for example,

C:\Users\<username>\AppData\Roaming\PBApps\Applications\localhost_<appname>\<appname>.exe "parm1 parm2 parm3"

C:\Users\<username>\AppData\Roaming\PBApps\Applications\localhost_<appname>\<appname>.exe parm1/parm2/parm3

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.

App shortcut

You can specify whether to create the following shortcuts:

  • 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.

You can also customize the app shortcut name and the shortcut icon (the icon file must be added to the External Files tab first before it can be selected here).

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 Regasm or require administrator rights to register; or any other commands that need to be executed with administrator rights.

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

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.

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.

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 page

Option

What you specify

Web API Generation

Specify the location, name, authentication template, and 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.

If the PowerServer C# solution has already been created before, you can select an existing solution from the Solution name list, and then deploy the app to the existing solution; if you re-deploy an app to an existing solution, the application data models and ESQLs will be updated in the solution, and if you deploy a new app to an existing solution, the application data models and ESQLs will be added to the existing solution.

You can also choose whether to overwrite the server settings (such as license, launch settings etc.) and the authentication template in the solution. Apps 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 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.

Important

The port number in the Web API URL will be deployed to the PowerServer C# solution; so that when PowerServer Web API starts, it starts at the specified port number.

And the complete Web API URL will be deployed to the Web server, so that the client knows where to call the PowerServer Web APIs.

License settings

You can click Auto Import to directly obtain and import the license from the Appeon sites, or click Import from File to select and import the license file.

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# models during the deployment process; and 2) when accessing data from the database at application runtime.

See Configure the database connection for more details.