PowerShell

PowerShell ビルドステップは、PowerShell スクリプトを実行するために特別に設計されています。

PowerShell 統合を担当するプラグインは、 GitHub (英語) でオープンソース化されています。

クロスプラットフォーム PowerShell

クロスプラットフォーム PowerShell (PowerShell Core) は Windows、macOS、Linux でサポートされています: 使用しているプラットフォーム用の PowerShell パッケージをダウンロードし、TeamCity エージェントにインストールしてください。
PowerShell Desktop と PowerShell Core の並行インストールは、Windows でサポートされています。

ビルドエージェントにインストール済みの PowerShell の検出

起動時に、TeamCity エージェントは Program Files と Windows ディレクトリなどの標準の場所、または ARM64 システムでは ~/powershell と /opt/microsoft/powershell/<バージョン>/ で PowerShell のインストールを検索します。カスタムの場所を teamcity.powershell.detector.search.paths エージェントプロパティで指定できるため、エージェントはこのディレクトリ (およびその子ディレクトリ) 内の PowerShell も検出できます。
複数の場所を一覧表示するには、パスを ; で区切ります。

PowerShell 設定

オプション	説明
バージョン	TeamCity がサポートする PowerShell バージョンのリスト。これは `-バージョン` コマンドライン引数として `powershell.exe` に渡されます。
PowerShell ランモード	x64 マシンで希望の実行モードを選択します。バージョンバージョンを指定してください（たとえば、1.0 または 2.0）。エージェントにインストールされているバージョンと比較され、適切な要件が追加されます。 Core エディションの場合は、下限として使用されます。デスクトップ版では、正確なバージョンが使用されます（`-バージョン` コマンドライン引数が追加されます）。バージョンフィールドが空白のままの場合、バージョン要件の下限は追加されず、PowerShell のデスクトップエディションでは `-バージョン` 引数は使用されません。プラットフォームプラットフォームのビット数を選択します。 `x64` — 64 ビット、デフォルト、対応する要件が追加されます `x86 アーキテクチャ` — 32 ビット、対応する要件が追加されます `自動` — 選択すると、ビルド構成にプラットフォーム要件は追加されません。また、32-bit と 64-bit の PowerShell が両方インストールされている場合は、64-bit が優先されます。エディション使用する PowerShell エディションを選択します。デスクトップ — Windows にバンドルされているクローズドソース版で、Windows プラットフォームでのみ使用できます。 Core — .NET Core に基づくオープンソース版、クロスプラットフォーム、64 ビットのみ
標準エラー出力を次のようにフォーマットします。	ランナーによるエラー出力の処理方法を指定します。エラー: `標準エラー出力` への出力はすべてエラーとして処理されます警告: デフォルト ; `標準エラー出力` への出力はすべて警告として扱われます「ビルドランナーによってエラーメッセージがログに記録される」場合にビルドを失敗させるには (ビルド失敗条件を参照)、エラー出力セレクターのデフォルト設定を警告からエラーに変更します。
作業ディレクトリ	ビルド作業ディレクトリへのパスを指定します。
スクリプト	スクリプトを TeamCity に直接入力するか、スクリプトへのパスを指定するかを選択します: ファイル: PowerShell ファイルへのパスを入力します。パスはチェックアウトディレクトリからの相対パスである必要があります。ソース: PowerShell スクリプトソースを入力します。 TeamCity のパラメーター参照はコード内で置き換えられることに注意してください。 PowerShell スクリプトのソースが VCS に保存された Kotlin DSL 構成で定義されている場合、PowerShell 変数参照は Kotlin では文字列テンプレートとして扱われることに注意してください。この問題を回避するため、TeamCity はソースフィールドに入力されたすべての参照を自動的にエスケープし、VCS 内のソースコードを更新します。ただし、VCS でスクリプトソースを直接変更する場合は、変数参照を `${'$'}reference_name` として手動でエスケープすることをお勧めします。または、スクリプトを別のファイルに保存し、ファイルフィールドで参照できます。この方法では、TeamCity はファイルのインポート時にも参照を適切に処理します。スクリプトに明示的に定義されたパラメーターが含まれている場合、PowerShell 2.0 が正しい終了コードを返さないという問題があります。回避策(英語)として、PowerShell をアップグレードするか、 `[Environment]::Exit(code)` を使用します。
スクリプト実行モード	PowerShell スクリプトの実行モードを指定してください。デフォルトでは、PowerShell は任意の `.ps1` ファイルの実行を許可しません。 TeamCity は `-ExecutionPolicy ByPass` 引数を提供しようとします。外部ファイルから .ps1 スクリプトを実行を選択した場合は、スクリプトに署名するか、PowerShell で任意の `.ps1` ファイルの実行を許可する必要があります。実行ポリシーでスクリプトの実行が許可されていない場合は、この問題を回避するためにスクリプトを PowerShell stdin に入力モードを選択してください。 `-Command` モードは非推奨であり、バージョン 1.0 以降の PowerShell での使用は推奨されていません。
スクリプト引数	「スクリプト実行モード」オプションが「外部ファイルから .ps1 スクリプトを実行」に設定されている場合に使用できます。 PowerShell スクリプトに引数として渡すビルドパラメーターを指定します。名前付き引数を使用する場合は、次のパターンに従ってください: `-<スクリプト引数 1> %build_parameter1% -<スクリプト引数 2> %build_parameter2%`。特殊シンボルのエスケープ TeamCity は、オペレーティングシステムのコンソール (Windows ではコマンドプロンプト、Linux では bash など) から `powershell.exe` を呼び出します。特殊シンボルを含むパラメーターが二重引用符で PowerShell スクリプトに渡される場合は、これらの文字が適切にエスケープされていることを確認してください: 使用するインタープリターに応じたエスケープルールを使用します。たとえば Windows で PowerShell スクリプト引数がバックスラッシュで終わる場合、TeamCity が正しく解釈できるようにバックスラッシュをエスケープシンボルとして使用します: `"foo\\"`。
追加のコマンドラインパラメーター	PowerShell 実行可能ファイルに渡されるパラメーターを指定します。

