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 6 as a self-contained application.
Please note versions before 2.12 require .NET Framework 4.6 or later.
-
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.
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.1) 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:
C:\Users\[UserName]\AppData\Local\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",
}
}
}
}
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 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.