Install Live Agent as a Windows Service

<< Click to Display Table of Contents >>

Navigation:  Live > Installation and Configuration >

Install Live Agent as a Windows Service

This document applies to EQuIS Live Agents that can be installed as Windows Services:

Agent Service

File Processor

Hardware Monitor

LoggerNet

MIS

 

Notes:

Multiple instances of an agent can be run at the same time, on the same computer, using the serviceNameSuffix App Setting (in the agent's .config file), which allows creation of unique service names. (If running multiple agent instances, also update the log4net.config file's log file location and/or name so that each instance is logging to a different log file.)

If the agent is already installed, the installer (.msi file) may not allow you to perform a new installation. In this case, manually copy, and rename, the existing agent's folder (e.g., copy C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\ to C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent B\), and update the copy's .config files.

 

Uninstall

 

(Optional) If a previous version of the agent is installed, perform the following steps to upgrade to a newer version:

 

1.Make a backup copy of your *.config files (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\):

a.EarthSoft.Live.Agents.LoggerNet.exe.config

b.log4net.config

 

2.Uninstall the service:

a.Right-click the Uninstall.ps1 file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\Uninstall.ps1), and Run with PowerShell. Type y when prompted to confirm, and press Enter.
 
Note: Uninstall.ps1 is not included with agents released prior to 2020.
 
Or
 

b.Open a Command Prompt, run as an Administrator. Change to the folder where the agent's executable is installed (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\) and uninstall the service by running a command line on the executable. Below is an example of a command line for uninstalling the LoggerNet Agent as a Windows Service:
 
EarthSoft.Live.Agents.LoggerNet.exe uninstall

 

3.Uninstall the the agent's executable (e.g., Name = EarthSoft EQuIS Live LoggerNet) from the Windows Control Panel.

 

 

Install Executable

1.Download the the appropriate version of the agent (.zip) from the EarthSoft Community Center Downloads Dashboard (Products > EQuIS Live).

2.Unblock the downloaded ZIP file.

3.Extract the downloaded ZIP file.

4.Run the .msi file (e.g., EarthSoft_EQuIS Live LoggerNet_Live_7.0_x64.msi).

5.Next > ☑ I accept the terms of the License Agreement > Next > select the installation folder (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\) > Next > Install > Finish.

 

 

Database Connection

1.Open the agent's .config file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\EarthSoft.Live.Agents.LoggerNet.exe.config) in a text editor (e.g., Notepad++).

2.In the <connectionStrings> section, find the item with name="databaseConnection".

3.Set the connectionString value, e.g.,

Data Source=sql-038-equisonline-com.database.windows.net; User ID=live.logger; Password=your.password; Database=DBNAME; Connection Timeout=600;

Data Source=acme-corp-prd-equis.database.windows.net,1433; User ID=a user; Password=a password; Database=EQUIS; Connection Timeout=600; Encrypt=True; TrustServerCertificate=False;

 

Notes:

The connectionString requires an SQL (e.g., Microsoft SQL Server) login. An Application-Level Security (ALS) login (aka EQuIS Enterprise login) cannot be used to connect to the database.

The encrypt command line option (below) can be used to encrypt the connectionString value.

 

4.Set the providerName to EarthSoft.Common.Data.SqlConnection (Microsoft SQL Server).

5.Save and close the .config file.

 

 

App Settings

 

Users may change one or more app settings in the agent's .config file. See the agent's help page for a list of available app settings (e.g., LoggerNet app settings).

 

All EQuIS Live Agents that can be installed as Windows Services support the following app settings:

 

Setting

Example(s)

Description

serviceNameSuffix

A

If this setting is not empty, the agent will append this suffix to the service name when installing the Windows Service.

 

For example, set this setting to 'B' to set the service name to 'EarthSoft.Live.Agents.LoggerNet B'.

 

This setting allows users to create unique service names, and thus run multiple instances of an agent at the same time, on the same computer (e.g., to add file data to two different databases).

 

Note: If the service is installed before changing this value, run Uninstall.ps1 to uninstall the service (and remove the old service name). Then, after changing this value, run Install.ps1 to install the service (and add the new service name).

 

If this setting is not present in the *.config file, users can add it.

useNetworkLicenses

true or false

If this setting is true, the agent will use "network" licenses, which are stored in the ST_LICENSE table in the database, else if it is false, the agent will use "local" licenses, which are saved in the agent's *.config file, in the licenses section.

 

The log4net.config file contains the agent's logging settings, e.g., log to file (RollingLogFileAppender) %env{temp}/equislogs/{process}.log (<file type="log4net.Util.PatternString" value="%env{temp}/equislogs/{process}.log" />), using logging level all (i.e., <level value="all" />).

 

 

Review Network License

 

