Users Guide
Creating Executables and Components

To configure a deployment server:

1. Set up a Web server according to the documents provided by the vendor.

   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.

2. Select Tools > (PowerClient) Web Server Profile from the menu bar to open the Web Server Profile window.

   
   
   

3. In the Web Server Profile window, click Add to configure a local or remote Web server where the application will be deployed.

   • To configure a local Web server, select the Local Server button and specify the Web root of the Web server (for example %systemdrive%\inetpub\wwwroot for IIS) or a subdirectory under the Web root. Click Test File Path to make sure the specified path is valid for deployment.

     Note

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

   • To configure a remote Web server, select the Remote Server button. You will need to specify the profile name and the following FTP settings: host name, port number, user name, password, and encryption settings. Click Test FTP Connection to make sure the specified settings are correct for deployment. The FTP user must have the read and write permissions in order to transfer files to the FTP server successfully.

     
     
     

   The server configuration will be used by all PowerClient 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.

   Note

   As PowerBuilder is designed to be case-insensitive, therefore, in a case-sensitive system like Linux, some app files (such as images) may not be found or loaded. To avoid any issue caused by the case of file name, make sure to configure the Linux server to ignore case-sensitive.

To create a PowerClient 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 PowerClient project type and click OK.

   The Project painter for PowerClient 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. 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.

To build and deploy a PowerClient 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 PowerClient Project button in the toolbar, or right-click the PowerClient project in the System Tree and then select Build & Deploy PowerClient Project to compile and deploy the application to the server. Or select Deploy PowerClient Project if you have already built the application before.

   The application executable file (as well as an XML file with the same name and the object files) is generated under %PBAPPSCACHEDIR%\[appname] (%PBAPPSCACHEDIR% points to %TEMP%\pbappscache\temp\) on the development machine, then digitally signed, and deployed to the server.

   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.

To build and deploy the PowerClient project with commands:

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

   1. Click the Export PowerClient Build File button () in the toolbar if the PowerClient project painter opens, or right click the PowerClient project object (or target or workspace) and then select Export Build File.

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

      If you right click the workspace and then select Export Build File, you can select one or more targets to export the build file for, and then select one or more project types to export if there are more than one type of project objects in the selected target(s). If you select more than one project type, the corresponding project objects will be exported to the build file > "Projects" > [project object name]. If the selected targets contain project objects with the same name, only the object listed last will be added to the build file.

      Select "Export the Git/SVN SourceControl settings (if exists) from the project" if you want to export the Git/SVN source control settings (such as login username, password, source code path etc.) to the build file. The password will be encrypted automatically.

      Specify how to overwrite the source code settings if the build file already contains such settings. Existing settings will be kept by default. If you want to export the current settings, such as login username, password (encrypted), source code path etc. to the build file, you should select "Clear existing settings". If you have selected "Clear existing settings", while have not selected "Export the Git/SVN SourceControl settings (if exists) from the project", then existing settings will be removed and no settings will be stored.

      Specify how to overwrite the build job settings and project settings if the build file already contains such settings. Such settings will be cleared by default.

      
      
      

   3. Click Export.

   The exported JSON file includes every single setting that is required for compiling, packaging and deploying the PowerClient project. It also contains a "BuildPlan" block which provides additional configurations. For more, see About the build file.

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

   PBAutoBuild220 /f c:\salesdemo_local.json /l Log_PCBuild.log /le Log_PCError.log

   The PBAutoBuild220.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.

     PBAutoBuild220 /f c:\salesdemo_local.json

   • /l -- write the logging information to a file.

   • /le -- write the error information to a file. For example,

     PBAutoBuild220 /f c:\salesdemo_local.json /l Log_PCBuild.log /le Log_PCError.log

     The relative path specified in the parameter is relative to the path of the configuration file. In the above example, the log files will be generated under the same path as the configuration file.

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

     PBAutoBuild220 /p 123456

   • /v -- specify the product version (property displayed for executable).

     /fv -- specify the file version (property displayed for executable).

     /vn -- specify the product version (executable version used by installer).

     /fvn -- specify the file version (executable version used by installer).

     You can specify for multiple projects at the same time, in this format: "[projectname1]:1.0.0.1;[projectname2]:1.2.3.4". Projects are separated with semicolons (";"). For example,

     PBAutoBuild220 /f c:\test.json /v "project1:1.0.0.1;project2:1.2.3.4" /vn "project1:1.0.0.1;project2:1.2.3.4" /fv "project1:1.0.0.1;project2:1.2.3.4" /fvn "project1:1.0.0.1;project2:1.2.3.4"

     If no project name is specified, the version number will be used by all projects. For example,

     PBAutoBuild220 /f c:\test.json /v "1.0.0.1"

     The version numbers specified by parameters take precedence over those specified in the build file.

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

     PBAutoBuild220 /h

3. Check if PBAutoBuild220 command is successful via errorlevel. For more information, refer to Verifying if PBAutoBuild is successful.

To package the PowerClient project:

1. Click the PowerClient project in the System Tree and then select the Client Deployment page.

2. Click the "Create a package" button and specify the location where the package will be generated.

3. Specify to generate the package as an executable installer or a compressed zip file.

   
   
   

   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 file, 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.

   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.

To undeploy the PowerClient project from the server:

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

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

To uninstall the PowerClient 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 in the Startup page > Basic tab of the Project painter for PowerClient. If the Uninstall menu is not available, you can run the Uninstall.exe file in the application folder, for example, %AppData%\PBApps\Applications\localhost_app1\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_app1.

     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 PowerClient. 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 public version of the cloud app launcher is installed, it can only be uninstalled by the administrator.

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

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

To run CustomizeDeploy.dll in Windows Web server:

1. Install the ASP.NET Core Runtime 3.1 or later.

2. Open the command prompt. (You'd better run the command prompt using an administrator by right-clicking it and then selecting "Run as administrator").

3. Navigate to the Web server root folder > [application] folder > "1.01" (for example, C:\inetpub\wwwroot\sales\1.01).

4. Execute the CustomizeDeploy.dll file using the dotnet command.

To run CustomizeDeploy.dll in Linux Web server:

1. Install the ASP.NET Core Runtime 3.1 or later.

   dnf install aspnetcore-runtime-5.0

2. Go to the Web server root folder > [application] folder > "1.01" (for example, /var/www/html/sales/1.01, or /usr/share/nginx/html/sales/1.01).

3. Right click the blank area within the folder and then select Open in Terminal.

4. Execute the CustomizeDeploy.dll file using the dotnet command. Notice that the command and file name are all case-sensitive in the Linux OS.