共用方式為

執行手冊輸出和訊息

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

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

小溪 描述 已發行 測試
輸出 供其他 Runbook 使用的物件。 寫入工作歷程記錄。 顯示於測試輸出窗格。
警告 適用於使用者的警告訊息。 寫入工作歷程記錄。 顯示於測試輸出窗格。
錯誤 適用於使用者的錯誤訊息。 不像例外狀況，Runbook 預設會在出現錯誤訊息後繼續執行。 寫入工作歷程記錄。 顯示於測試輸出窗格。
詳細資訊 提供一般或疑難排解資訊的訊息。 只有為 Runbook 開啟詳細日誌記錄時才會寫入工作歷程記錄。 只有在 Runbook 中將 $VerbosePreference 設為 Continue 時，才會在測試輸出窗格中顯示。
進度 在 "Runbook" 中，每個活動之前和之後都會自動生成紀錄。 runbook 不應該嘗試建立自己的進度記錄，因為進度記錄是針對互動式使用者設計的。 只有在為 Runbook 開啟進度記錄時，才會寫入至作業歷程記錄。 未顯示於測試輸出窗格。
偵錯 適用於互動式使用者的訊息。 不應在操作手冊中使用。 不寫入工作歷程記錄。 不會寫入測試輸出窗格中。

輸出資料流

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

您可以使用 Write-Output 或將物件放在運行簿中的獨立一行來將資料寫入輸出資料流。

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

函式的輸出

當您在 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 在發生錯誤時像處理例外狀況一樣暫停，請將 $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 已設定為記錄進度記錄，進度訊息也不會顯示。

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

喜好設定變數

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

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

注意

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

變數 預設值 有效的值
警告偏好 繼續 停
繼續<\br>
\SilentlyContinue
ErrorActionPreference 繼續 停
繼續
靜默持續
VerbosePreference 靜默持續 停
繼續
靜默持續

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

價值 行為
繼續 將該訊息記錄下來，並繼續執行運行手冊。
靜默持續 繼續執行運行手冊，而不記錄訊息。 這種作法會忽略訊息。
停 將訊息記錄並暫停 Runbook。

擷取工作流程手冊的輸出和訊息

管理入口網站

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

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

下一步

撰寫自動化工作手冊。