PowerShell

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

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

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

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

ビルドエージェントにインストールされている PowerShell の検出

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

PowerShell の設定

オプション	説明
バージョン	TeamCity がサポートしている PowerShell バージョンのリスト。これは `-Version` コマンドライン引数として `powershell.exe` に渡されます。
PowerShell ランモード	x64 マシンで希望の実行モードを選択します。バージョンバージョンを指定してください（たとえば、1.0 または 2.0）。エージェントにインストールされているバージョンと比較され、適切な要件が追加されます。Core エディションの場合は、下限として使用されます。デスクトップ版では、正確なバージョンが使用されます（`-Version` コマンドライン引数が追加されます）。バージョンフィールドが空白のままの場合、バージョン要件の下限は追加されず、PowerShell のデスクトップエディションでは `-Version` 引数は使用されません。プラットフォームプラットフォームのビット数を選択します。 `x64` — 64 ビット、デフォルト、対応する要件が追加されます `x86` — 32 ビット、対応する要件が追加されます `Auto` — 選択されている場合、ビルド要件にプラットフォーム要件は追加されません。32 ビットと 64 ビットの両方の PowerShell がインストールされている場合は、64 ビットが優先されます。版使用する PowerShell エディションを選択します。デスクトップ — Windows にバンドルされているクローズドソース版で、Windows プラットフォームでのみ使用できます。 Core — .NET Core に基づくオープンソース版、クロスプラットフォーム、64 ビットのみ
標準エラー出力を次のようにフォーマットします。	ランナーによるエラー出力の処理方法を指定します。エラー : `stderr` への出力はすべてエラーとして処理されます警告 : デフォルト ; `stderr` への出力はすべて警告として扱われます「ビルドランナーによってエラーメッセージが記録される」場合にビルドを失敗させるには ( ビルドの失敗条件を参照)、エラー出力セレクターのデフォルト設定を warning から error に変更します。
作業ディレクトリ	ビルド作業ディレクトリへのパスを指定します。
スクリプト	スクリプトを 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 標準入力に入れるモードを選択してください。 `-Command` モードは非推奨であり、バージョン 1.0 以降の PowerShell での使用は推奨されていません。
スクリプト引数	スクリプト実行モードオプションが外部ファイルから .ps1 スクリプトを実行するに設定されている場合に使用できます。 PowerShell スクリプトに引数として渡されるビルドパラメーターを指定します。名前付き引数を使用する場合は、次のパターンに従ってください。`-<script_argument1> %build_parameter1% -<script_argument2> %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 デスクトップバージョン 5.1.17763 以降を介して実行された場合、ビルドログに誤検知の警告しかないにもかかわらず、PowerShell スクリプトがエラーで失敗する可能性があります。
この問題を回避するには、代わりに PowerShell Core を使用することをお勧めします。または、--log-level ERROR 属性を追加して、docker-compose コマンドのログレベルを制限することもできます。

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

エラー処理

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

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

開発リンク

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

2026 年 3 月 08 日

TeamCity オンプレミス 2025.11 ヘルプ