PowerShell

Edit page Last modified: 22 August 2023

The PowerShell build runner is specifically designed to run PowerShell scripts.

The plugin responsible for PowerShell integration has been open-sourced on GitHub.

tip

If you need to run a PowerShell script with elevated permissions, consider using the TeamCity RunAs plugin.

Cross-Platform PowerShell

  • Cross-platform PowerShell (PowerShell Core) is supported on Windows, macOS, and Linux: download a PowerShell package for your platform and install it on the TeamCity agent.

  • Side-by-side installation of PowerShell Desktop and PowerShell Core is supported under Windows.

Detection of Installed PowerShell on Build Agents

During the startup, a TeamCity agent searches for the PowerShell installation in standard locations, such as Program Files and Windows directories, or ~/powershell and /opt/microsoft/powershell/<version>/ in ARM64 systems. You can specify a custom location in the teamcity.powershell.detector.search.paths agent property, so the agent can detect PowerShell in this directory (and its children) as well.
To list multiple locations, separate their paths with ;.

PowerShell Settings

Option

Description

Version

List of PowerShell versions supported by TeamCity. It is passed to powershell.exe as the -Version command line argument.

PowerShell run mode

Select the desired execution mode on a x64 machine:

Version

Specify a version (for example, 1.0 or 2.0). It will be compared to the version installed on the agent, and an appropriate requirement will be added. For Core editions, it will be used as the lower bound. On Desktop editions, the exact version will be used (-Version command line argument will be added).

If the version field is left blank, no lower bound on the version requirement will be added, no -Version argument will be used on Desktop editions of PowerShell.

Platform

Select the platform bitness:

  • x64 — 64-bit, default, the corresponding requirement will be added

  • x86 — 32-bit, the corresponding requirement will be added

  • Auto — when it is selected, no platform requirement will be added to the build configuration, and if both 32-bit and 64-bit PowerShells are installed, 64-bit will be preferred.

Edition

Select a PowerShell edition to be used:

  • Desktop — closed-source edition bundled with Windows, available only on Windows platforms.

  • Core — open-source edition based on .NET Core, cross-platform, 64-bit only

Format stderr output as:

Specify how the error output is handled by the runner:

  • error: any output to stderr is handled as an error

  • warning: default; any output to stderr is handled as a warning

tip

To fail a build if "an error message is logged by build runner" (see Build Failure Conditions), change the default setting of the Error Output selector from warning to error.

Working directory

Specify the path to the build working directory.

Script

Select whether you want to enter the script right in TeamCity, or specify a path to the script:

  • File: Enter the path to a PowerShell file. The path has to be relative to the checkout directory.

  • Source: Enter the PowerShell script source. Note that TeamCity parameter references will be replaced in the code.

note

If your PowerShell script source is defined via a Kotlin DSL configuration stored in VCS, note that PowerShell variable references are treated in Kotlin as string templates. To work around this issue, TeamCity automatically escapes all references entered in the Source field and updates the source code in VCS. However, if you modify the script source directly in the VCS, we suggest that you manually escape variable references as ${'$'}reference_name.
Alternatively, you can store your script in a separate file and reference it in the File field. This way, TeamCity will also properly process references on importing the file.

note

There is an issue with PowerShell 2.0 not returning the correct exit code when the script contains explicitly defined parameters. As a workaround, either upgrade your PowerShell or to use [Environment]::Exit(code).

Script execution mode

Specify the PowerShell script execution mode. By default, PowerShell may not allow execution of arbitrary .ps1 files. TeamCity will try to supply the -ExecutionPolicy ByPass argument. If you've selected Execute .ps1 script from external file, your script should be signed or you should make PowerShell allow execution of arbitrary .ps1 files. If the execution policy doesn't allow running your scripts, select Put script into PowerShell stdin mode to avoid this issue.

The -Command mode is deprecated and is not recommended for use with PowerShell of version greater than 1.0.

Script arguments

Available if "Script execution mode" option is set to "Execute .ps1 script from external file".

Specify build parameters to be passed as arguments into the PowerShell script.
When using named arguments, follow this pattern: -<script_argument1> %build_parameter1% -<script_argument2> %build_parameter2%.

