Onboarding the .Net CD Agent

These steps outline the onboarding steps needed on the environment, with the CD agent, added to each component that builds up the Application Under Test.

Configuration steps

Download an Agent Token from the dashboard and make it available to each component configured with our agent.
- This can be done by placing it in a file accessible to the agent or through an environment variable directly or through a secret manager.
Download the CD agent and make it available to each component by copying it in, downloading it during startup, or mounting an external volume containing the agent. Please refer to the dedicated section below for details.
Create an “Integration Build Lab ID” entry of type “CD only” in the dashboard for the tested application (see picture on the right).
- Do so in the settings of the SeaLights dashboard, under 'Cockpit & Onboarding → Integration Build Labs → CD Only'
- The lab ID from this integration build entry needs to be provided to the CD agent through an environment variable.
Add the CD agent to your environment to attach it as a Profiler to your Application Under Test.
Set the relevant parameters and/or environment variables to be used (See samples below)

When the application is up and running and the Sealights CD Agent configured, you can see it is properly running from the Cockpit -> Live Agents Monitor screen.

Agent’s Parameters Reference

Mandatory parameters

Property (CLI)	Required	Description	Env variable	JSON
`--appName`	Yes	Name of the target application	`SL_GENERAL_APPNAME`	"general": { "appName": "" }
`--branchName`	Yes	The source branch of the application	`SL_GENERAL_BRANCHNAME`	"general": { "branchName": "" }
`--buildName`	Yes	The build label/version of the current artefact	`SL_GENERAL_BUILDNAME`	"general": { "buildName": "" }
`--labId`	Yes	CD-only lab id	`SL_LABID`, `SL_SESSION_LABID`	"general": { "labId": "" }
`--binDir`	Yes	Path to the scanned folder where all binary files are located	`SL_SCAN_BINDIR`	"general": { "binDir": "" }
`--includeNamespace`	Yes	Comma-separated list of namespaces to include in the scan. Supports wildcard (`*` = any string, `?` = any character) characters.	`SL_SCAN_INCLUDENAMESPACES`	"general": { "includeNamespaces": "" }

Optional parameters

These parameters may be required due to your specific configuration or environment’s limitations (e.g., proxy).

Property	Description
`--excludeNamespace`	Comma-separated list of namespaces to exclude from the scan. Supports wildcard (`` = any string, `?` = any character) characters. Default value: `System., Microsoft.*`	`SL_SCAN_EXCLUDENAMESPACES`
`--include`	Comma-separated list of files to include in scan. Supports wildcard (`` = any string, `?` = any character) characters. Default value: `.dll,*.exe`	`SL_SCAN_INCLUDEFILES`
`--exclude`	Comma-separated list of files to exclude from the scan. Supports wildcard (`*` = any string, `?` = any character) characters. Default value: `System.", "Microsoft.`	`SL_SCAN_EXCLUDEFILES`
`--includedAssemblies`	Comma-separated list of assemblies to include. Supports wildcard (`*` = any string, `?` = any character) characters.	`SL_SCAN_INCLUDEASSEMBLIES`
`--excludedAssemblies`	Comma-separated list of assemblies to exclude from the scan. Supports wildcard (`*` = any string, `?` = any character) characters. Default value: `mscorlib, System., Microsoft.`	`SL_SCAN_EXCLUDEASSEMBLIES`
`--srcRootDir`	Source root directory, where all paths will be made relative to	`SL_SCAN_SRCROOTDIR`	"scan": { "srcRootDir": "" }
`--target`	The name of the target application that will be started	`SL_PROFILER_TARGET`
`--targetArgs`	Arguments to be passed to the target process	`SL_PROFILER_TARGETARGS`
`--workingDir`	The path to the working directory	`SL_PROFILER_WORKINGDIR`

Logging parameters

To enable logs, you can set the following parameters

Parameter (CLI)

Description

Env variable

JSON

--profilerLogLevel

Log level. Default and Recommended value is 6

0=None
3=Errors
4=Warnings
6=Info (Light Debug)
7=Debug(Full)

SL_PROFILER_LOGLEVEL

"profiler": {
  "logLevel": 6
}

--profilerLogDir

Enables logging profiler data to file. Requires LogLevel to be specified.

SL_PROFILER_LOGDIRECTORY

"profiler": {
  "logDirectory": ""
}

Sample Commands

Downloading the agent

The different available options to download the agent are documented in a dedicated central page: https://sealights.atlassian.net/l/cp/g0omvaoL

For example, you can use the following commands to automate the process

Linux

wget -nv -O sealights-dotnet-agent-linux.tar.gz https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-linux-self-contained.tar.gz
mkdir sl-dotnet-agent && tar -xzf ./sealights-dotnet-agent-linux.tar.gz --directory ./sl-dotnet-agent
echo "[Sealights] .NetCore Agent version is: `cat ./sl-dotnet-agent/version.txt`"

Windows

iwr -OutFile sealights-dotnet-agent.zip -UseBasicParsing -Uri https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-windows-self-contained.zip
Expand-Archive .\sealights-dotnet-agent.zip -DestinationPath sl-dotnet-agent -Force
Write-Output "[Sealights] .NetCore Agent version is: $(Get-Content .\sl-dotnet-agent\version.txt)"

Configuration commands

Simple Web App (Desktop, Windows)

This simple use case illustrates how to collect coverage with the CD agent from a web application started without parameters.

.\net6.0\SL.DotNet.exe cdAgent --appName "TestApp" --branchName "main" --buildName "$(Get-Date -Format "yyyy-MM-dd-HH-mm-ss")" --labId "integ_main_integration_TestApp_Integration" \
    --binDir "WeatherApi\bin\Debug\net6.0" --includeNamespace "WeatherApi*" \
    --target "WeatherApi\bin\Debug\net6.0\WeatherApi.exe" --workingDir "WeatherApi\bin\Debug\net6.0"  \
    --identifyMethodsByFqn

Microservice (Alpine-based docker file)

DockerFile

FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine

WORKDIR /app
COPY --from=build /app/out .
COPY Scripts/start-app.sh .

# Sealights - install prereq, agent, token, bsid
# Best practice it to mount a pre-existing sealights directory depending on the environment (test or prod)
RUN mkdir -p /sealights/{agent,logs}
RUN wget -nv -O sealights-dotnet-agent-alpine.tar.gz https://agents.sealights.co/dotnetcore/latest/sealights-dotnet-agent-alpine-self-contained.tar.gz
RUN tar -xzf ./sealights-dotnet-agent-alpine.tar.gz --directory /sealights/agent
COPY ["SeaLights/sltoken.txt", "/sealights/"]
RUN chmod -R 777 /sealights

# Set the script as the entrypoint
ENTRYPOINT ["sh", "start-app.sh", "YourAppName.dll"]

startup script

#!/bin/sh
# Check if sealights folder exists
if [ -d "/app/sealights/" ]; then
    /app/sealights/agent/SL.DotNet cdAgent --appName ms-gateway-api --branchName poc --buildName $(cat /app/version.txt) \
                  --binDir /app --includeNamespace MyCompany.* --target dotnet --targetArgs $1 --workingDir /app \
                  --identifyMethodsByFqn --profilerLogLevel 6 --profilerLogDir /app/sealights/logs --labId integ_POC_DemoApp
else
    dotnet $1
fi

SeaLights CD Agent for .Net Application