共用方式為

Runbook 輸出和訊息

  • 發行項

大部分的自動化 Runbook 都會有某種形式的輸出，例如錯誤訊息給使用者，或想要由另一個工作流程取用的複雜物件。 Windows PowerShell 提供 多個資料流 ，以便從工作流程傳送輸出。 服務管理自動化會以不同的方式與每一個數據流搭配運作，您應該遵循在建立 Runbook 時如何使用每個數據流的最佳做法。

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

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

輸出資料流

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

您可以使用 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 已設定為記錄進度記錄，進度訊息也不會顯示。

Write-Progress Cmdlet 在 Runbook 中無效，因為它適用於與互動式使用者搭配使用。

喜好設定變數

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

下表列出可用於 Runbook 的喜好設定變數及其有效值和預設值。

注意

此數據表只包含 Runbook 中有效的值。 在 Service Management Automation 外部的 Windows PowerShell 中使用時，其他值對喜好設定變數有效。

變數 預設值 有效的值
WarningPreference 繼續 停止
Continue<\br>
\SilentlyContinue
ErrorActionPreference 繼續 停止
繼續
SilentlyContinue
VerbosePreference SilentlyContinue 停止
繼續
SilentlyContinue

下表列出 Runbook 中有效的喜好設定變數值的行為。

值 行為
繼續 將訊息記錄，並繼續執行 Runbook。
SilentlyContinue 繼續執行 Runbook 而不記錄訊息。 這種作法會忽略訊息。
停止 將訊息記錄並擱置 Runbook。

擷取 Runbook 輸出和訊息

管理入口網站

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

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。