note

Escaping special symbols

TeamCity calls powershell.exe from the console of your operating system (command prompt on Windows, bash or other on Linux).

If parameters containing special symbols are passed to your PowerShell script in double quotes, make sure these characters are properly escaped: use the escape rules depending on your interpreter, for example, on Windows, if a PowerShell script argument ends with a backslash, use the backslash as the escape symbol for TeamCity to correctly interpret it: "foo\\".

Additional command line parameters

Specify parameters to be passed to the PowerShell executable.

Docker Settings

In this section, you can specify the Docker image which will be used to run the build step.

Current Limitations

  • Execution under Docker requires the PowerShell executable to be added to PATH.

  • When using Docker to run the build step, only Docker-related build agent requirements are applied to the build.

  • Selection of Edition in PowerShell build step affects the executable being used (powershell.exe for Desktop, pwsh for Core).

  • <Auto> defaults to pwsh (Core).

  • To specify a custom PowerShell executable, the teamcity.powershell.virtual.executable configuration parameter must be set to the full path of this executable inside the provided image.

  • Current limitations of the Container Wrapper do not allow Linux containers running under Windows systems.

Known Issues

  • If the docker-compose command is run via PowerShell Desktop version 5.1.17763 or later, the PowerShell script could potentially fail with an error despite having only false positive warnings in the build log.
    To work around this problem, we suggest using PowerShell Core instead. Alternatively, you can limit the logging level for the docker-compose command by adding the --log-level ERROR attribute to it.

Interaction with TeamCity

Attention must be paid when using PowerShell to interact with TeamCity through service messages. PowerShell tends to wrap strings written to the console with commands like Write-Output, Write-Error and similar (see TW-15080). To avoid this behavior, either use the Write-Host command, or adjust the buffer length manually:

function Set-PSConsole {
  if (Test-Path env:TEAMCITY_VERSION) {
    try {
      $rawUI = (Get-Host).UI.RawUI
      $m = $rawUI.MaxPhysicalWindowSize.Width
      $rawUI.BufferSize = New-Object Management.Automation.Host.Size ([Math]::max($m, 500), $rawUI.BufferSize.Height)
      $rawUI.WindowSize = New-Object Management.Automation.Host.Size ($m, $rawUI.WindowSize.Height)
    } catch {}
  }
}

Error Handling

Due to the PowerShell issue that causes zero exit code to be always returned to a caller, TeamCity cannot always detect whether the script has executed correctly or not. We recommend several approaches that can help in detecting script execution failures:

  • Manually catching exceptions and explicitly returning exit code
    The PowerShell plugin does not use the cmd wrapper around powershell.exe. It makes returning the explicit exit code possible.

    try {
# your code here
} Catch {
$ErrorMessage = $_.Exception.Message
Write-Output $ErrorMessage
exit(1)
}

  • Setting to and adding a build failure condition:
    In case syntax errors and exceptions are present, PowerShell writes them to stderr. To make TeamCity fail the build, set Error Output option to Error and add a build failure condition that will fail the build on any error output.

  • Failing build on certain message in build log:
    Add a build failure condition that will fail the build on a certain message (say "POWERSHELL ERROR") in the build log.

    $ErrorMessage = "POWERSHELL ERROR"
try {
  # your code here
} Catch {
  Write-Output $ErrorMessage
  exit(1)
}

Handling Output

To properly handle non-ASCII output from PowerShell, the correct encoding must be set both on the PowerShell side and on the TeamCity side.

  • To set the output encoding for PowerShell to UTF-8, add the following line to the beginning of your PowerShell script:

    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

  • To set the encoding on the TeamCity agent side, either set the Java launch option -Dfile.encoding=UTF-8, or set the build configuration parameter teamcity.runner.commandline.stdstreams.encoding value to UTF-8.

Temporary Files

The TeamCity PowerShell plugin uses temporary files as an entry point; these files are created in the build temporary directory and removed after the PowerShell build step is finished. To keep the files, set the powershell.keep.generated or teamcity.dont.delete.temp.files configuration parameter to true.

The PowerShell support is implemented as an open-source plugin. For development links refer to the plugin's page.