Icon

You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 
Skip to end of metadata
Go to start of metadata

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

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.

Error Output

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

    Icon

    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.

    Icon

    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.

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:

Error Handling

Due to this issue in PowerShell itself which 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
    Since TeamCity 9.0 the PowerShell plugin does not use the cmd wrapper around powershell.exe. It makes returning the explicit exit code possible.

 

  • Setting Error Output to Error and adding 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.

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

  • No labels

2 Comments

  1. When I use Powershell runner, I see the script options of FIle and Source Code.

    Then there is the script execution mode of Execute ps1 from external file and Put script into PowerShell stdin with "-Command -" argument. 

    If I select Source Code as Script, I get Script Source.

    So my question is it acceptable to use Source Code and Execute ps1 from external file or is it supposed to select the appropriate script execution mode based on the selected script option?

    1. Yes, it is acceptable. The first option describes where to get the script, the second - how to execute it