What is the PowerServer C# solution

The PowerServer C# solution is generated when you select the Build & Deploy Project button () in the toolbar. After the solution is generated, you can click the Open C# Solution in SnapDevelop button () in the toolbar to launch the PowerServer C# solution in SnapDevelop. Or go to the location where the solution is generated; and double click PowerServer_[appname].sln to launch the solution in SnapDevelop or other C# editor such as Visual Studio.

The PowerServer C# solution is an ASP.NET Core solution which contains the following projects:

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

  • The ServerAPIs project contains the PowerServer Web APIs. The PowerServer Web APIs is RESTFul APIs for handling the database connections, data processing, PowerServer license activation etc. You can run the ServerAPIs project to start the PowerServer Web APIs. For detailed steps, refer to Hosting Web APIs in Kestrel.

  • The ServerAPIs.Tests project contains a number of test cases which can check if the PowerServer Web APIs is running correctly after the ServerAPIs project is modified. See Running the ServerAPIs.Tests project for more details.

  • The UserExtensions project contains miscellaneous tools such as logging, authentication, management APIs etc. And as the project name suggests, you can customize and enhance this project by adding additional code and functionalities in this project, and they will remain unchanged and unaffected even when the solution is upgraded.

Among these projects, only the ServerAPIs and UserExtensions projects contain configurable files and controllers. The following highlights the important files and settings only.

ServerAPIs project:

  • Properties\launchSettings.json: This file contains the environment settings for running the PowerServer Web APIs in the local development environment. For more information, refer to About PowerServer Web APIs and Kestrel.

