Command Reference

Creating a session ID

Standard Session ID

dotnet ./<agent-path>/SL.DotNet.dll config --appName <arg> --branchName <arg> --buildName <arg> --includeNamespace <arg> [--excludeNamespace <arg>] [--include <arg>] [--exclude <arg>] [--buildSessionId <arg> | --buildSessionIdFile <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
appName	Name of the application
branchName	The source branch of the application
buildName	The build label of the current build
includeNamespace	Comma-separated list of namespaces to include in scan. Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: 'com.example.*,io.*.demo,com.?ello.world'
excludeNamespace	Comma-separated list of packages to exclude from scan. Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: 'com.example.*,io.*.demo,com.?ello.world'
include	Comma-separated list of files to include in scan. Default: *.exe, *.dll Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: '*-with-dependencies.dll,bad-bad?.exe,*-source.dll' This is a regex so to include all sub directories and files use the .*
exclude	Comma-separated list of files to exclude from scan. Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.dll,bad-bad?.exe,*-source.dll'
buildSessionId	Optional: A user provided session ID
buildSessionIdFile	Optional: A user provided Build Session ID file.
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed
identifyMethodsByFqn	(optional) Allows the agent identify methods by the fully qualified name (FQN) and support pipelines with multiple compilations of the same version

Pull Request Session ID

dotnet ./<agent-path>/SL.DotNet.dll prConfig --appName <arg> --pullRequestNumber <arg> --targetBranch <arg> --latestCommit <arg> --repositoryUrl <arg> --includeNamespace <arg> [--excludeNamespace <arg>] [--include <arg>] [--exclude <arg>] [--buildSessionId <arg> | --buildSessionIdFile <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
appName	Name of the application
pullRequestNumber	The number assigned to the Pull Request from the source control
targetBranch	The branch to which this PR will be merged into (already reported to SeaLights)
latestCommit	The full SHA of the last commit made to the Pull Request
repoUrl	The pull request URL for the PR to be scanned, up until the section before the pullRequestNumber value
includeNamespace	Comma-separated list of namespaces to include in scan. Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: 'com.example.*,io.*.demo,com.?ello.world'
excludeNamespace	Comma-separated list of packages to exclude from scan. Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: 'com.example.*,io.*.demo,com.?ello.world'
include	Comma-separated list of files to include in scan. Default: *.exe, *.dll Supports wildcards (* = any string, ? = any character, space character is not allowed). For example: '*-with-dependencies.dll,bad-bad?.exe,*-source.dll' This is a regex so to include all sub directories and files use the .*
exclude	Comma-separated list of files to exclude from scan. Supports wildcards (* = any string, ? = any character). For example: '*-with-dependencies.dll,bad-bad?.exe,*-source.dll'
buildSessionId	Optional: A user provided session ID
buildSessionIdFile	Optional: A user provided Build Session ID file.
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed
identifyMethodsByFqn	(optional) Allows the agent identify methods by the fully qualified name (FQN) and support pipelines with multiple compilations of the same version

Scanning a build

Scanning files

The project must contain all the PDB files!

dotnet ./<agent-path>/SL.DotNet.dll scan {--buildSessionId <arg> | --buildSessionIdFile <arg>} --workspacePath <arg> --ignoreGeneratedCode true [--firstModule {true|false}] [--uniqueModuleId <arg>] [--baseDir <arg>] [--scm <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
workspacePath	Path to the source workspace
firstModule	Must be provided when scanning the first module
uniqueModuleId	A unique module ID to be used for seperate modules
baseDir	Base path where all relative paths should start from. By default the agent searches for the solution file and uses its path for this value
hashingAlgorithm	Hashing algorithm to use. Available options are md5 (default), sha1, sha256, sha384, sha512
scm	The SCM that is used in order to provide integration with. Values: auto, git, none
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed
ExtraScanDir	Scan additional folder to collect more runtime components (.git/dll/exe ) for scanning. The path is an absolute path.
extraDbgSearchDirs	Comma-separated list of absolute paths to the folders where the agent will recursively search for *.pdb files

Ending multi-modules scan

dotnet ./<agent-path>/SL.DotNet.dll reportBuildStatus {--buildSessionId <arg> | --buildSessionIdFile <arg>} --success <true|false> [--message <arg>] [--duration <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
success	Indicates that the build succeeded (considered failed if not specified)
message	Additional build status message to report (optional)
duration	Build duration in milliseconds (optional)

Coverage Collection operation

Starting the Application/Process via the Agent (run command)

A single process can be run with the SeaLights agent as a test listener to capture the test footprints or events from a testing framework (like MSTest, NUnit, and XUnit).

dotnet ./<agent-path>/SL.DotNet.dll run {--buildSessionId <arg> | --buildSessionIdFile <arg>} --target <arg> [--workingDir <arg>] [--instrumentationMode {tests|coverage|testsAndCoverage}] [--targetArgs <arg>] [--labId <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]] [--profilerRegistrationMethod <path32|path64>]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
target	Name of the application to run with the test listener
workingDir	Path to working directory. Current working directory will be used if not specified
profilerRegistrationMethod	Sets the COM32 profiler DLL registration method.
targetArgs	Command line arguments to pass the target application
labId	Unique ID for a set of test labs in case multiple labs are running simultaneously
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed
tags	(Optional) One or several tags (comma separated) to be passed to Sealights in order to label this instance in the cockpit. Any free text (without spaces) is allowed, like --tags tag1,tag2
instrumentationMode	(Optional) Set instrumentation mode, default value is testsAndCoverage. Possible values: tests reporting test events only (for functional testing) coverage reporting coverage only (for agent connected to the application under test) testsAndCoverage reporting both test and coverage (for In-Process testing like Unit Tests, Integraiton Tests or Components Tests)
tiaDisabled	(Optional) Set to true to disable getting TIA Recommendations from Sealights Backend (Default: false).

Configuring a Background Listener

Environment variables required for Background test listener

You need to run your process with the following environment variables:

.NET Core/ Windows

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={01CA2C22-DC03-4FF5-8350-59E32A3536BA}
CORECLR_PROFILER_PATH_32=SL.DotNet.ProfilerLib.Windows_x86.dll
CORECLR_PROFILER_PATH_64=SL.DotNet.ProfilerLib.Windows_x64.dll
SL_CollectorId=SL_Agent

.NET Core/Linux

Parameter	Description
CORECLR_ENABLE_PROFILING	Enable Sealights profiling to capture coverage by setting the value to 1.
CORECLR_PROFILER	Linux: {3B1DAA64-89D4-4999-ABF4-6A979B650B7D} Windows: {01CA2C22-DC03-4FF5-8350-59E32A3536BA}
CORECLR_PROFILER_PATH_32	Name of the profiler executable for an x86 architecture: Linux: libSL.DotNet.ProfilerLib.Linux.so Windows: SL.DotNet.ProfilerLib.Windows_x86.dll
CORECLR_PROFILER_PATH_64	Name of the profiler executable for an x64 architecture: Linux: libSL.DotNet.ProfilerLib.Linux.so Windows: SL.DotNet.ProfilerLib.Windows_x64.dll
SL_CollectorId	A random alphanumeric ID that was provided during the startBackgroundTestListener
SL_LogLevel	Optional: Level of logs to generate - Default is 0 (none), Fatal=1, Error=4, Debug=6, All=999
SL_LogDir	Optional: Folder to save log files in

Starting Background test listener

dotnet ./<agent-path>/SL.DotNet.dll startBackgroundTestListener {--buildSessionId <arg> | --buildSessionIdFile <arg>} --testListenerSessionKey <arg> [--labId <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
testListenerSessionKey	A random alphanumeric ID (%RANDOM% in command line) This ID needs to be passed to any process that you want to capture cover
labId	Unique ID for a set of test labs in case multiple labs are running simultaneously
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

Stop Background test listener

dotnet ./<agent-path>/SL.DotNet.dll stopBackgroundTestListener {--buildSessionId <arg> | --buildSessionIdFile <arg>} --testListenerSessionKey <arg> [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
testListenerSessionKey	A random alphanumeric ID that was provided during the startBackgroundTestListener
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

MS Windows - Specific commands

Installing/Uninstalling the Coverage Collector service

SL.DotNet.CoverageCollectorService.exe {install {start} | unsinstall }

Parameter	Description
install	Install the Coverage Collector Service
start	Start the service
uninstall	Uninstall the service. This command should be executed alone. This is commonly used when upgrading your agent version, as it is needed to uninstall the coverage collector service from the machine first.

Register the Profiler for a Windows Service

This command will add the Environment REG_MULTI_SZ record to the target service inside the Windows registry (Related Windows Registry path: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services) with a list of the environment variables required to start the Sealights profiler.

SL.DotNet.exe instrumentService --serviceName <arg> {--force} {--undo}

Parameter	Description
serviceName	REQUIRED Target service name
force	Forces overwriting existing registry entries. Default value: false
undo	Unregister the Profiler and removes the Environment Variables from the Registry.

Register the Profiler for IIS

This command registers the Sealight profiler with two specific IIS services: WAS and W3SVC. So this command is equivalent to instrumentService running twice (for each of these IIS services).

SL.DotNet.exe instrumentIIS {--force}

Parameter	Description
force	Forces overwriting existing registry entries. Default value: false
undo	Unregister the Profiler and removes the Environment Variables from the Registry.

Starting coverage collection session

SL.DotNet.exe startCollectorServiceSession {--buildSessionId <arg> | --buildSessionIdFile <arg>} [--labId <arg>] --processName <arg> --applicationPool <arg> --includeChildProcesses {true|false} [--token <arg> | --tokenFile <arg>] [--machine <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
processName	Name of the executable to collect coverage from. If you’re running several services on the machine, you can use --processName * and every service having the Sealights' environment variables defined in its Registry entry will be metered For .NET Core processes, set --processName dotnet, as this is the name of the process on which .NET Core applications run. For IIS, provide w3wp.exe
applicationPool	For IIS, provide the Application pool. Since there could be multiple applications running on a single IIS server, it is important to make note of the Application Pool name that corresponds to the hosted application from which coverage will be collected. You can provide a star (*) to the applicationPool parameter in order to capture of all the Application Pools at once. This start (*) option can be used for troubleshooting or if your IIS server is dedicated to your application but is not necessarily defined as a best practice.
labId	Unique ID for a set of test labs in case multiple labs are running simultaneously
machine	(Optional) IIS Host to start the session remotely on.
proxy	Address of proxy to run connection through. To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

Stopping coverage collection session

SL.DotNet.exe stopCollectorServiceSession --stopAllSessions --processName <arg> --applicationPool <arg> [--machine <arg>]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
stopAllSessions	Close all the sessions at once.
processName	If you’re running several services on the machine, you can use --processName * and every service having the Sealights' environment variables defined in its Registry entry will be metered For .NET Core processes, set --processName dotnet, as this is the name of the process on which .NET Core applications run. For IIS, provide w3wp.exe
applicationPool	For IIS, provide the Application pool. Since there could be multiple applications running on a single IIS server, it is important to make note of the Application Pool name that corresponds to the hosted application from which coverage will be collected. You can provide a star (*) to the applicationPool parameter in order to stop capture of all the Application Pools at once.
labId	Unique ID for a set of test labs in case multiple labs are running similtaniously
machine	(Optional) IIS Host to stop the session remotely on.

Reporting a Test Stage

Starting a test stage

dotnet ./<agent-path>/SL.DotNet.dll startExecution {--buildSessionId <arg> | --buildSessionIdFile <arg>} --testStage <arg> [--labId <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

Parameter	Description
token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
testStage	Name of the test stage
labId	Unique ID for a set of test labs in case multiple labs are running similtaniously
proxy	Address of proxy to run connection through. To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

Upload report files

dotnet ./<agent-path>/SL.DotNet.dll uploadTestReport {--buildSessionId <arg> | --buildSessionIdFile <arg>} --testStage <arg> --report <arg> [--labId <arg>] [--token <arg> | --tokenFile <arg>] [proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

token	Access token generated from the SeaLights server
tokenFile	Path to file containing the access token generated from the SeaLights server
buildSessionId	Session ID of configuration created
buildSessionIdFile	Path to file containing the Session ID of configuration created
testStage	Name of the test stage
report	Path to report file or directory containing all the valid reports (Non recursive). Supported formats are MSTest (TRX files), xUnit.Net and NUnit (XML files).
labId	Unique ID for a set of test labs in case multiple labs are running simultaneously
proxy	Address of proxy to run connection through. To use the system proxy just provide the value 'system'.
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

Ending a test stage

dotnet ./<agent-path>/SL.DotNet.dll endExecution {--buildSessionId <arg> | --buildSessionIdFile <arg>} --testStage <arg> [--labId <arg>] [--token <arg> | --tokenFile <arg>] [--proxy <arg> [--proxyUsername <arg> --proxyPassword <arg>]]

token	Access token generated from the SeaLights server
tokenfile	Path to file containing the access token generated from the SeaLights server
buildsessionid	Session ID of configuration created
buildsessionidfile	Path to file containing the Session ID of configuration created
labId	Unique ID for a set of test labs in case multiple labs are running similtaniously
proxy	Address of proxy to run connection through To use the system proxy just provide the value 'system'
proxyUsername	The proxy username if needed
proxyPassword	The proxy password if needed

Logging

If you're facing technical issue, you can consult our dedicated FAQ section at .Net/.NetCore as we’ve listed there the most common problems and solutions for your benefit.

Agents Commands

To enable logs when executing direct agent commands, you can set the following parameters with any of the above commands Both console output and file options are compatible and non-exclusive.

For logging into the console and a file, add

--logPreset Debug --logDir C:\Sealights\Logs\

For logging only into the console, add

--logPreset Debug --logAppendFile false

Parameter	Description
logPreset	Set the log preset. Allows managing several log-related options at once and has precedence on LOG_LEVEL. The default preset is Default. See below the available options.
logAppendConsole	Set to false to disable log output to the console. Default is true.
logAppendFile	Set to true to enable log output to a file
logFilename	Provide the name of the log file
profilerLogLevel	Level of logs to generate by the Profiler entity as a Integer value: Default is 0 (none), Fatal=1, Error=4, Debug=6, All=999 Value from this options will be passed to the environment variable SL_LogLevel. This option is available only for a subset of the agent’s commands (run, cdAgent, instrumentService, instrumentIIS)
profilerLogDir	Folder to save Profiler log files in. Value from this options will be passed to the environment variable SL_LogDir. This option is available only for a subset of the agent’s commands (run, cdAgent, instrumentService, instrumentIIS)
enablePerformanceMonitoring	Set to true to enable performance monitoring of the host machine. Default value: false Write a warning to the log if resource usage exceeded threshold of 90%. Available metrics: CPU, RAM, Network Usage. Note: This option is available only for collector-related commands (cdAgent, run, startBackgroundTestListener)

Environment variables (Profiler, Collector, Background Listener...)

To enable logs, you can add the following environment variables to the registry in addition to the regular variables set for the Profiler. If the below variables are set, any agent’s command will print values in the configuration data (in the Profiler section).

Parameter	Description
SL_LOGGING_LOGPRESET	Set the log preset. Allows managing several log-related options at once and has precedence on LOG_LEVEL. The default preset is Default. See below table for the detailed available options.
SL_LOGLEVEL	Level of logs to generate : Disabled, Critical , Error , Warn , Info (Default) , Debug , Trace
SL_LOGGING_TOCONSOLE	Enables or disables logging to the console. Default value: true
SL_LOGGING_TOFILE	Enables or disables logging into a file. Default value: false
SL_LOGDIR (or SL_LOGDIRECTORY)	Set the directory for logs for both the collector and the profiler. The default value depends on the OS: ".\logs" for Windows and "/var/log/sealights" for Linux
SL_LOGGING_FILENAME	Sets the collector’s log file name relative to the SL_LOGDIR set above. Default value: cli_{command}_{time}_{pid}.log
SL_FEATURES_ENABLEPERFORMANCEMONITORING	Enable performance monitoring of the host machine — available metrics: CPU, RAM, Network Usage. Write a warning to the log if resource usage exceeds the threshold of 90%. (Default is false)
SL_PROFILER_LOGLEVEL	Set to none to disable logging from the Profilers. This restricts output exclusively to the Collector's logs, simplifying troubleshooting.

Available logging presets

Option value	Description
Default	Do nothing. Default value
Disabled	Disable logs. Set LogLevel to “Disabled”
Debug	Debug mode. Set LogLevel to “Debug” and LogAppendFile to “True”
Diagnostic	Diagnostics mode. The same as Debug, plus enabled perf metrics Set LogLevel to Debug, LogAppendFile and EnablePerformanceMonitoring to True