> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/command-reference.md). # Command Reference {% hint style="warning" %} **Legacy Alias Deprecation Notice** Starting with **.NET Agent 3.16.0**, SeaLights supports standardised CLI parameter naming across technologies. Legacy parameter aliases remain supported for backward compatibility, but they are planned for future deprecation. Customers are strongly encouraged to migrate to the standardised CLI parameters as part of their regular maintenance and upgrade process. More information can be found in [**Configuration Standards**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/configuration-standards.md). {% endhint %} Use this reference by workflow. For guided setup, see [**Scanning the build binaries**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/scanning-the-build-binaries.md), [**Running tests**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/running-tests.md), and [**Capturing coverage from the application**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/capturing-coverage-from-the-application.md). Use these sections in order: 1. **Common options** — reuse authentication, console, and proxy settings. 2. **Config and scan** — create a session, scan binaries, and finalize multi-module builds. 3. **Wrapper command** — use `run` for test frameworks or application processes. 4. **Runtime coverage collectors** — use the background listener or Windows Collector Service flows. 5. **Test execution and results** — open a test stage and upload test reports. 6. **Logging** — collect agent and profiler diagnostics. ## Common options These options repeat across commands. The command tables below omit them unless a command has unique behavior. | CLI Parameter | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `--token` | SeaLights agent token, used to authenticate to the server. | | `--tokenFile` | Path to a file containing the SeaLights agent token, used to authenticate to the server. | | `--quiet` | Suppresses console feedback messages only. Does not suppress log output when logging is configured to print to the console (Default: `false`). | | `--proxy` | Address of proxy to run connection through. Use `system` to use the system proxy. | | `--proxyUsername` | The proxy username if needed. | | `--proxyPassword` | The proxy password if needed. | | `--tags` | One or more tags (comma-separated) to label this instance in the cockpit. Any free text without spaces is allowed, e.g. `--tags tag1,tag2`. | | `--settings` | Set configuration file for the CLI instance. | ## Config and scan ### Create a build session (`config`) This command creates the build session used by later scan and test commands. ```bash ## Minimum required CLI parameters dotnet .//SL.DotNet.dll config \ --token \ --appName \ --branchName \ --buildName \ --includeNamespace ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--appName` | `--appname` | **Required.** Name of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--buildSessionIdFile` | `--buildsessionidfile` | File where the Build session ID to use can be found. | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards (`*` = any string, `?` = any character). For example: `'com.example.*,io.*.demo,com.?ello.world'` | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. For example: `'com.example.*,io.*.demo,com.?ello.world'` | | `--include` | `--include` | Comma-separated list of files or patterns to include (Default: `*.exe, *.dll`). Supports wildcards. For example: `'*-with-dependencies.dll,bad-bad?.exe'` | | `--exclude` | `--exclude` | Comma-separated list of files or patterns to exclude. Supports wildcards. For example: `'*-with-dependencies.dll,bad-bad?.exe'` | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. By default, all assemblies are included. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. Empty by default. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn` (use method's Fully Qualified Name — produces persistent build scans across multiple builds), `mvid` (use CLR method token — produces a unique identifier per build). | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier instead of the method's token. Allows producing persistent build scans among multiple builds. | | `--ignoreGeneratedCode` | `--ignoregeneratedcode` | Ignore scanning methods that are marked with `[GeneratedCodeAttribute]`. | | `--linesPerHit` | `--linesperhit` | Set how many lines will represent one hit when line level coverage is enabled (Default: `1`). | | `--agentPort` | `--agentport` | Port for IPC communication. SeaLights agent application will listen on this port. | ### Create a pull request session (`prConfig`) Use this command for pull request analysis. ```bash ## Minimum required CLI parameters dotnet .//SL.DotNet.dll prConfig \ --token \ --appName \ --pullRequestNumber \ --targetBranch \ --latestCommit \ --includeNamespace ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--appName` | `--appname` | **Required.** Name of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--pullRequestNumber` | `--pullrequestnumber` | **Required.** The number assigned to the Pull Request from the source control. | | `--pullRequestTitle` | `--pullrequesttitle` | **Required.** The Pull Request title. | | `--targetBranch` | `--targetbranch` | **Required.** The branch to which this PR will be merged into (already reported to SeaLights). | | `--latestCommit` | `--latestcommit` | **Required.** The full SHA of the last commit made to the Pull Request. | | `--repositoryUrl` | `--repositoryurl` | Source control repository URL, from which URLs will be built. May be auto-detected during runtime if available. | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards (`*` = any string, `?` = any character). | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--include` | `--include` | Comma-separated list of files or patterns to include (Default: `*.exe, *.dll`). | | `--exclude` | `--exclude` | Comma-separated list of files or patterns to exclude. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. By default, all assemblies are included. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. Empty by default. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn` (use method's Fully Qualified Name), `mvid` (use CLR method token). | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier instead of the method's token. Allows producing persistent build scans among multiple builds. | | `--ignoreGeneratedCode` | `--ignoregeneratedcode` | Ignore scanning methods that are marked with `[GeneratedCodeAttribute]`. | | `--buildSessionIdFile` | `--buildsessionidfile` | File where the Build session ID to use can be found. | | `--linesPerHit` | `--linesperhit` | Set how many lines will represent one hit when line level coverage is enabled (Default: `1`). | | `--agentPort` | `--agentport` | Port for IPC communication. SeaLights agent application will listen on this port. | ### Scan binaries (`scan`) {% hint style="warning" %} The project must contain all the PDB files! {% endhint %} This command uploads the scanned build map for the current session. ```bash ## Minimum required CLI parameters dotnet .//SL.DotNet.dll scan \ --token \ --buildSessionId \ --scanDir \ --includeNamespace ``` **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--scanDir` | `--workspacepath` | **Required.** Path to the scanned folder where all binary files are located. | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards. | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--include` | `--include` | Comma-separated list of files or patterns to include (Default: `*.exe, *.dll`). | | `--exclude` | `--exclude` | Comma-separated list of files or patterns to exclude. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. By default, all assemblies are included. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. Empty by default. | | `--uniqueModuleId` | `--uniquemoduleid` | Unique Module ID. Required in the case of a multi-modular build. | | `--moduleName` | `--modulename` | Sets the module name. | | `--srcRootDir` | `--srcrootdir` | Source root directory, where all paths will be made relative to. | | `--scm` | `--scm` | Source control type. Available values: `auto`, `git`, `tfvc`, `none` (Default: `auto`). | | `--scmProvider` | `--scmprovider` | Source control provider (e.g. `Github`, `Bitbucket`, `Gitlab`). | | `--scmVersion` | `--scmversion` | Source control provider version (e.g. BitBucket version). | | `--repositoryUrl` | `--repositoryurl` | Source control repository URL. If not provided, the URL of the remote Git origin will be used. | | `--commitDataFile` | `--commitdatafile` | A path to a file containing commit data. Used from the VSTS extension to report TFVC commits to the server. | | `--extraScanDirs` | `--extrascandirs` | Adds additional directories to scan. Same filters will be applied. | | `--extraDbgSearchDirs` | `--extradbgsearchdirs` | Adds additional locations where the agent will search for debug symbols (`*.pdb` files). | | `--ignoreGeneratedCode` | `--ignoregeneratedcode` | Ignore scanning methods that are marked with `[GeneratedCodeAttribute]`. | | `--ignoreDisplayClass` | `--ignoredisplayclass` | Filter out DisplayClass index from method hashing. This can eliminate unexpected modified coverage from added closures. | | `--enableBatching` | `--enablebatching` | Enables batching of scan results before sending to the server. | | `--dumpTo` | `--dumpto` | Duplicate buildmap to the specified file. | ### Finalize a multi-module build (`reportBuildStatus`) Use this command after all module scans are complete. ```bash ## Minimum required CLI parameters dotnet .//SL.DotNet.dll reportBuildStatus \ --token \ --buildSessionId \ --success true ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ---------------------- | ---------------------- | ------------------------------------------------------------------------ | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--success` | `--success` | Indicates that the build succeeded (considered failed if not specified). | | `--message` | `--message` | Additional build status message to report (optional). | | `--durationMs` | `--durationms` | Build duration in milliseconds (optional). | ## Wrapper command for tests and application processes Use `run` when you can control the process startup command. Use it in two ways: * Wrap a supported test framework such as MSTest, NUnit, xUnit, or `dotnet test`. * Wrap an application or service process to capture runtime coverage. See [**Running tests**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/running-tests.md) and [**Configuring the Profiler-Initiated Collector**](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/capturing-coverage-from-the-application/configuring-the-profiler-initiated-collector.md) for end-to-end setup. ### Run a process through the agent (`run`) 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). Use the sample that matches your workflow. {% tabs %} {% tab title="Application runtime" %} ```bash ## Runtime coverage for an application under test dotnet .//SL.DotNet.dll run \ --token \ --buildSessionId \ --labId \ --instrumentationMode coverage \ --target ``` {% endtab %} {% tab title="In-process tests" %} ```bash ## Wrapper for in-process test execution, such as unit tests dotnet .//SL.DotNet.dll run \ --token \ --buildSessionId \ --includeNamespace \ --instrumentationMode testsAndCoverage \ --testStage "Unit Tests" \ --target dotnet \ --targetArgs "test " ``` {% endtab %} {% tab title="Testing framework" %} {% hint style="warning" %} The `buildSessionId` and `buildSessionIdFile` parameters are **deprecated** for external test-runner commands. Use `labId` instead. These parameters remain supported for in-process testing (Unit Tests, Integration Tests, Component Tests). {% endhint %} ```bash ## Wrapper for a testing framework runner, such as functional tests dotnet .//SL.DotNet.dll run \ --token \ --labId \ --instrumentationMode tests \ --testStage \ --target \ --targetArgs "" ``` {% endtab %} {% endtabs %} #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--appName` | `--appname` | **Required.** Name of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--target` | `--target` | The name (or path) of the target application to run with the test listener. | | `--targetArgs` | `--targetargs` | Command line arguments to pass to the target application. | | `--workingDir` | `--workingdir` | Path to the working directory. The current working directory is used if not specified. | | `--includeProcessFilter` | `--includeprocessfilter` | A list of process names to include for profiling. If empty, all processes are included. | | `--excludeProcessFilter` | `--excludeprocessfilter` | A list of process names to exclude from profiling. If empty, no processes are excluded. | | `--includeChildProcesses` | `--includechildprocesses` | Enable instrumentation for child processes (Default: `true`). | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards. | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. By default, all assemblies are included. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. Empty by default. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn` (use method's Fully Qualified Name), `mvid` (use CLR method token). | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier instead of the method's token. | | `--testStage` | `--teststage` | Sets the test stage (e.g. `'Integration-Test'`). | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | | `--instrumentationMode` | `--instrumentationmode` | Set instrumentation mode. Possible values: `tests`, `coverage`, `testsAndCoverage` (Default: `testsAndCoverage`). | | `--testListenerSessionKey` | `--testlistenersessionkey` | A session key that uniquely identifies the running test listener background instance. | | `--agentPort` | `--agentport` | Port for IPC communication. SeaLights agent application will listen on this port. | | `--idleTimeoutSec` | `--idletimeoutsec` | Number of seconds of inactivity after last active profiler disconnected before shutting down. Use `-1` to disable. | | `--startupInactivityTimeoutSec` | `--startupinactivitytimeoutsec` | Number of seconds of inactivity after startup before shutting down. Use `-1` to disable. | | `--footprintsEnableV6` | `--footprintsenablev6` | Use Footprints V6 protocol. | | `--tiaDisabled` | `--tiadisabled` | Set to `true` to disable getting TIA Recommendations from the SeaLights backend (Default: `false`). | | `--useMsProfiler` | `--usemsprofiler` | Use the MS Instrumentation profiler as uber profiler. | | `--comRegistration` | `--comregistration` | Register profiler as COM object in the Windows Registry. Required for .NET < 4.0. | | `--sessionsFile` | `--sessionsfile` | Allow specifying an external file for multiple apps configurations. | ## Runtime coverage collectors Use these commands when you need runtime coverage but cannot wrap the target process directly. ### Start the background listener (`startBackgroundTestListener`) {% hint style="info" %} Before using the background test listener, ensure the following environment variables are set on the target process. {% endhint %} {% tabs %} {% tab title="Windows" %} ```ps1 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= ``` {% endtab %} {% tab title="Linux" %} ```bash 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= ``` {% endtab %} {% endtabs %} This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters dotnet .//SL.DotNet.dll startBackgroundTestListener \ --token \ --appName \ --branchName \ --buildName \ --labId \ --includeNamespace \ --testListenerSessionKey ``` **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--appName` | `--appname` | **Required.** Name of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--testListenerSessionKey` | `--testlistenersessionkey` | A random alphanumeric ID (`%RANDOM%` in command line) that uniquely identifies the running background listener instance. This ID must be passed to any process you want to capture coverage from via `SL_CollectorId`. | | `--target` | `--target` | The name (or path) of the target application. | | `--targetArgs` | `--targetargs` | Arguments to be passed to the target process. | | `--workingDir` | `--workingdir` | The path to the working directory. If not specified, the current working directory will be used. | | `--includeProcessFilter` | `--includeprocessfilter` | A list of process names to include for profiling. If empty, all processes are included. | | `--excludeProcessFilter` | `--excludeprocessfilter` | A list of process names to exclude from profiling. If empty, no processes are excluded. | | `--includeChildProcesses` | `--includechildprocesses` | Enable instrumentation for child processes (Default: `true`). | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards. | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. By default, all assemblies are included. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. Empty by default. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn` (use method's Fully Qualified Name), `mvid` (use CLR method token). | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier instead of the method's token. | | `--testStage` | `--teststage` | Sets the test stage (e.g. `'Integration-Test'`). | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | | `--instrumentationMode` | `--instrumentationmode` | Set instrumentation mode. Possible values: `tests`, `coverage`, `testsAndCoverage` (Default: `testsAndCoverage`). | | `--agentPort` | `--agentport` | Port for IPC communication. SeaLights agent application will listen on this port. | | `--idleTimeoutSec` | `--idletimeoutsec` | Number of seconds of inactivity after last active profiler disconnected before shutting down. Use `-1` to disable. | | `--startupInactivityTimeoutSec` | `--startupinactivitytimeoutsec` | Number of seconds of inactivity after startup before shutting down. Use `-1` to disable. | | `--footprintsEnableV6` | `--footprintsenablev6` | Use Footprints V6 protocol. | | `--tiaDisabled` | `--tiadisabled` | Set to `true` to disable getting TIA Recommendations from the SeaLights backend (Default: `false`). | | `--useMsProfiler` | `--usemsprofiler` | Use the MS Instrumentation profiler as uber profiler. | | `--comRegistration` | `--comregistration` | Register profiler as COM object in the Windows Registry. Required for .NET < 4.0. | | `--sessionsFile` | `--sessionsfile` | Allow specifying an external file for multiple apps configurations. | ### Stop the background listener (`stopBackgroundTestListener`) This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters dotnet .//SL.DotNet.dll stopBackgroundTestListener \ --token \ --labId \ --testListenerSessionKey ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | -------------------------- | -------------------------- | -------------------------------------------------------------------- | | `--testListenerSessionKey` | `--testlistenersessionkey` | The session key provided when starting the background test listener. | | `--agentPort` | `--agentport` | Port for IPC communication (Default: `31031`). | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | ## MS Windows-specific commands Use these commands for IIS, Windows Services, and the Windows Coverage Collector Service. ### Install or uninstall the Coverage Collector Service (`SL.DotNet.CoverageCollectorService.exe`) {% hint style="info" %} This command is commonly used when upgrading your agent version, as it is required to uninstall the Coverage Collector Service from the machine before installing a new version. {% endhint %} ```bash SL.DotNet.CoverageCollectorService.exe {install {start} | uninstall} ``` **All CLI Parameters**
CLI ParameterDescription
installInstall the Coverage Collector Service.
startStart the service. Used together with install.
uninstallUninstall the Coverage Collector Service. This command must be executed alone.
### Instrument a Windows Service (`instrumentService`) This command adds the `Environment REG_MULTI_SZ` record to the target service in the Windows registry with the environment variables required to start the SeaLights profiler. {% hint style="info" %} Related Windows Registry path: `Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\` {% endhint %} This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters SL.DotNet.exe instrumentService \ --serviceName \ --appName \ --branchName \ --buildName \ --labId \ --scanDir \ --includeNamespace ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--serviceName` | `--servicename` | **Required.** Target service name. | | `--appName` | `--appname` | **Required.** Name of the application. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--force` | `--force` | Forces overwriting existing registry entries (Default: `false`). | | `--scanDir` | `--scandir` | Path to the scanned folder where all binary files are located. | | `--undo` | `--undo` | Unregisters the SeaLights profiler and removes the Environment Variables from the Registry. | | `--startCollector` | `--startcollector` | Start the collector as an external process (PIC) alongside the target process. Possible values: `run`, `cdAgent`. | | `--profilerStartup` | `--profilerstartup` | Controls profiler startup blocking behavior. Values: `Blocking` (default — blocks until collector connects), `Async` (target app starts during connection). | | `--targetRuntime` | `--targetruntime` | Specify the target CLR runtime to profile. Possible values: `auto`, `fw` (.NET Framework only), `core` (.NET Core / .NET 5+ only). (Default: `auto`). | | `--useMsProfiler` | `--usemsprofiler` | Use the MS Instrumentation profiler as uber profiler. | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards. | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--include` | `--include` | Comma-separated list of files or patterns to include. | | `--exclude` | `--exclude` | Comma-separated list of files or patterns to exclude. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn`, `mvid`. | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier. | | `--ignoreGeneratedCode` | `--ignoregeneratedcode` | Ignore scanning methods that are marked with `[GeneratedCodeAttribute]`. | | `--ignoreDisplayClass` | `--ignoredisplayclass` | Filter out DisplayClass index from method hashing. | | `--repositoryUrl` | `--repositoryurl` | Source control repository URL. | | `--includeProcessFilter` | `--includeprocessfilter` | A list of process names to include for profiling. | | `--excludeProcessFilter` | `--excludeprocessfilter` | A list of process names to exclude from profiling. | | `--testStage` | `--teststage` | Sets the test stage. | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | | `--instrumentationMode` | `--instrumentationmode` | Set instrumentation mode. Possible values: `tests`, `coverage`, `testsAndCoverage` (Default: `testsAndCoverage`). | | `--testListenerSessionKey` | `--testlistenersessionkey` | A session key that uniquely identifies the running test listener background instance. | | `--agentPort` | `--agentport` | Port for IPC communication. | | `--idleTimeoutSec` | `--idletimeoutsec` | Seconds of inactivity after last active profiler disconnected before shutting down. Use `-1` to disable. | | `--startupInactivityTimeoutSec` | `--startupinactivitytimeoutsec` | Seconds of inactivity after startup before shutting down. Use `-1` to disable. | | `--footprintsEnableV6` | `--footprintsenablev6` | Use Footprints V6 protocol. | | `--tiaDisabled` | `--tiadisabled` | Set to `true` to disable TIA Recommendations (Default: `false`). | | `--sessionsFile` | `--sessionsfile` | Allow specifying an external file for multiple apps configurations. | ### Instrument IIS (`instrumentIIS`) This command registers the SeaLights profiler with two specific IIS services: `WAS` and `W3SVC`. It is equivalent to running `instrumentService` twice — once for each of these services. {% hint style="info" %} Related Windows Registry path: `Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services` {% endhint %} ```bash ##Minimum required CLI parameters SL.DotNet.exe instrumentIIS \ --appName \ --branchName \ --buildName \ --labId \ --scanDir \ --includeNamespace ``` **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `--appName` | `--appname` | **Required.** Name of the application. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--buildName` | `--buildname` | **Required.** The build label of the current build. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--scanDir` | `--scandir` | Path to the scanned folder where all binary files are located. | | `--force` | `--force` | Forces overwriting existing registry entries (Default: `false`). | | `--undo` | `--undo` | Unregisters the SeaLights profiler and removes the Environment Variables from the Registry. | | `--startCollector` | `--startcollector` | Start the collector as an external process (PIC) alongside the target process. Possible values: `run`, `cdAgent`. | | `--profilerStartup` | `--profilerstartup` | Controls profiler startup blocking behavior. Values: `Blocking`, `Async` (Default: `Blocking`). | | `--targetRuntime` | `--targetruntime` | Specify the target CLR runtime to profile. Possible values: `auto`, `fw`, `core` (Default: `auto`). | | `--useMsProfiler` | `--usemsprofiler` | Use the MS Instrumentation profiler as uber profiler. | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--includeNamespace` | `--includenamespace` | **Required.** Comma-separated list of namespace or namespace patterns to include. Supports wildcards. | | `--excludeNamespace` | `--excludenamespace` | Comma-separated list of namespace or namespace patterns to exclude. Supports wildcards. | | `--include` | `--include` | Comma-separated list of files or patterns to include. | | `--exclude` | `--exclude` | Comma-separated list of files or patterns to exclude. | | `--includeAssemblies` | `--includeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to include. | | `--excludeAssemblies` | `--excludeassemblies` | **Advanced.** Comma-separated list of assemblies or patterns to exclude. | | `--identifyMethodsBy` | `--identifymethodsby` | Set method identifier type. Possible values: `fqn`, `mvid`. | | `--identifyMethodsByFqn` | `--identifymethodsbyfqn` | Use Method's Fully Qualified Name as unique method identifier. | | `--ignoreGeneratedCode` | `--ignoregeneratedcode` | Ignore scanning methods that are marked with `[GeneratedCodeAttribute]`. | | `--ignoreDisplayClass` | `--ignoredisplayclass` | Filter out DisplayClass index from method hashing. | | `--repositoryUrl` | `--repositoryurl` | Source control repository URL. | | `--includeProcessFilter` | `--includeprocessfilter` | A list of process names to include for profiling. | | `--excludeProcessFilter` | `--excludeprocessfilter` | A list of process names to exclude from profiling. | | `--testStage` | `--teststage` | Sets the test stage. | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | | `--instrumentationMode` | `--instrumentationmode` | Set instrumentation mode. Possible values: `tests`, `coverage`, `testsAndCoverage` (Default: `testsAndCoverage`). | | `--testListenerSessionKey` | `--testlistenersessionkey` | A session key that uniquely identifies the running test listener background instance. | | `--agentPort` | `--agentport` | Port for IPC communication. | | `--idleTimeoutSec` | `--idletimeoutsec` | Seconds of inactivity after last active profiler disconnected before shutting down. Use `-1` to disable. | | `--startupInactivityTimeoutSec` | `--startupinactivitytimeoutsec` | Seconds of inactivity after startup before shutting down. Use `-1` to disable. | | `--footprintsEnableV6` | `--footprintsenablev6` | Use Footprints V6 protocol. | | `--tiaDisabled` | `--tiadisabled` | Set to `true` to disable TIA Recommendations (Default: `false`). | | `--sessionsFile` | `--sessionsfile` | Allow specifying an external file for multiple apps configurations. | ### Start a Collector Service session (`startCollectorServiceSession`) This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters SL.DotNet.exe startCollectorServiceSession \ --token \ --buildSessionId \ --labId \ --processName \ --applicationPool \ --includeChildProcesses true ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--labId` | `--labid` | Unique ID for a set of test labs in case multiple labs are running simultaneously. | | `--processName` | `--processname` | Name of the executable to collect coverage from. Use `*` to match all processes with SeaLights environment variables in their Registry entry. For IIS use `w3wp.exe`. For .NET Core use `dotnet`. | | `--applicationPool` | `--applicationpool` | For IIS: the Application Pool name corresponding to the hosted application. Use `*` to capture all Application Pools at once. | | `--includeChildProcesses` | `--includechildprocesses` | Enable instrumentation for child processes (Default: `true`). | | `--testListenerSessionKey` | `--testlistenersessionkey` | A session key that uniquely identifies the running test listener background instance. | | `--testStage` | `--teststage` | Sets the test stage. | | `--sessionResponseTimeoutSec` | `--sessionresponsetimeoutsec` | Time to wait for response for `startCollectorServiceSession` and `stopCollectorServiceSession` commands. | | `--save` | `--save` | Store coverage collector session changes to file (predefined sessions). | | `--footprintsEnableV6` | `--footprintsenablev6` | Use Footprints V6 protocol. | | `--machine` | `--machine` | Optional: IIS host to start the session remotely on. | ### Stop a Collector Service session (`stopCollectorServiceSession`) This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters SL.DotNet.exe stopCollectorServiceSession \ --labId \ --processName ``` **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--stopAllSessions` | `--stopallsessions` | Close all sessions at once. | | `--processName` | `--processname` | Name of the process to stop coverage collection for. Use `*` to match all processes with SeaLights environment variables in their Registry entry. For IIS use `w3wp.exe`. | | `--applicationPool` | `--applicationpool` | For IIS: the Application Pool to stop. Use `*` to stop capture for all Application Pools at once. | | `--sessionResponseTimeoutSec` | `--sessionresponsetimeoutsec` | Time to wait for response for `startCollectorServiceSession` and `stopCollectorServiceSession` commands. | | `--save` | `--save` | Store coverage collector session changes to file (predefined sessions). | | `--machine` | `--machine` | Optional: IIS host to stop the session remotely on. | ## Capture test execution and results Use these commands when you need to report a test stage explicitly or upload result files from the test framework. ### Open a test stage (`startExecution`) This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters dotnet .//SL.DotNet.dll startExecution \ --token \ --appName \ --branchName \ --labId ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ---------------------- | ---------------------- | ---------------------------------------------------------------- | | `--appName` | `--appname` | **Required.** Name of the application. | | `--branchName` | `--branchname` | **Required.** The source branch of the application. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--testStage` | `--teststage` | Name of the test stage (e.g. `'Integration-Test'`). | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | ### Upload test report files (`uploadTestReport`) {% hint style="warning" %} Supported report formats are MSTest (TRX files), xUnit.Net, NUnit, and JUnit (XML files). {% endhint %} This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters dotnet .//SL.DotNet.dll uploadTestReport \ --token \ --buildSessionId \ --labId \ --testStage \ --report ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--testStage` | `--teststage` | Name of the test stage. | | `--report` | `--file` | Path to the test framework report file or folder containing report files (non-recursive). Supported formats: MSTest (TRX), xUnit.Net, NUnit, JUnit (XML). | | `--useExistingExecution` | `--useexistingexecution` | Instructs the agent not to send start/end execution events on report upload (Default: `false`). | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | ### Close a test stage (`endExecution`) This example is with minimum required CLI Parameters. All available CLI Parameters can be found in the table below. ```bash ##Minimum required CLI parameters dotnet .//SL.DotNet.dll endExecution \ --token \ --buildSessionId \ --labId \ --testStage ``` #### **All CLI Parameters** | CLI Parameter | Legacy Alias | Description | | ---------------------- | ---------------------- | ---------------------------------------------------------------- | | `--buildSessionId` | `--buildsessionid` | Session ID of configuration created. | | `--buildSessionIdFile` | `--buildsessionidfile` | Path to file containing the Session ID of configuration created. | | `--labId` | `--labid` | **Required.** Sets the lab ID. | | `--testStage` | `--teststage` | Name of the test stage. | | `--testProjectId` | `--testprojectid` | Set Test Project ID for running tests group. | | `--prId` | `--prid` | Set Pull Request ID to group tests by PR. | ## Logging Logging is configured via CLI parameters or environment variables. By default, the agent logs at `Info` level only. ### Available logging presets | Preset Value | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Default` | No change to log level. Default value. | | `Disabled` | Disable all logs. Sets `LogLevel` to `Disabled`. | | `Debug` | Debug mode. Sets `LogLevel` to `Debug` and `LogAppendFile` to `true`. | | `Diagnostic` | Diagnostics mode. Same as Debug, plus enables performance monitoring. Sets `LogLevel` to `Debug`, `LogAppendFile` and `EnablePerformanceMonitoring` to `true`. | ### Agent commands To enable logging when executing direct agent commands, append the following parameters to any command. Both console output and file options are compatible and non-exclusive. {% tabs %} {% tab title="Console and file" %} ```ps1 --logPreset Debug --logDir "C:\Sealights\Logs\" ``` {% endtab %} {% tab title="Console only" %} ```ps1 --logPreset Debug --logAppendFile false ``` {% endtab %} {% tab title="Diagnostic (Console and file)" %} {% code overflow="wrap" %} ```ps1 --logPreset Diagnostic --logDir "C:\Sealights\Logs\" ``` {% endcode %} {% endtab %} {% endtabs %} | CLI Parameter | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--logPreset` | Set the log preset. Has precedence over `--logLevel`. Default is `Default`. See available options below. | | `--logLevel` | Sets log level. Available values: `Disabled`, `Critical`, `Error`, `Warn`, `Info`, `Debug`, `Trace` (Default: `Info`). | | `--logAppendConsole` | Enables or disables logging to the console (Default: `true`). | | `--logAppendFile` | Enables or disables logging to a file (Default: `false`). | | `--logFilename` | Sets the collector's log file name (Default: `cli_{command}_{time}_{pid}.log`). | | `--logDir` | Set directory for logs for both the collector and profiler (Default: `..\logs` (Windows) or `/var/log/sealights` (Linux)). | | `--profilerLogLevel` | Log level for the Profiler entity as an integer. Default: `0` (none). Values: Fatal=1, Error=4, Debug=6, All=999. Available only for `run`, `cdAgent`, `instrumentService`, `instrumentIIS`. | | `--profilerLogDir` | Folder to save Profiler log files in. Available only for `run`, `cdAgent`, `instrumentService`, `instrumentIIS`. | | `--enablePerformanceMonitoring` | Enable performance monitoring of the host machine (CPU, RAM, Network). Writes a warning if resource usage exceeds 90%. Available only for `cdAgent`, `run`, `startBackgroundTestListener` (Default: `false`). | ### Environment variables To enable logging via environment variables (e.g. for the Profiler, Background Listener, or IIS), set the following in the process environment or Windows registry in addition to the regular Profiler variables. {% hint style="info" %} The `SL_LOGGING_*` variables apply to the **Collector**. The `SL_LogLevel` and `SL_LogDir` variables apply to the **Profiler**. Both sets can be used together for full diagnostic coverage. {% endhint %} | Environment Variable | Description | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `SL_LOGGING_LOGPRESET` | Set the log preset. Has precedence over `SL_LOGLEVEL`. See available presets below (Default: `Default`). | | `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: `true`). | | `SL_LOGGING_TOFILE` | Enables or disables logging to a file (Default: `false`). | | `SL_LOGDIR` (or `SL_LOGDIRECTORY`) | Set the directory for logs for **both the collector and the profiler** (Default: `.\logs` (Windows) or `/var/log/sealights` (Linux)). | | `SL_LOGGING_FILENAME` | Sets the collector's log file name relative to `SL_LOGDIR` (Default: `cli_{command}_{time}_{pid}.log`). | | `SL_FEATURES_ENABLEPERFORMANCEMONITORING` | Enable performance monitoring of the host machine — CPU, RAM, Network Usage. Writes a warning if resource usage exceeds 90%(Default: `false`). | | `SL_PROFILER_LOGLEVEL` | Set to `none` to disable logging from the Profiler. Restricts output exclusively to the Collector's logs, simplifying troubleshooting. | | `SL_LogLevel` | Profiler-level log integer. Default: `0` (none). Values: Fatal=1, Error=4, Debug=6, All=999. | | `SL_LogDir` | Folder to save Profiler log files in. | ### Logging examples {% tabs %} {% tab title="PowerShell" %} ```powershell $env:SL_LOGLEVEL = "Debug" # DEBUG | INFO | WARN | ERROR (default: Info) $env:SL_LOGGING_TOFILE = "true" # Optional: persist logs to file $env:SL_LOGDIR = "C:\Sealights\Logs" # Optional: set log directory ``` {% endtab %} {% tab title="Azure DevOps" %} ```yaml - script: dotnet .//SL.DotNet.dll run ... displayName: Run tests with SeaLights logging enabled env: SL_LOGLEVEL: Debug # DEBUG | INFO | WARN | ERROR (default: Info) SL_LOGGING_TOFILE: "true" # Optional: persist logs to file SL_LOGDIR: "$(Agent.TempDirectory)\sealights-logs" # Optional: set log directory ``` {% endtab %} {% tab title="Bash" %} ```bash export SL_LOGLEVEL=Debug # DEBUG | INFO | WARN | ERROR (default: Info) export SL_LOGGING_TOFILE=true # Optional: persist logs to file export SL_LOGDIR=/var/log/sealights # Optional: set log directory ``` {% endtab %} {% tab title="GitHub Actions" %} ```yaml - name: Run tests with SeaLights logging enabled env: SL_LOGLEVEL: Debug # DEBUG | INFO | WARN | ERROR (default: Info) SL_LOGGING_TOFILE: "true" # Optional: persist logs to file SL_LOGDIR: "/var/log/sealights" # Optional: set log directory run: | dotnet .//SL.DotNet.dll run ... ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/command-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.