PowerShell

PowerShell ビルドランナーは、PowerShell スクリプトを実行するように特別に設計されています。

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

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

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

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

起動時に、TeamCity エージェントは、Program Files および Windows ディレクトリなどの標準の場所で 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 ビットのみ
標準エラー出力を次のようにフォーマットします。	ランナーによるエラー出力の処理方法を指定します。 error : `stderr` への出力はすべてエラーとして処理されます警告 : デフォルト ; `stderr` への出力は警告として処理されます「エラーメッセージがビルドランナーによってログに記録される」場合（ビルドの失敗条件を参照）、ビルドを失敗させるには、エラー出力セレクターのデフォルト設定を警告からエラーに変更します。
作業ディレクトリ	ビルド作業ディレクトリへのパスを指定します。
スクリプト	スクリプトを TeamCity に直接入力するか、スクリプトへのパスを指定するかを選択します。ファイル :PowerShell ファイルへのパスを入力します。パスは、チェックアウトディレクトリからの相対パスである必要があります。ソース :PowerShell スクリプトソースを入力します。TeamCity パラメーター参照はコードで置き換えられることに注意してください。 PowerShell スクリプトソースが VCS に格納されている Kotlin DSL 構成を介して定義されている場合、PowerShell 変数参照は Kotlin では文字列テンプレート(英語)として扱われることに注意してください(英語)。この問題を回避するために、TeamCity は、ソースフィールドに入力されたすべての参照を自動的にエスケープし、VCS のソースコードを更新します。ただし、VCS でスクリプトソースを直接変更する場合は、変数参照を `${'$'}reference_name` として手動でエスケープすることをお勧めします。または、スクリプトを別のファイルに保存して、ファイルフィールドで参照することもできます。このようにして、TeamCity はファイルのインポート時に参照も適切に処理します。スクリプトに明示的に定義されたパラメーターが含まれている場合、PowerShell2.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 は、オペレーティングシステムのコンソールから `powershell.exe` を呼び出します（Windows のコマンドプロンプト、Linux の bash またはその他）。特殊記号を含むパラメーターを二重引用符で囲んで PowerShell スクリプトに渡す場合は、これらの文字が正しくエスケープされていることを確認してください。たとえば、Windows では、PowerShell スクリプト引数がバックスラッシュで終了する場合正しく解釈するには、TeamCity のエスケープ記号としてバックスラッシュを使用してください。`"foo\\"`
追加コマンド行パラメーター	`powershell.exe` に渡すパラメーターを指定してください。

Docker の設定

PowerShell ステップで Docker のサポートを有効にするには、-Dteamcity.docker.runners=jetbrains_powershell 内部プロパティを使用して TeamCity サーバーを実行します。

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

現在の制限

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

既知の問題

docker-compose コマンドが PowerShell デスクトップバージョン 5.1.17763 以降を介して実行された場合、ビルドログに誤検知の警告しかないにもかかわらず、PowerShell スクリプトがエラーで失敗する可能性があります。
この問題を回避するには、代わりに PowerShell コアを使用することをお勧めします。または、--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 に設定し、エラー出力でビルドに失敗するビルド失敗条件を追加します。
ビルドログの特定のメッセージでビルドに失敗しました :
ビルドログの特定のメッセージ（「POWERSHELLERROR」など）でビルドが失敗するビルド失敗条件を追加します。
$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 サポートはオープンソースのプラグインとして実装されています。開発リンクについてはプラグインのページ(英語)を参照してください。

最終更新日: 2021 年 2 月 26 日

TeamCity 2020.2 ヘルプ