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

Detection of Installed PowerShell on Build Agents

During startup, a TeamCity agent searches for the PowerShell installation in standard locations, such as Program Files and Windows directories. 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

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.

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