[アーティクル]
07/08/2016

Runbook の出力とメッセージ

発行: 2016年6月

適用対象: Windows Azure Pack for Windows Server,System Center 2012 R2 Orchestrator

ほとんどのオートメーション Runbook は、ユーザーや別のワークフローでの使用を目的とした複合オブジェクトに、エラーメッセージなどの何らかの形式の出力を行います。 Windows PowerShell は、複数のストリームを使用してワークフローから出力を送信します。サービス管理オートメーションはこれらのストリームを個別に処理するため、Runbook を作成する場合は、それぞれの使用方法のベストプラクティスに従う必要があります。

次の表では、公開済みの Runbook を実行する場合と Runbook をテストする場合の、管理ポータルでの各ストリームの簡単な説明とその動作を示しています。各ストリームの詳細については、次のセクションで説明します。

ストリーム	説明	公開済み	[テスト]
出力	他の Runbook での使用を目的としたオブジェクト。	ジョブ履歴に書き込まれます。	テスト出力ウィンドウに表示されます。
警告	ユーザーを対象とした警告メッセージ。	ジョブ履歴に書き込まれます。	テスト出力ウィンドウに表示されます。
エラー	ユーザーを対象とした警告エラーメッセージ。例外とは異なり、既定ではエラーメッセージの後も Rrunbook が続行します。	ジョブ履歴に書き込まれます。	テスト出力ウィンドウに表示されます。
詳細	一般情報やトラブルシューティング情報を提供するメッセージ。	詳細ログが Runbook で有効になっている場合のみ、ジョブ履歴に書き込まれます。	$VerbosePreference が Runbook で [続行] に設定されている場合のみ、テスト出力ウィンドウに表示されます。
進行状況	Runbook で各アクティビティの前後に自動的に生成されるレコード。 Runbook では、対話ユーザーを対象としているため、独自の進行状況レコードが作成されません。	進行状況ログが Runbook で有効になっている場合のみ、ジョブ履歴に書き込まれます。	テスト出力ウィンドウに表示されません。
デバッグ	対話ユーザーを対象とするメッセージ。 Runbook では使用されません。	ジョブ履歴に書き込まれません。	テスト出力ウィンドウに書き込まれません。

出力ストリーム

出力ストリームは、ワークフローが正常に実行されたときに作成されるオブジェクトの出力を目的としています。オートメーションでは、このストリームは主に、現在の Runbook を呼び出す親 Runbook での使用を目的としたオブジェクトで使用されます。親 Runbook から Runbook のインラインを呼び出すと、出力ストリームから親 Runbook にデータが返されます。 Runbook が別の Runbook から呼び出されないことがわかっている場合は、出力ストリームのみを使用してユーザーに一般情報を伝える必要があります。ただし、ベストプラクティスとして、通常は詳細ストリームを使用してユーザーに一般情報を伝える必要があります。

Runbook で、Write-output を使用するか、独自の行にオブジェクトを配置することで、出力ストリームにデータを書き込むことができます。

#The following lines both write an object to the output stream.
Write-Object –InputObject $object
$object

関数からの出力

Runbook に含まれている関数内で出力ストリームに書き込むと、その出力は Rrunbook に渡されます。 Runbook がその出力を変数に割り当てている場合は、出力ストリームに書き込まれません。関数内から他のストリームに書き込む場合は、Runbook の対応するストリームに書き込まれます。

次の Runbook の例を考えてみます。

Workflow Test-Runbook
{
   Write-Verbose "Verbose outside of function"
   Write-Output "Output outside of function"
   $functionOutput = Test-Function

   Function Test-Function
   {
      Write-Verbose "Verbose inside of function"
      Write-Output "Output inside of function"
   }
}

Runbook ジョブの出力ストリームは、次のようになります。

Output outside of function

Runbook ジョブの詳細ストリームは、次のようになります。

Verbose outside of function
Verbose inside of function

$FunctionOutput 変数に値を指定します。

Output inside of function

出力のデータ型を宣言する

ワークフローは、OutputType 属性を使用して、その出力のデータ型を指定できます。この属性は実行時に影響しませんが、Runbook の予想される出力のデザイン時に Runbook の作成者に目安を提供します。 Runbook のツールセットが進化するにつれて、デザイン時に出力のデータ型を宣言する重要性が高まります。結果的に、作成する Runbook に次の宣言を含めることをお勧めします。

次の Runbook の例では、文字列オブジェクトの出力とその出力の型の宣言を示しています。 Runbook が特定の型の配列を出力する場合は、型の配列ではなく型を指定する必要があります。

Workflow Test-Runbook
{
   [OutputType([string])]

   $output = "This is some string output."
   Write-Output $output
}

