Host TurboPlayer Service in a Windows Service - Multiple configurations

Requirements

• Run PowerShell as an Administrator

• Since v2.0.74.0, the majority of TurboPlayerService API’s require the TurboPlayerServiceLicense.dll be present

Prepare the Environment (If Necessary)

• Download the complete TurboPlayerService software package

  • IMPORTANT: at the moment, the TurboPlayerService.deps.json, TurboPlayerService.runtimeconfig.json and runtimes/ should exist in the package in order to have it successfully running

Install .NET 6 Runtime and .NET 6 Core Runtime

Visit https://dotnet.microsoft.com/en-us/download/dotnet/6.0

• Download the “..NET 6 Runtime” and install it.

  

• Download the “.NET 6 Core Runtime” Hosting Bundle and install it.

  

Create service configuration in the Parameters Service

Create service configuration with all necessary parameters for all planned service instances as described here DigaSystem registry subkeys and parameters

Create configuration files

Create file ConfigurationName.json

Create file ConfigurationName.json for every configuration, a separated configuration file with the name ConfigurationName.json must be created in the service directory. This file contains parameters to get access to the external services & configuration uses for the current service instance. E.g.

This file is the standard configuration file for .NET 6 Core applications and is mandatory to start the service. See more information here Service configuration file - Multiple configurations, how to create & configure it

Hint. By the first installation rename the file template_AppSettings.json to ConfigurationName.json This file contains all parameters required for service configuration and requires only to fill with the real values (e.g. URLs for the DPE services)

Create file log4net.json

This file contains configuration for the file log and strongly recommended being configured. Service can use this log if DPE Log Service isn’t available or logged information is too big. See more information here Logging, how to create & configure it

Hint. By the first installation rename the file template_log4net.config to log4net.config This file contains a typical configuration for file log and can be used without changes in mostly standard workflows even with multiple service configurations workflows or can be used as a start point to optimize file log for custom workflows.

Create the Windows Service

Create Windows service for every service instance

To create the Windows Service for every service instance, use the native Windows Service Control Manager's (sc.exe) create command.

sc.exe create "$TurboPlayerServiceInstanceNameOfYourChoice" binpath="C:\Path\To\TurboPlayerService.exe /configuration:ConfigurationName"
# OUTPUT: [SC] CreateService SUCCESS

Parameter “binpath” : Full qualified path name to your TurboPlayerSerivce.exe. This string can also include command line arguments, interpreted by TurboPlayerSerivce. For multiple instance configuration you must provide the configuration name by the “/configuration” parameter.

Argument: /configuration: [nameOfYourConfigurationInDigaSystemRegistry]

Check the result

After successfully creating the all services, you can find it in the Windows Services, such as the following.

Configure the Windows Services

The services can be configured like all other typical Windows services via context menu and dialogs.

Start and Stop the Windows Service

When you followed the configuration steps, the service can be started and stopped like all other typical Windows services. (As a general reminder, a complete configuration would typically include an ConfigurationName.json configuration files (like for all other .NET 6 applications; TurboPlayerService release contains a template_appsettings.json for reference) and correctly configured DigaSystem registry parameters (which is unique to TurboPlayerService as specified in the aforementioned configuration page.).)

Define the URLs to use

This part is not specific to TurboPlayer Service hosted in a Windows Service. It is also valid when TurboPlayer Service is hosted by other containers, such as a PowerShell environment. However, it makes sense to keep it here to ease the installation of TurboPlayer Service hosted in a Windows Service.

By default, the TurboPlayer Service like all other standard .NET 6 Core web applications will listen on port 5000 if no URL and port definition given.

In general, there are several ways to define the Urls for a .NET 6 Core web applications. However, in the context of an application hosted in a Windows Service, there is just one recommended way, as given in the following.

The recommended way is to define Urls in the appsettings.json file or in the DigaSystem registry under the subkey "TurboPlayerService". The easiest way is to do it in the appsettings.json file.

The Urls follows the standard pattern supported by all standard .NET 6 Core web applications. (The value provided can be one or more HTTP and HTTPS endpoints (HTTPS only if a default cert is available). Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").)

For only HTTP, it is recommended to use the "Urls"  in ConfigurationName.json:

{
  "Urls": "http://*:11250"
}

For both HTTP and HTTPS, it is recommended to use "Kestrel" in appsettings.json:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://*:11250"
      },
      "HttpsInlineCertFile": {
        "Url": "https://$FQDN:11251",
        "Certificate": {
          "Path": "C:\\Path\\To\\ValidCertificate.pfx",
          "Password": "$Password"
        }
      }
    }
  }
}

N.B. The HTTPS URL will not work automatically without making the following HTTPS configuration. In fact, it will stop TurboPlayer Service from successfully starting.

There are many more different ways to configure HTTP URLs and HTTPS URLs. For the biggest possibility, please reference the documentation given by Microsoft at https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-6.0.

(Worth mentioning, according to some comments on the Internet, when the key "Kestrel" is configured, the key "Urls" may not take effects.)

Verify the running TurboPlayer Service instance

TurboPlayerService API to check WebSocket requests

• {{service_host_name_or_ip}}/turbo/ws

  • GetVersion

Delete the Windows Service

To delete the Windows Service, use the native Windows Service Control Manager's (sc.exe) delete command.

sc.exe delete "$TurboPlayerServiceInstanceNameOfYourChoice"
# OUTPUT: [SC] DeleteService SUCCESS

Troubleshooting

Windows could not start the service on Local Computer

There could be many causes which lead to this issue.

1. The first diagnose method is to start the TurboPlayerService as a CLI program and check the output.

2. The second diagnose method is to check the log file (for example, Log/TurboPlayerService.log) for possibly useful information.

In Windows PowerShell: The required library hostfxr.dll could not be found.

It could be the .NET 6 runtime is not installed, please try to install the .NET 6 runtime environment as given in the "Prepare the Environment" section.

Example

Requested configuration

Requested steps

• Create service configurations TPS0, ExternalTPS and TPSRegional. See DigaSystem registry subkeys and parameters for details

• Create service configuration files TPS0.json, ExternalTPS.json and TPSRegional.json See Service configuration file - Multiple configurationsfor details

• Create file log configuration file. See Logging for details

• Install TurboPlayerService as Windows service “Instance0” with configuration name TPS0 via followed command line

  CODE

  sc.exe create "Instance0" binpath="C:\Path\To\TurboPlayerService.exe /configuration:TPS0"

• Install TurboPlayerService as Windows service “ExternalTPS” with configuration name TPS1 via followed command line

  CODE

  sc.exe create "ExternalTPS" binpath="C:\Path\To\TurboPlayerService.exe /configuration:ExternalTPS"

• Install TurboPlayerService as Windows service “RegionalTPS” with configuration name TPSRegional via followed command line

  CODE

  sc.exe create "RegionalTPS" binpath="C:\Path\To\TurboPlayerService.exe /configuration:TPS