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

Since TeamCity 2017.1, TeamCity provides support for PowerShell on Linux and Mac OS: download a PowerShell package for your platform and install it on the TeamCity agent.

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`.

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