PowerShell
The PowerShell build runner is specifically designed to run PowerShell scripts.
The plugin responsible for PowerShell integration has been open-sourced on GitHub.
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 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 ( If the version field is left blank, no lower bound on the version requirement will be added, no Platform Select the platform bitness:
Edition Select a PowerShell edition to be used:
|
Format stderr output as: | Specify how the error output is handled by the runner:
|
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:
|
Script execution mode | Specify the PowerShell script execution mode. By default, PowerShell may not allow execution of arbitrary The |
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. |
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 Docker 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 thedocker-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:
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 aroundpowershell.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 tostderr
. To make TeamCity fail the build, set Error Output option toError
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]::UTF8To set the encoding on the TeamCity agent side, either set the Java launch option
-Dfile.encoding=UTF-8
, or set the build configuration parameterteamcity.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 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
.
Development Links
The PowerShell support is implemented as an open-source plugin. For development links refer to the plugin's page.