TeamCity 2020.2 ヘルプ

PowerShell

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

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

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

ビルドエージェントにインストールされている 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 スクリプトの実行モードを指定してください。デフォルトでは、PowerShell は任意の .ps1 ファイルの実行を許可しません。TeamCity は -ExecutionPolicy ByPass 引数を提供しようとします。外部ファイルから .ps1 スクリプトを実行するを選択した場合は、スクリプトに署名するか、PowerShell で任意の .ps1 ファイルの実行を許可する必要があります。実行ポリシーでスクリプトの実行が許可されていない場合は、この問題を回避するためにスクリプトを PowerShell 標準入力に入れるモードを選択してください。

-Command モードは非推奨であり、バージョン 1.0 以降の PowerShell での使用は推奨されていません。

スクリプト引数

スクリプト実行モードオプションが外部ファイルから .ps1 スクリプトを実行するに設定されている場合に使用できます。

PowerShell スクリプトに引数として渡されるビルドパラメーターを指定します。
名前付き引数を使用する場合は、-<script_argument1> %build_parameter1% -<script_argument2> %build_parameter2% のパターンに従ってください。

追加コマンド行パラメーター

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