UserExtensions project:

  • AppConfig folder

    • AppConfig.json: This file specifies the environment (such as the DB connection profile) to be used when starting PowerServer Web APIs.

      "POWERSERVER_ENVIRONMENTTYPE": Specifies the DB connection profile used for starting PowerServer Web APIs. By default, the DB connection profile that is currently selected in the project painter > Database page is set in this file. Refer to Create the DB connection profile for more information.

      "ConnectionStrings": Specifies the connection string of the database. You could store the database connection (including the cache, application settings, and transaction-to-cache mappings) in this database instead of in Applications.json or Applications.[DBConnectionProfile].json, so that you could modify, add, or delete the database connection through APIs. For more, refer to Managing database connections using APIs.

        "POWERSERVER_ENVIRONMENTTYPE": "Default",
      
        "ConnectionStrings": {
          "AppConfig": "<appconfig connection string>"
        }
    • AppConfig.xml: This file sets the environment (mainly the DB connection profile) to be used when publishing the PowerServer Web APIs.

      The default value is empty, meaning that all of the configured DB connection profiles will be deployed.

      <POWERSERVER_ENVIRONMENTTYPE></POWERSERVER_ENVIRONMENTTYPE>
    • Applications.json or Applications.[DBConnectionProfile].json: This file contains the basic information of the deployed applications and the database connection cache settings.

      • "Applications": This block includes a list of the deployed applications and the mappings of transactions and connection caches, timeout values for transaction, session, and request, and run mode (0-normal mode, 1-test mode) of each deployed application.

        Take the following settings for example, in the "salesdemo_cloud" application, the "sqlca" transaction object is mapped to the "sales" database cache. Refer to Managing transaction-to-cache mappings in PowerServer for more information.

        To understand and set appropriate timeout values for "Transaction", "Session" and "Request", refer to Configure the timeout settings.

        You can run the application in test mode ("RunMode": 1) if you want to perform load-testing for the application. For more, refer to Tutorial: Load testing installable cloud apps.

        The MaxSPCache setting specifies the maximum number of stored procedures for which the driver caches information. The driver retrieves information from the server about a stored procedure's parameters the first time the stored procedure is called and caches that information. The next time the procedure is called, the driver retrieves the information from the cache to improve performance. The information is retrieved based on the stored procedure's name. The name is case sensitive. If you call two different stored procedures with the same name, you can turn off caching by setting the value of MaxSPCache to 0.

          "Applications": {
            "salesdemo_cloud": {
              "CloudTransactions": {
                "sqlca": {
                  "CacheName": "sales"
                }
              },
              "Transaction": {
                "Timeout": 120,
                "TransactionException": true
              },
              "Session": {
                "Timeout": 3600
              },
              "Request": {
                "Timeout": 3600
              },
              "RunMode": 0,
              "MaxSPCache": 50
            }
          },
      • "Connections": This block includes a list of the cache groups and caches. Refer to Managing database caches in PowerServer for more information.

          "Connections": {
            "Default": {
              "local-sa": {
                "ConnectionType": "Odbc",
                "OdbcName": "PB Demo DB V2022R2",
                "OdbcDriver": "SqlAnywhere",
                "UserID": "dba",
                "Password": "eyJQYX...",
                "CommandTimeout": 30,
                "SecurityOptions": null,
                "OtherOptions": null,
                "DynamicConnection": false       
              }
            }
          }
  • Authentication folder: This folder contains the template and built-in server for the selected authentication type. Refer to Tutorial: Authenticating your apps for more information.

  • Controllers folder

    • ApplicationController.cs: This file provides APIs for dynamically adding, modifying or removing the application settings and transaction mappings.

    • ConnectionController.cs: This file provides APIs for dynamically adding, modifying or removing the cache or cache group.

    • LicenseController.cs: This file provides APIs for dynamically accessing the license information.

    • SessionController.cs: This file provides APIs for getting all user sessions or killing a particular user session.

    • StatisticsController.cs: This file provides APIs for getting statistics of the request and transaction.

    • TransactionController.cs: This file provides APIs for getting all transactions or rolling back a particular transaction.

    For documentation of these APIs, refer to Use PowerServer Management APIs.

  • HealthChecks folder: For more information, refer to Check the status of Web APIs and the readme.txt file under Solution Items.

  • Logging folder: For more information, refer to Configure the log settings.

  • OpenAPI folder: The OpenAPI Specification for exposing the API documentation in Swagger UI.

  • UserConfig.json or UserConfig.Development.json: This file contains settings related with the server. As you can use multiple environments in ASP.NET Core (read more), there can be multiple configuration files, for example, UserConfig.json will take effect in the production environment (for example, when Web APIs are published and running in IIS, docker etc.), while UserConfig.Development.json will take effect in the development environment (for example, when Web APIs is running from the PowerBuilder IDE or SnapDevelop IDE).

    • "AllowedHosts": Specifies the host names to bind with PowerServer. Refer to Host filtering for more information.

    • "PowerServer": This block specifies the settings for PowerServer.

      • "LicenseKey" & "LicenseCode": PowerServer license information. Refer to Importing the PowerServer license for more information.

      • "EncryptedSensitiveData": Sensitive data refers to the database login password which is used to create the database connection cache in Applications.json. If the password is an encrypted value (encrypted automatically by IDE or manually by the CustomizeDeploy.dll tool), this setting should be set to True; if the password is not encrypted (still a plain-text string), this setting should be set to False so that PowerServer will encrypt the password for you and store the encrypted value to the database. If this setting is set to True and you input a plain-text password, the plain-text password will be directly stored to the database.

      • "ProxyOptions": The IP address and login credentials of the proxy server. If the Web API host server connects to Internet through a proxy server, you will need to configure the proxy server settings here. The password for the proxy server must be an encrypted value (encrypted by the CustomizeDeploy.dll tool).

      • "EmailOptions": This block 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. Refer to Configuring the email settings for more information.

      • "StatisticsOptions": This block 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 to get the statistics.

        "PathBase": null,
        "AllowedHosts": "*",
      
        "PowerServer": {
          "LicenseKey": "DSCE-IHFG-CHEI-51H3-G0BE",
          "LicenseCode": "eyJQYXlsb2FkIjoiVT*****",
          "EncryptedSensitiveData": false,
          "AppModelsAssemblyNames": [ "AppModels.dll" ],
          "ProxyOptions": {
          ...
          },
          "EmailOptions": {
          ...
          },
          "StatisticsOptions": {
          ...
          },

For files that are not mentioned here, refer to the readme.txt file under Solution Items for more information.