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

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

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

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

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

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	`CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={3B1DAA64-89D4-4999-ABF4-6A979B650B7D} CORECLR_PROFILER_PATH_32=libSL.DotNet.ProfilerLib.Linux.so CORECLR_PROFILER_PATH_64=libSL.DotNet.ProfilerLib.Linux.so SL_CollectorId=SL_Agent`

Parameter	Description

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

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

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

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

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

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

Parameter

SeaLights .NET Core agent - Command Reference