PowerShell

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

The plugin responsible for PowerShell integration has been opensourced on GitHub: https://github.com/JetBrains/teamcity-powershell

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 installations of PowerShell Desktop and PowerShell Core is supported under Windows.

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 (e.g. 1.0, 2.0, etc.). 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 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: (since TeamCity 2017.1) 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 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. 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 here arguments to be passed into PowerShell script. 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, e.g. 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 `powershell.exe`.

Docker Settings

To enable support for Docker in PowerShell steps, run the TeamCity server with the -Dteamcity.docker.runners=jetbrains_powershell internal property.

In this section, you can specify a 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, theteamcity.powershell.virtual.executable configuration parameter must be set to the full path of this executable inside the provided image
Current limitations of the Docker wrapper do not allow Linux containers running under Windows systems

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 this issue in PowerShell itself 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 codeThe 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 logAdd 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 toUTF-8

Temporary Files

The TeamCity PowerShell plugin uses temporary files as an entry point; these files are created in the build temporary folder 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.

Development Links

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

Last modified: 20 April 2023