Follow these steps to apply and/or review the Live license.

 

 

Install Agent as Windows Service

 

Right-click the Install.ps1 file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\Install.ps1), and Run with PowerShell. Type y when prompted to confirm, and press Enter.

 

Or, open a Command Prompt, run as an Administrator. Change to the folder where the agent's executable is installed (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\) and install the service by running a command line on the executable. Below is an example of a command line for installing the LoggerNet Agent as a Windows Service:

EarthSoft.Live.Agents.LoggerNet.exe install

 

 

Review Windows Service

1.Open Windows Services (e.g., use Windows shortcut keys Win + R to launch Run > type services.msc into the dialog box and press the Enter key).

2.Find the service (e.g., EarthSoft.Live.Agents.LoggerNet).

3.Verify its Startup Type (e.g., it should be Automatic (Delayed Start) if you want the agent to start up with the operating system, and not require any user interaction).

4.Verify its Log On As account. The account should be able to connect to the database (specified in the agent's .config file), and read and write to all the files and folders that the agent will use. For example, the agent's executable folder (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\), the agent's watched files and folders (if the agent watches files and folders), and the agent's log folder (specified in the agent's log4net.config file).

 

Note: The log file is a good starting point for troubleshooting problems with these agents. Right-click the Menu.ps1 file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\Menu.ps1), and Run with PowerShell to view and open the log files.

 

 

Start Windows Service

 

Note: Some agents may require additional setup before being started (e.g., you may add data logger(s) before starting LoggerNet).

 

Start the service using one of the following methods:

 

1.Windows Services; e.g., right-click EarthSoft.Live.Agents.LoggerNet.exe > start.
 
Or
 

2.Right-click the Menu.ps1 file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\Menu.ps1), and Run with PowerShell. Type start, and press Enter.
 
Or
 

3.Open a Command Prompt, run as an Administrator. Change to the folder where the agent's executable is installed (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\) and start the service. Below is an example of a command line for starting the LoggerNet Agent Windows Service:

EarthSoft.Live.Agents.LoggerNet.exe start

 

 

Command Line Options

 

All EQuIS Live Agents that can be installed as Windows Services support the following command line options:

 

Option

Description

[none]

Run the agent as a console process. (Note: The agent must be started manually, by the user, when the computer is restarted, if it is run as a console process, and not a Windows Service.)

encrypt

For example, encrypt "a string", or encrypt "Data Source=acme-corp-prd-equis.database.windows.net,1433; User ID=a user; Password=a password; Database=EQUIS; Connection Timeout=600; Encrypt=True; TrustServerCertificate=False;"

help

Show the agent's command line options and their descriptions.

install

Install the agent as a Windows Service.

log *

Open log file (e.g., log 1).

logdir *

Open log directory (e.g., logdir 1).

register

Deprecated: In EQuIS 7, Live licenses are applied through EQuIS Professional: Applying Network Licenses.

 

Set the useNetworkLicenses App Setting to true, to use "network" licenses, which are stored in the ST_LICENSE table in the database, or set it to false, to use "local" licenses, which are saved in the agent's *.config file, in the licenses section. Then show this registration screen to view / save license keys. (Note: Local licenses are being phased out.)

start

Install (if not installed) and start the agent as a Windows Service.

status

Show the status of the agent's Windows Service (only applicable if the executable has been installed as a Windows Service).

stop

Stop the agent's Windows Service (only applicable if the service is running).

uninstall

Stop (if running) and uninstall the agent's Windows Service (only applicable if the executable has been installed as a Windows Service).

 

See the agent's help page for a list of all available command line options (e.g., LoggerNet command line options).

 

Right-click the Menu.ps1 file (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\Menu.ps1), and Run with PowerShell to view and run these commands.

 

 

PowerShell Scripts

 

The PowerShell scripts (e.g., C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent\*.ps1) provide a more convenient way to install (Install.ps1) and uninstall (Uninstall.ps1) the Windows Service, and view and run the agent's command line options (Menu.ps1) than using a Command Prompt.

 

To run a *.ps1 file, right-click it, and choose Run with PowerShell.

 

If a PowerShell script does not run, it may be due to the PowerShell execution policy. (Check that the file is unblocked first!) The PowerShell execution policy can be viewed (e.g., Get-ExecutionPolicy -List), and changed (Set-ExecutionPolicy RemoteSigned) from a PowerShell prompt, run as an Administrator. However, a safer option may be to manually add the script's certificate to the local computer certificate trust (e.g., right-click one of the *.ps1 files > Properties > Digital Signatures > select the signature > Details > View Certificate > Install Certificate… > Local Machine > Next > Place all certificates in the following store > Browse... > Trusted Root Certification Authorities > OK > Next > Finish).