Installing CaseMaster

Installation involves a number of steps:

  • Create application folder with all relevant sub-folders
  • Copy CaseMaster runtime folder
  • Install primary database
  • Verify settings in configuration file
  • (optional) Install application on IIS

The quickest way to get going is to install the primer training project. This application comes with a self-contained SQLite database and, like all CaseMaster web applications, can be run using Kestrel which requires no additional installation or configuration.

Running Under Kestrel

Using Kestrel as the web server is convenient for CaseMaster development. It is not recommended to use Kestrel directly for production purposes; instead use IIS to proxy requests to Kestrel (which happens behind the scenes).

In VSCode you can start caseMaster.web.exe which can be found in the runtime folder of your application. This will start the Kestrel web server and will listen to port 5000 for HTTP requests.

If you want to use another port or use HTTPS, you best create a VSCode task (by adding task definition to .vscode/tasks.json).

    {
        "label": "dotnet: run",
        "type": "process",
        "command": "${workspaceFolder}/runtime/CaseMaster.Web.exe",
        "args": [
            "--server.urls",
            "${config:casemaster.baseUri}"
        ],
        "problemMatcher": []
    }

Create a self-cert using the following .Net command:

dotnet dev-certs https

Make sure to add the following to .vsCode/settings.json:

{
    "casemaster.baseUri": "https://localhost:5001",
    "casemaster.rejectUnauthorized": false
}

The reject unauthorized setting is needed as by default self signed certs will be rejected by the vscode extension.

Running Under IIS

It is beyond the scope of this document to describe the usage of IIS in detail. Please refer to documentation online.

  1. Download the .Net IIS Hosting bundle (make sure to download and install this specific version)
  2. Create an application pool and set to recent CLR version and integrated managed pipeline mode
  3. Create application and point to runtime folder of the application

Some considerations (assuming an understanding of configuring IIS):

  1. Number of worker processes
  2. Application pool identity
  3. Binding and security certificates
  4. Number of worker processes

Set-up VSCode

The recommended editor for CaseMaster development is Microsofts VSCode. In the primer training project you will also find the CaseMaster VSCode extension.

There are a number of VSCode extensions that are useful:

Extension Benefits
CaseMaster Mandatory for any serious CaseMaster developer
exe Runner Allow you to run executable from within VSCode; useful to run Kestrel web server
All autocomplete Autocomplete based on text found in any of the open windows
Notepad++ Introduces the fantastic Notepad++ keyboard shortcuts; do not install at your own peril

The Application Folder

A CaseMaster application folder has a number of reserved folders:

Folder Purpose
bo Business objects
document Document templates
log Log files
page Page definitions
qualifier Qualifiers
runtime CaseMaster runtime folder
script Scripts
service Services
static Static files (e.g. Javascript, images)
trace Trace files

The Configuration File

In the root of the application folder you will find a number of key configuration files:

File Purpose
configuration.cms The master configuration file (can be used on all environments)
environment.cms Defines the environment (development, test or production)
incDevelopment.cms Extra configuration items for development environment
incTest.cms Extra configuration items for test environment
incProduction.cms Extra configuration items for production environment

Connecting to the Database

CaseMaster connects to a databases using a concept known as datasources. Each application must have at least one datasource known as the primary datasource. The primary datasource must point to a relation database that has a number of essential CaseMaster specific tables (such as user, userLogin, session, sequence and others).

You will that many CaseMaster applications only have the primary datasource.

The set-up of datasources is typically found in one of the environment-specific configuration include files (see here). The following is an example from a random incDevelopment.cms file:

resource main
    <
        dataSources: <@configuration/dataSources
            primary: <@configuration/dataSource/sqlite
                type: dataSourceType.primary
                connectionString: $formatString( 'Data Source={0}', fileSystem.buildPath( app.runtimeDir(), '..', 'data', 'database', 'cm2.0Training.db' ) )
            >
        >
    >
end-resource
  • This specific example uses the SQLite RDBMS
  • The connection string is a standard database connection string; see for examples here
  • There can only be one entry with type primary; any other datasource would have the type alternative (of which there can be multiple)
  • The datasource type channel is reserved for a future CaseMaster version

/