f:id:masatsuna:20200911011224p:plain Azure Pipelines で PowerShell を組んでいると、パイプラインの実行エラーや警告をログ出力したくなるケースがよくあります。ただログを出力したいだけであれば、 Write-Host コマンドレットを使って標準出力に文字列を出力しても問題ありません。しかし、以下のようにパイプラインの実行結果のトップ画面である Summary ページに、エラーや警告の情報を出力できたらより良い状態になります。

f:id:masatsuna:20200911001947p:plain — Summary 画面の通知

今回はこのような出力 Azure Pipelines から行う方法について解説します。

環境

今回は PowerShell タスク（v2）を用います。

PowerShell タスクから警告/エラーの情報を出す

前述のような出力を行うためには、 Azure Pipelines の実行エンジンに対して、 PowerShell スクリプトから警告やエラーの情報を伝えてあげなければなりません。 Azure Pipelines の PowerShell タスクを使う場合、 Write-Host コマンドレットに特別な文字列を設定することで、この動作を実現できます。

trigger: none

pool:
  vmImage: 'windows-latest'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "##vso[task.LogIssue type=warning;]警告ログです"
      Write-Host "##vso[task.LogIssue type=error;]エラーログです"
    pwsh: true

Summary 画面には、エラーと警告、 2 つのログをサマリー表示してくれます。上述の PowerShell スクリプトの 1 行目、 2 行目が、それぞれのログを出力している箇所です。標準出力に対して ##vso[task.LogIssue type=xxxx;]ログ本文 の形式で文字列を流し込むことで、エラーや警告の情報を Summary 画面に出力できるようになります。

今回は PowerShell を用いていますが、 Bash や CMD を使う場合は、同様の文字列を echo コマンドで標準出力に出力することで、同じようなことが実現できます。

タスクを失敗させる

上記のパイプラインを実行すると、以下のような画面になります。

f:id:masatsuna:20200911003843p:plain — エラーがあるのにビルド成功？

見てもらうとわかる通り、エラーや警告は通知されているものの、ビルドパイプラインの実行は正常に終了している状態になります。この動作からも明らかですが、エラーや警告の情報を出力しただけでは、 PowerShell タスク、パイプライン全体の実行結果をエラーに設定することはできません。

PowerShell タスクを明示的に失敗に設定したい場合は、以下のように PowerShell タスク実装します。

trigger: none

pool:
  vmImage: 'windows-latest'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "##vso[task.LogIssue type=warning;]警告ログです"
      Write-Host "##vso[task.LogIssue type=error;]エラーログです"
      Write-Host "##vso[task.complete result=Failed;]タスクを失敗に設定します"
      return
    pwsh: true

PowerShell スクリプトの 3 行目で、この PowerShell タスクを失敗に設定しています。これにより、 PowerShell タスクが失敗するようになり、パイプライン自体も失敗となります。

しかし、この処理を PowerShell の世界で見ると、単純に標準出力に文字列を出力しているだけです。 PowerShell のスクリプトを了させる効果は、この 1 文にありません。そのため、タスクをエラーに設定した直後に、 return などスクリプトを強制的に終了させるコマンドを使ってください。この例ではあってもなくても関係ありませんが、特定の条件に当てはまる場合のみエラーとするなど、処理が複雑化してくると、意図しない処理が実行されてしまう危険があります。これら 2 つをセットで使うよう、意識付けしておくとよいと思います。

f:id:masatsuna:20200911004828p:plain — ビルドパイプラインも失敗扱いになる

タスクの失敗を通知するコマンドと return コマンドの組み合わせを実装するのがめんどくさい場合は、 exit 1 と実装することでも、同じような結果を得ることができます。ただし、 exit 1 を利用した場合、ビルドの Summary ページに、 exit 1 が呼び出されたことを示すエラーも表示されるようになります。これが気にくわない場合は、上記のような実装をすることをおすすめします。