メッセージストリーム

出力ストリームとは異なり、メッセージストリームはユーザーに情報を伝えることを目的としています。さまざまな種類の情報に対して複数のメッセージストリームがあり、オートメーションによってそれぞれ異なる方法で処理されます。

警告ストリームとエラーストリーム

警告ストリームとエラーストリームは、Runbook で発生する問題をログに記録することを目的としています。これらは、Runbook を実行するとジョブ履歴に書き込まれ、Runbook をテストすると管理ポータルのテスト出力ウィンドウに表示されます。既定では、警告やエラーの後も Runbook は実行し続けます。メッセージを作成する前に、Runbook でユーザー設定変数を設定すると、警告やエラーで Runbook を中断するように指定できます。たとえば、例外としてエラーで Runbook を中断するには、$ErrorActionPreference を Stop に設定します。

Write-Warning または Write-Error コマンドレットを使用して、警告メッセージまたはエラーメッセージを作成します。アクティビティはこれらのストリームに書き込むこともできます。

#The following lines create a warning message and then an error message that will suspend the runbook.

$ErrorActionPreference = "Stop"
Write-Warning –Message "This is a warning message."
Write-Error –Message "This is an error message that will stop the runbook because of the preference variable."

詳細ストリーム

詳細メッセージストリームは、Runbook の操作に関する一般情報です。 Runbook ではデバッグストリームを使用できないため、詳細メッセージをトラブルシューティング情報に使用する必要があります。既定では、公開済みの Runbook からの詳細メッセージはジョブ履歴に格納されません。詳細メッセージを格納するには、管理ポータルの Runbook の [構成] タブで、公開済み Runbook を [Log Verbose Records (詳細レコードを記録)] に設定します。ほとんどの場合は、パフォーマンス上の理由から、Runbook の詳細レコードを記録しない既定の設定を保持してください。このオプションは、Runbook のトラブルシューティングやデバッグの場合のみ有効にします。

$VerbosePreference 変数は、既定で SilentlyContinue に設定されています。格納される詳細メッセージに対して公開済みの Runbook でこの変数を変更する必要はありません。この値が公開済みの Runbook で明示的に SilentlyContinue に設定されている場合は、Runbook が詳細レコードを記録するように構成されている場合でも、詳細メッセージは保存されません。

Runbook をテストするときに、Runbook が詳細レコードを記録するように構成されている場合でも、詳細メッセージは表示されません。 Runbook のテスト時に詳細メッセージを表示するには、$VerbosePreference 変数を Continue に設定する必要があります。この変数を設定すると、管理ポータルのテスト出力ウィンドウに詳細メッセージが表示されます。

Write-Verbose コマンドレット使用して、詳細メッセージを作成します。

#The following line creates a verbose message.

Write-Verbose –Message "This is a verbose message."

デバッグストリーム

デバッグストリームは、対話ユーザーとの使用を目的としているため、Runbook では使用しません。

進捗状況レコード

進行状況レコードを記録するように Runbook を構成した場合 (管理ポータルの Runbook の [構成] タブで)、レコードは各アクティビティが実行された前後にジョブ履歴に書き込まれます。ほとんどの場合は、パフォーマンスを最大限活用するために、Runbook の進行状況レコードを記録しない既定の設定を保持してください。このオプションは、Runbook のトラブルシューティングやデバッグの場合のみ有効にします。 Runbook をテストするときに、Runbook が進行状況レコードを記録するように構成されている場合でも、進行状況メッセージは表示されません。

Write-progress コマンドレットは、対話ユーザーとの使用を目的としているため、Runbook では無効になっています。

ユーザー設定変数

Windows PowerShell は、ユーザー設定変数を使用して、別の出力ストリームに送信されるデータに応答する方法を決定します。 Runbook でこれらの変数を設定して、異なるストリームに送信されるデータに応答する方法を制御できます。

次の表では、有効な既定値が設定された Runbook で使用できるユーザー設定変数を一覧しています。この表は、1 つの Runbook でのみ有効な値を示しています。サービス管理オートメーション以外の Windows PowerShell で使用する場合は、これ以外の値もユーザー設定変数で使用できます。

変数	既定値	有効な値
WarningPreference	Continue	Stop Continue SilentlyContinue
ErrorActionPreference	Continue	Stop Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continue SilentlyContinue

次の表では、Runbook で有効なユーザー設定変数値の動作を一覧しています。

値	動作
Continue	メッセージを記録し、Runbook を実行し続けます。
SilentlyContinue	メッセージを記録せずに、Runbook を実行し続けます。これは、メッセージを無視する効果があります。
Stop	メッセージを記録し、Runbook を中断します。