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>]]
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>]]
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>]]
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>]]
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)
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>]
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:
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
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>]]
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>]]
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 meteredFor .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 meteredFor .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>]]
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
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>]]
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
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, add
--logEnabled true --logAppendConsole true --enablePerformanceMonitoring true
For logging into a file, add
--logEnabled true --logAppendFile true --enablePerformanceMonitoring true
Parameter
Description
logEnabled
Set to true to enable logs
logAppendConsole
Set to true to enable log output to the console
logAppendFile
Set to true to enable log output to a file
logFilename
Provide the name of the log file
logFileCount
Limit the number of log files to create. Default: 10
logSizeLimit
Limit the size of the log file. Default: 10*1024 KB
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
)
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 as explained in the section Running background processes above. If the below variables are set, any agent’s command will print values in the configuration data (in the Profiler section).
Parameter
Description
SL_LogLevel
Level of logs to generate as a Integer value: None=0
(Default), Fatal=1
, Error=4
, Debug=6
(Recommended) , All=999
SL_LogDir
Folder to save log files in.
Last updated
Was this helpful?