C# Script

The C# Script runner allows executing a C# script on Windows, Linux, or macOS. It uses a custom TeamCity tool for running a C# Interactive shell across platforms.

With this runner, you can perform various service tasks, such as preparing a build environment, creating an OS user, or reporting to different messengers.

Refer to Configuring Build Steps for a description of common build steps' settings. Refer to Container Wrapper to learn how you can run this step inside a container.

Prerequisites

The runner's requirements:

.NET runtime 6.0.0 or later must be installed on a build agent, or available in a Docker container if this step is run inside Docker.

C# Script Settings

Setting	Description
TeamCity C# script tool	Select a version of the TeamCity C# Script tool from those installed via Administration \| Tools, or enter a custom path to this tool, relative to the build checkout directory.
Script type	Choose one of the two options: enter a custom script body right inside the runner or specify a path to a C# script file (`.csx`). If the submitted script references another script, make sure the path to the referenced script is specified relatively to the build checkout directory.
C# script	Available for the Custom Script type. Enter a code of a C# script.
C# script file	Available for the Script File type. Enter a path to the script file, relative to the build checkout directory.
Script parameters	Enter parameters of the script. Parameters are passed as the `Args` array. View supported arguments. Parameter references are supported. Passing secure values For security reasons, we highly recommend that you avoid using parameter references directly inside scripts if these parameters represent secure values. You can pass such values via script parameters instead. For example, to pass a token value, add a new build parameter with the "Password" type, refer it in the runner’s Script parameters field: `%access_token%` and call it as an argument within the script: `val accessToken = args[0]` This way, you can reuse the token’s value anywhere in the script. This practice will ensure that these values are available on the agent only during the build. Otherwise, if the parameters are specified directly inside the script, their resolved values will be stored on the agent machine as long as the script itself is stored, which might compromise the security of your data.
NuGet package sources	If you refer to a package from a script, TeamCity will automatically download it from the feed specified in this field. The runner can automatically parse commands like `#r "nuget:System.Text.Json"` and `#r "nuget:System.Text.Json,4.7.2"`. By default, TeamCity restores NuGet packages from their sources published on NuGet.org. In this field, you can specify paths to other NuGet repositories, and TeamCity will search for packages there, by the order of declaration. If a package source cannot be found in any of the specified repositories, TeamCity will search for it on NuGet.org.

Commands and Arguments Supported in Scripts

Supported commands:

Command	Description	Example
`#r`	Add a reference to a NuGet package or an assembly and its dependencies.	`#r "nuget:<package_name>, 1.2.3"` or `#r "<library_name>.dll"`
`#load`	Load the specified script file and execute it.	`#load "<script_name>.csx"`
`#help`	Display Help on available commands and key bindings.
`#l`	Set a verbosity level to `quiet`, `normal`, or `trace`.

Supported arguments:

arguments provided in the Script parameters field and stored in the Args array (for example, WriteLine(Args[0]) to write the value of the first script parameter);
system parameters specified in Build Configuration Settings | Parameters and stored in the Props dictionary (for example, WriteLine(Props["version"]) to write the value of the system.version parameter).

Last modified: 18 September 2024