Installing ScriptX.Services for Windows PC
ScriptX.Services for Windows PC requires
- Microsoft Windows Windows 10 (1803) or later on an Intel x64 (compatible) PC.
ScriptX.Services for Windows PC components:
-
A self host web application server that provides the REST API to be called by clients to perform printing. The application is self configuring with the printers available to the PC and is implemented with .NET Core as a self-contained application.
Please note versions before 2.12 require .NET Framework 4.6 or later runtime is already installed.
-
The ScriptX Print Server - a COM based server (MeadCo ScriptX Broker/Host) that provides the pagination and printing facilities that is called by the REST API.
-
Orchestrator. Pre v2.17 this component is optional but required/highly recommended if there may be multiple users concurrently signed in to Windows. From v2.17.0 onwards Orchestator is built-in to Script.Services for Windowsd PC but its use remains optional.
Orchestrator for ScriptX.Services as a service is required when shared host environments such as Citrix or RDS are in use.
Installation and use
A single installer is available that will install both web server and print service and a default configuration that is suitable for most use-cases.
The default configuration has these key aspects:
The default configuration can be customised on a per-user basis.
-
Download the latest version (2.23.2) of ScriptX.Services for Windows PC:
-
Run the downloaded installer.
In order for the installers to run, you must be logged on to your computer as an Administrator.
ScriptX.Services for Windows PC is now available to any browser at any time.
Using Microsoft Edge or Google Chrome 92 or later?
Microsoft Edge and Google Chrome 92 and later on Windows 10 may by default block communication between an insecure origin site and server hosting on the local loopback address
127.0.0.1.Because of this origin sites using ScriptX.Services for Windows PC to provide printing must be secure unless the feature is disabled (see //flags and search for "Block insecure private network requests").
Other/older browsers do not block communication.
Customising the configuration if required
As installled:
To view the configration in use navigate to the server dashboard (this link assumes the default port works).
Each of these aspects can be changed by defining configuration values in the appsettings.json file.
This file should be edited/created in the user's local application data folder:
%LOCALAPPDATA%\MeadCo\ScriptXServices (or Powershell: $env:LOCALAPPDATA\MeadCo\ScriptXServices).
An empty appsettings.json file is simply this:
{
}
To configure the server, add sections as described below to between these top level braces {}, for example:
{
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
}
}
}
}
Please see the “Alternatives to set configuration” section below for alternatives to editing appsettings.json.
Standard Port Configuration
To configure the port used, create an appsettings.json file similar to this:
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
}
}
}
The value given to "Port" can be any value that is free on your systems.
Port conflicts
ScriptX.Services for Windows PC does not run as a system service, it runs per user.
From v2.15 onwards if the configured port is in use (by a concurrently logged in user) then the next available free port will be used (the port used is written to the appsettings.json file).
This will cause problems for client javascript which assumes that the port is always the same.
Orchestrator works around this issue by ensuring that the port it uses doesnt cause a conflict with concurrently signed in users. This means client javascript can assume the port is the same and use the Orchestrator API to determine the port for ScriptX.Services for Windows PC.
Configuring use of Built-in Orchestrator
The default port for Orchestrator is 41190. If this would cause a conflict with other software, to configure the port used, add a section to appsettings.json file similar to this:
{
"Orchestrator": {
"Endpoints": {
"Http": {
"Port": 40100
}
},
}
}
Where Port is a port number that is not in use on the system
Configuring use of Orchestrator as a Service
Configure the use of Orchestorator as a Service as follows
{
"Orchestrator": {
"Endpoints": {
"Service": {
"Port": 40100
}
},
},
}
Where Port is the port number in use by Orchestrator as a Service on your system.
And also:
{
"ServerHost": {
"OrchestratorKey": "[username]"
}
}
The value of "OrchestratorKey" can be any string value but must be unique for each user. "[USERNAME]" can be included in the value and will be replaced by the active users name.
Support for https:
To support https a server certificate for localhost must be installed and recognised as valid by the browsers that are to be used. Such a certificate may already be installed, in which case it will be used.
If there is a port clash for https, then configure the port to be used by create an appsettings.json file similar to this:
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
},
"Https": {
"Port": "45679",
"Certificate": {
"Source": "localhost",
}
}
}
}
ScriptX.Services Server Configuration
Settings are available to tune the http server used by ScriptX.Services for Windows PC.
These settings are defined at the top level of the “appsettings.json” file, for example:
"ServerHost": {
"MaxConcurrentConnections": 24,
"Endpoints": {
}
}
The following values are supported:
| Name | Default value | Description |
|---|---|---|
| MaxConcurrentConnections | 24 | This value shouild not need to be changed. However if network logging shows errors due to saturation, increase the value. |
| PersistUsedPorts | false | Once the available port has been claimed it is written back to the user's appsettings.json file at "ServerHost:EndPoints:Http". Assuming the system is in default configuration this will occur when the user signs-in. It will then be possible for other processes to determine the port in use by the user. This feature is deprecated by Orchestrator. For all versions prior to 2.23.3 the default is true. |
Enable logging assistance
Logging is available and configured in the same way as for all .NET Core applications with a section similar to this:
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
},
"File": {
"Name": "service.log"
}
}
ScriptX.Services for Windows PC enables logging to the Debug output stream. If you wish to log to a file, add a "File" section as shown above.
If no path specification is given the file will be created in the folder:C:\Users\[UserName]\AppData\Local\MeadCo.
Please note that for v2.15.4 and earlier log files were written to (if no path given): C:\Users\[UserName]\AppData\Local\MeadCo\ScriptXServices.
The log file name will be as given in configuration during normal operation. If the application is being run to perform a shutdown during uninstall or upgrade the name will be prefixed with "Shutdown-"
For use cases where log files are written to a common location/file share "[USERNAME]" can be included in the file name and will be replaced by the active users name.
ScriptX.Services job control behaviour
Settings are available to tune ScriptX.Services for Windows PC processing of jobs and the job queue.
These settings are defined at the top level of the “appsettings.json” file, for example:
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
}
}
"EnsurePrintDefaultsPerJob": true
The following values are supported:
| Name | Default value | Description |
|---|---|---|
| ForgetTimeout | 120 | Time (s) before a job is removed from memory cache after completion. Clients that request job status should have stopped enquiring for status before this timeout. |
| StaleTimeout | 60 | Time (s) before a job is removed from memory cache after failure or is considered abandoned - successfully completed a print to file but the file was not collected. |
| HungTimeout | 300 | Time (s) in which a job must complete or it will be considered to have entered a hung state and will be stopped and abandoned. |
| CacheDevices | false |
Controls whether to cache the details of printer devices available on the system. If false then the list of available printers and printer settings are repeatedly requested with a consequent performance impact. However printer information will always reflect the status on the system (for example the current default printer). If true the list of available printers and their settings are loaded on first request and on subsequent requests details are returned from the cache with a consequent performance improvement. |
| EnsurePrintDefaultsPerJob | false |
If true then the printer settings are reset to their (system) default values before applying the settings defined for the current job. If false then printer settings for a job are continued from the previous job and updated with those settings defined for the current job. |
ScriptX Services behaviour tuning
A number of settings are available to tune the behaviour of ScriptX Services (the web server).
These settings are defined at the top level of the “appsettings.json” file, for example:
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
}
}
"DoNotReplyAllowPrivateNetwork": false
The following values are supported:
| Name | Default value | Description |
|---|---|---|
| DoNotReplyAllowPrivateNetwork | false | Diables support for Access-Control-Request-Private-Network header in CORS preflight request. Set to true to disable adding the response header "Access-Control-Allow-Private-Network: true" when Access-Control-Request-Private-Network: true is present in the preflight check. |
| KeyCookieLifetime | 0 | [Deprecated] For versions prior to 2.20.0 is the lifetime of a cookie to remember the user in multi-user scenarios. |
| EnablePrintProcessorRecycling | false | The print processor will be stopped during background tidying (see below) iff there no active print jobs. The processor will restart when next used. |
| BackgroundTidyPeriod | 300 | The time in seconds between each sweep during which housekeeping tasks such as deleting temporary files created by print jobs are performed. |
| GetUpdateVersion | false | If true, the codestore service (see below) is contacted at startup for details on the latest available version. The dashboard will highlight if a new version is available. |
| Codestore | https://codestore.meadroid.com/ | The address of the servioce providing details on available versions |
| LicenseWarehouse | //licenses.meadroid.com | Url to the MeadCo license file (.mlf) store. This url is used to replace "warehouse&quit; or "securewarehouse" |
| AllowBuiltinOrchestratorInRemoteSessions | false |
Applies to v2.20.0 and later. If set to true this will allow built-in orchestrator (if configured) to start in a remote session, e.g. if using Remote Desktop to a desktop PC (not server) for support purposes.
When false (default) built-in orchestrator will not start when it is determined that a remote session is in use. This is required when users are using a shared environment such as RDS or Citrix or Orchestrator will attempt to start for every user on the *same* port, which cannot happen. In these configurations, Orchestrator as a Service should/must be used. |
| PDFPrintProcessor | ScriptXServer | The print engine to use for printing PDF files. Valid values are "PDFium" or "ScriptXServer". |
| HTMLPrintProcessor | ScriptXServer | The print engine to use for printing HTML files. Valid value is "ScriptXServer". |
ScriptX Server behaviour tuning
A number of settings are available to tune the behaviour of ScriptX Server (the print processor).
It is extremely rare for these values to need to be changed from their defaults.
Values can be defined in a section “ScriptXServer”. For example:
"ScriptXServer": {
"IgnoreSecurityIssues": true,
"PrintHtmlLoadTime": 25,
}
The following values are supported:
| Name | Default value | Description |
|---|---|---|
| IgnoreSecurityIssues | false | Set true to work around a problem in the mshtml print engine where loading content to print from a secure (https) server on a local domain that is known to have a valid certificate fails. |
| AllowCertRevocationFailure | false | Set true if a local secure https server is using a certificate whose revocation cannot be checked (for example it does not have access to the internet). |
| LoadSnippetToPrintDelay | 500 | Time delay (ms) before re-trying a check that a document using the html:// psuedo protocol (i.e. a string - this applies to print page or print frame with ScriptX.Service) is ready to print (see also PrintHtmlLoadTime). |
| LoadHtmlToPrintDelay | 500 | Time delay (ms) before re-trying that a document loaded from a url is ready to print (see also PrintHtmlLoadTime). |
| PrintHtmlLoadTime | 20 | The number of attempts at re-trying a document is ready to print. |
| PrintStartWaitTime | 500 | Time to allow (ms) for the print template to initialise. |
| PrintInitTimeout | 4000 | Time (ms) to allow for the PrintHtmlServer browser to start and initialise. If this fails the error “Error initializing the MeadCo PrintHTML server, operation timed out.” will be reported. |
| ExtendedPrintStartWaitTime | 40000 | Time to allow (ms) for the print routine to complete passing of required print settings to the printer. If this value is too small the error “Print Template processing is still in progress.” will be reported. |
| SpoolerStartWaitTime | 60000 | Time to allow (ms) for initial pagination of the document to complete. If the job takes longer it is considered stalled and stopped. |
Alternatives for setting configuration
An alternative to editing the user’s appsettings.json file is to use the environment settings.
This is useful to configure a setting for a user or for all users.
All values can be thought of as appearing in a hierarchy of section names leading to a value name. For example:
"ServerHost": {
"Endpoints": {
"Http": {
"Port": "45678"
}
}
The value “Port” can be written as ServerHost__Endpoints__Http__Port = “45678”.
The above can be used as an environment variable, by prefixing with “MEADCOSCRIPTX_”, either per user or for all users.
For example:
- Press Windows + R to open the Windows Run prompt.
- Type in sysdm.cpl and click OK.
- Open the Advanced tab and click on the ‘Environment Variables’ button.
- The Environment Variables window is divided into two sections. The sections display user-specific and system-wide environment variables. To add a variable, click the New… button under the appropriate section.
- Enter the variable name (e.g. ‘MEADCOSCRIPTX_ServerHost__Endpoints__Http__Port’) and value (e.g ‘45678’) in the New User Variable prompt and click OK.
Configuring logging with environment variables
Configuration of logging was discusssed above with the following example in appsettings.json:
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
},
"File": {
"Append": true,
"Name": "service.log"
}
}
To configure with envionment variables:
| Name | Value |
|---|---|
| MEADCOSCRIPTX_Logging__LogLevel__Default | Debug |
| MEADCOSCRIPTX_Logging__LogLevel__System | Information |
| MEADCOSCRIPTX_Logging__LogLevel__Microsoft | Information |
| MEADCOSCRIPTX_Logging__File__Append | true |
| MEADCOSCRIPTX_Logging__File__Name | service.log |
Testing printing
See:
How to configure samples for use with ScriptX.Services for Windows PC.
Deployment of the evaluation license for your own testing and evaluation.