Docker 設定

このセクションでは、ビルドステップの実行に使用されるDocker イメージを指定できます。

現在の制限

Docker で実行するには、PowerShell 実行可能ファイルを PATH に追加する必要があります。
Docker を使用してビルドステップを実行する場合、Docker 関連のビルドエージェント要件のみがビルドに適用されます。
PowerShell ビルドステップでのエディションの選択は、使用されている実行可能ファイルに影響します（デスクトップの場合は powershell.exe 、コアの場合は pwsh）。
<Auto> のデフォルトは pwsh (Core) です。
カスタム PowerShell 実行可能ファイルを指定するには、 teamcity.powershell.virtual.executable 構成パラメーターを、提供されたイメージ内のこの実行可能ファイルの絶対パスに設定する必要があります。
Container Wrapper の現在の制限により、Windows システム上で Linux コンテナーを実行することはできません。

既知の課題

docker-compose コマンドが PowerShell Desktop バージョン 5.1.17763 以降で実行される場合、ビルドログに誤検知の警告しかなくても、PowerShell スクリプトがエラーで失敗する可能性があります。
この問題を回避するには、代わりに PowerShell Core を使用することをお勧めします。または、 docker-compose コマンドに --log-level ERROR 属性を追加することで、そのログレベルを制限できます。

TeamCity との連携

PowerShell を使用してサービスメッセージ経由で TeamCity と連携する場合は、注意が必要です。 PowerShell は、コンソールに書き込まれた文字列を Write-Output、 Write-Error などのコマンドでラップする傾向があります（TW-15080(英語) を参照）。この動作を回避するには、 Write-Host コマンドを使用するか、バッファー長を手動で調整します。

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 {}
  }
}


  

エラー処理

終了コード 0 が常に呼び出し元に返される PowerShell の問題により、TeamCity はスクリプトが正しく実行されたかどうかを常に検出できるわけではありません。スクリプトの実行エラーの検出に役立ついくつかのアプローチをお勧めします。

手動で例外をキャッチして明示的に終了コードを返す
PowerShell プラグインは powershell.exe の周囲の cmd ラッパーを使用しません。明示的な終了コードを返すことを可能にします。
try { # your code here } Catch { $ErrorMessage = $_.Exception.Message Write-Output $ErrorMessage exit(1) }
ビルド失敗条件の設定と追加:
構文エラーや例外が存在する場合、PowerShell はそれらを 標準エラー出力 に書き込みます。 TeamCity にビルドを失敗させるには、エラー出力オプションを エラー に設定し、何らかのエラー出力があるとビルドを失敗させるビルド失敗条件を追加します。
ビルドログ内の特定のメッセージでビルドに失敗した:
ビルドログ内の特定のメッセージ (「POWERSHELL ERROR」など) でビルドが失敗するビルド失敗条件を追加します。
$ErrorMessage = "POWERSHELL ERROR" try { # your code here } Catch { Write-Output $ErrorMessage exit(1) }

出力の処理

PowerShell からの非 ASCII 出力を適切に処理するには、PowerShell 側と TeamCity 側の両方で正しいエンコーディングを設定する必要があります。

PowerShell の出力エンコーディングを UTF-8 に設定するには、PowerShell スクリプトの先頭に次の行を追加します。
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
TeamCity エージェント側でエンコーディングを設定するには、Java 起動オプション -Dfile.encoding=UTF-8 を設定するか、ビルド構成パラメーターteamcity.runner.commandline.stdstreams.encoding の値を UTF-8 に設定します。

一時ファイル

TeamCity PowerShell プラグインは一時ファイルをエントリポイントとして使用します。これらのファイルはビルド一時ディレクトリに作成され、PowerShell ビルドステップの完了後に削除されます。ファイルを保持するには、 powershell.keep.generated または teamcity.dont.delete.temp.files 構成パラメーターを 真 に設定します。

開発リンク

PowerShell サポートはオープンソースのプラグインとして実装されています。開発リンクについてはプラグインのページ(英語)を参照してください。

2026 年 9 月 11 日