Install Live Agent as a Windows Service

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

Uninstall (Optional)

If a previous version of the agent is installed, you may want to perform the following steps to uninstall it:

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: 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.

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

Note: The agent will not be present in the Windows Control Panel if an xcopy install was used.

Install Executable

1.Get the latest .msi installer from the EarthSoft Community Center Downloads Dashboard (Products > EQuIS Live), or contact EarthSoft Support to get an xcopy install.

Note: Always get the latest version of the agent to ensure that you have the latest features and bug fixes. A Live agent running as a Windows service runs independently from other EQuIS products and will work with any EQuIS database version.

2.Unblock downloaded files.

3.Run the .msi installer (to extract the files), or copy and paste the xcopy install files (to any folder), on the computer that the agent is to run.

Note: If the agent is already installed, the .msi installer may not allow you to perform a new installation. In this case, manually copy, and rename, the existing agent's folder, and update the copy's .config files.

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 in the agent's .config file.

•When connecting to a self-hosted SQL Server instance that is not configured with a SSL certificate issued by a known certificate authority (CA), you must include TrustServerCertificate=True; in your connection string.

•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.

Setting

Example(s)

Description

serviceNameSuffix

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" />).

Note: 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.

Apply and/or Review License

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

Install 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.

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 the agent. 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).

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.Right-click the service and select 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 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).