Runbook 輸出和訊息

 

發佈時間: 2016年6月

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

大部分的 Automation Runbook 將會有某種形式的輸出，例如向使用者提供錯誤訊息，或供其他工作流程使用的複雜物件。 Windows PowerShell 提供多個資料流，以便從工作流程傳送輸出。服務管理自動化 以不同方式處理其中每個資料流，您應該在建立 Runbook 時遵循最佳作法來使用每個資料流。

下表簡述每個資料流，及它們在執行已發佈的 Runbook 和測試 Runbook 的管理入口網站中的行為。 後續各節將提供每個資料流的進一步詳細資料。

資料流	說明	已發行	測試
輸出	供其他 Runbook 使用的物件。	寫入工作歷程記錄。	顯示於測試輸出窗格。
警告	適用於使用者的警告訊息。	寫入工作歷程記錄。	顯示於測試輸出窗格。
錯誤	適用於使用者的錯誤訊息。 不像例外狀況，Runbook 預設會在出現錯誤訊息後繼續執行。	寫入工作歷程記錄。	顯示於測試輸出窗格。
詳細資訊	提供一般或疑難排解資訊的訊息。	只有為 Runbook 開啟詳細記錄時才會寫入工作歷程記錄。	只有在 Runbook 中將 $VerbosePreference 設為 Continue 時，才會在測試輸出窗格中顯示。
進度	在 Runbook 中每項活動之前和之後自動產生記錄。 Runbook 不應嘗試建立它自己的進度記錄，因為它們是供互動式使用者使用。	只有為 Runbook 開啟進度記錄時才會寫入工作歷程記錄。	不的顯示於測試輸出窗格。
偵錯	適用於互動式使用者的訊息。 不應該在 Runbook 中使用。	不寫入工作歷程記錄。	不會寫入測試輸出窗格中。

輸出資料流

輸出資料流適用於工作流程所建立的物件輸出 (當它能正確執行時)。 在 自動化 中，此資料流主要由呼叫目前 Runbook 的父 Runbook 使用。 當您從父 Runbook 呼叫 Runbook 內嵌時，它會將輸出資料流的資料傳回父代。 只有當您知道 Runbook 永遠不會被另一個 Runbook 呼叫時，您才應該使用輸出資料流通訊將一般資訊傳回使用者進行溝通。 但最佳作法一般是使用 詳細資料流，將一般資訊傳給使用者。

您可以使用 Write-Output，或將物件放在它自己在 Runbook 中的該行，將資料寫入輸出資料流。

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

從函式輸出

當您在 Runbook 包括的函式中寫入輸出資料流時，會將輸出傳遞回 Runbook。 如果 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 Cmdlet 建立警告或錯誤訊息。 也可能會將活動寫入這些資料流。

#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 設為 [記錄詳細資訊記錄]。 在大部分情況下，您應該保留預設設定，亦即基於效能考量，不記錄 Runbook 的詳細資訊記錄。 只有在疑難排解或偵錯 Runbook 時才開啟這個選項。

$VerbosePreference 變數預設為值 SilentlyContinue。 您不需要在已發佈的 Runbook 中變更這個變數，就可以儲存詳細訊息。 如果在已發佈 Runbook 中將此值明確設定為 [SilentlyContinue]，則即使設定 Runbook 來記錄詳細資訊記錄，仍不會儲存詳細訊息。

測試 Runbook 時，即使將 Runbook 設定為記錄詳細資訊記錄，仍不會顯示詳細訊息。 若要在測試 Runbook 時顯示詳細訊息，您必須將 $VerbosePreference 變數設為 [Continue]。 設定該變數後，詳細訊息會顯示在管理入口網站的 [測試輸出] 窗格中。

使用 Write-Verbose Cmdlet 建立詳細訊息。

#The following line creates a verbose message.

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

偵錯資料流

偵錯資料流適用於互動式使用者，並且不應用於 Runbook。

進度記錄

如果您設定 Runbook 來記錄進度記錄 (在管理入口網站中 Runbook 的 [設定] 索引標籤)，則會在執行每一個活動之前和之後，將記錄寫入到工作歷程記錄。 在大部分情況下，您應該保留預設設定，亦即不記錄 Runbook 的進度記錄以獲得最高效能。 只有在疑難排解或偵錯 Runbook 時才開啟這個選項。 測試 Runbook 時，即使 Runbook 設定為記錄進度記錄，也不會顯示進度訊息。

Write-Progress Cmdlet 在 Runbook 中無效，因為它是供與互動式使用者進行溝通的使用者使用。

喜好設定變數

Windows PowerShell 使用喜好設定變數，決定如何回應傳送至不同輸出資料流的資料。 您可以在 Runbook 中設定這些變數，控制如何回應傳送到不同資料流的資料。

下表列出可用於 Runbook 的喜好設定變數及其有效值和預設值。 請注意，本表只包含 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。

擷取 Runbook 輸出和訊息

管理入口網站

您可以從 Runbook 的 [工作] 索引標籤，在管理入口網站中檢視 Runbook 工作的詳細資料。 作業的 [摘要] 除了顯示作業的一般資訊及任何發生的例外狀況，還會顯示輸入參數和輸出資料流。 [歷程] 除了包含詳細資料流和進度記錄 (如果 Runbook 設定為記錄詳細資訊和進度記錄)，還包含來自輸出資料流和 警告和錯誤資料流的訊息。

Windows PowerShell

在 Windows PowerShell 中，您可以使用 Get-SmaJobOutput Cmdlet，從 Runbook 擷取輸出和訊息。 這個 Cmdlet 需要工作的識別碼，而且具有稱為 Stream 的參數，可讓您指定要傳回的資料流。 您可以指定 [Any] 以傳回工作的所有資料流。

下列範例會啟動 Runbook 範例，然後等待其完成。 完成後，就會從工作收集其輸出資料流。

$webServer = 'https://MyServer'
$port = 9090
$runbookName = "Test-Runbook"
$job = Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName

$doLoop = $true
While ($doLoop) {
   $job = Get-SmaJob –WebServiceEndpoint $webServer –Port $port -Id $job.Id
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped") 
}

Get-SmaJobOutput –WebServiceEndpoint $webServer –Port $port -Id $job.Id –Stream Output

請參閱

以 Runbook 擴充 Service Management Automation
Runbook Authoring