Runbookausgabe und Meldungen

Die meisten automatisierten Runbooks haben irgendeine Form der Ausgabe, wie z. B. eine Fehlermeldung an den Benutzenden oder ein komplexes Objekt, das von einem anderen Workflow verwendet werden soll. Windows PowerShell stellt mehrere Streams zum Senden von Ausgaben aus einem Workflow bereit. Service Management Automation arbeitet mit jedem dieser Ströme unterschiedlich, und Sie sollten bei der Erstellung eines Runbooks die bewährten Methoden für die Verwendung der einzelnen Ströme befolgen.

Die folgende Tabelle stellt eine kurze Beschreibung der einzelnen Streams und ihres Verhaltens im Verwaltungsportal bereit, sowohl beim Ausführen eines veröffentlichten Runbooks als auch beim Testen eines Runbooks. Weitere Details zu jedem Stream werden in den folgenden Abschnitten bereitgestellt.

Stream	Beschreibung	Veröffentlicht	Testen
Output	Objekte, die von anderen Runbooks genutzt werden.	Wird in den Auftragsverlauf geschrieben.	Wird im Testausgabebereich angezeigt.
Warnung	Für den Benutzer vorgesehene Warnmeldung.	Wird in den Auftragsverlauf geschrieben.	Wird im Testausgabebereich angezeigt.
Fehler	Für den Benutzer vorgesehene Fehlermeldung. Anders als bei einer Ausnahme wird das Runbook nach einer Fehlermeldung standardmäßig fortgesetzt.	Wird in den Auftragsverlauf geschrieben.	Wird im Testausgabebereich angezeigt.
Ausführlich	Meldungen mit allgemeinen Informationen oder Informationen zur Fehlerbehebung.	Wird nur in den Auftragsverlauf geschrieben, wenn die ausführliche Protokollierung für das Runbook aktiviert ist.	Wird im Testausgabebereich nur angezeigt, wenn $VerbosePreference im Runbook auf Fortsetzen festgelegt ist.
Status	Datensätze, die automatisch vor und nach jeder Aktivität im Runbook generiert werden. Das Runbook sollte nicht versuchen, seine eigenen Fortschrittsprotokolle zu erstellen, da sie für einen interaktiven Benutzenden gedacht sind.	Wird nur in den Auftragsverlauf geschrieben, wenn die Statusprotokollierung für das Runbook aktiviert ist.	Wird nicht im Testausgabebereich angezeigt.
Debug	Für einen interaktiven Benutzer vorgesehene Meldungen. Sollte nicht in Runbooks verwendet werden.	Wird nicht in den Auftragsverlauf geschrieben.	Wird nicht im Testausgabebereich angezeigt.

Ausgabedatenstrom

Der Ausgabestream ist für die Ausgabe von Objekten vorgesehen, die von einem Workflow erstellt wurden, wenn dieser korrekt abläuft. In Automation wird dieser Stream hauptsächlich für Objekte verwendet, die von übergeordneten Runbooks, die das aktuelle Runbook aufrufen, konsumiert werden sollen. Wenn Sie ein Runbook über ein übergeordnetes Runbook inline aufrufen, werden Daten aus dem Ausgabedatenstrom an das übergeordnete Runbook zurückgegeben. Verwenden Sie den Ausgabedatenstrom nur dann zum Anzeigen allgemeiner Informationen für den Benutzer, wenn Sie wissen, dass das Runbook nie von einem anderen Runbook aufgerufen wird. In der Regel empfiehlt es sich jedoch, den ausführlichen Datenstrom zu verwenden, um allgemeine Informationen für den Benutzer bereitzustellen.

Sie können Daten in den Ausgabedatenstrom schreiben, indem Sie Write-Output verwenden oder das Objekt im Runbook in einer eigenen Zeile platzieren.

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

Ausgabe einer Funktion

Wenn Sie in einer in Ihrem Runbook enthaltenen Funktion in den Ausgabedatenstrom schreiben, wird die Ausgabe an das Runbook zurückgegeben. Wenn das Runbook diese Ausgabe einer Variablen zuweist, wird sie nicht in den Ausgabestream geschrieben. Wenn Sie innerhalb der Funktion in andere Datenströme schreiben, wird die Ausgabe in den entsprechenden Datenstrom für das Runbook geschrieben.

Sehen Sie sich folgendes Beispielrunbook an:

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"
   }
}

Der Ausgabedatenstrom für den Runbookauftrag würde wie folgt aussehen:

Output outside of function

Der ausführliche Datenstrom für den Runbookauftrag würde wie folgt aussehen:

Verbose outside of function
Verbose inside of function

Die Variable $functionOutput würde den Wert haben:

Output inside of function

Deklarieren des Ausgabedatentyps

Ein Workflow kann den Datentyp seiner Ausgabe mit dem OutputType-Attributangeben. Dieses Attribut hat zur Laufzeit keinerlei Auswirkung, gibt dem Runbookautor zur Entwurfszeit aber Auskunft über die erwartete Ausgabe des Runbooks. Mit der Weiterentwicklung des Toolsets für Runbooks wird die Deklaration der Ausgabedatentypen zur Entwurfszeit zunehmend an Bedeutung gewinnen. Daher empfiehlt es sich, diese Deklaration in alle von Ihnen erstellten Runbooks einzuschließen.

Das folgende Beispielrunbook gibt ein Zeichenfolgenobjekt aus und enthält eine Deklaration des Ausgabetyps. Wenn Ihr Runbook ein Array eines bestimmten Typs ausgibt, sollten Sie trotzdem den Typ angeben und kein Array des Typs.

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

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

Nachrichtendatenströme

Im Gegensatz zum Ausgabedatenstrom dienen Nachrichtendatenströme zum Übermitteln von Informationen an den Benutzer. Es gibt mehrere Nachrichtenströme für unterschiedliche Arten von Informationen, und jeder wird von der Automatisierungstechnik unterschiedlich verarbeitet.

Wählen Sie die erforderliche Registerkarte, um mehr über diese Nachrichtenströme zu erfahren:

Warnungs- und Fehlerströme

Die Warnungs- und Fehlerdatenströme dienen zum Protokollieren von Problemen, die in einem Runbook auftreten. Sie werden in den Auftragsverlauf geschrieben, wenn ein Runbook ausgeführt wird, und in den Testausgabebereich im Verwaltungsportal aufgenommen, wenn ein Runbook getestet wird. Standardmäßig wird das Runbook nach einer Warnung oder einem Fehler fortgesetzt. Sie können angeben, dass das Runbook bei einer Warnung oder einem Fehler angehalten werden soll, indem Sie vor dem Erstellen der Meldung eine Einstellungsvariable im Runbook festlegen. Soll ein Runbook beim Auftreten eines Fehlers wie bei einer Ausnahme angehalten werden, legen Sie z.B. $ErrorActionPreference auf „Stop“ fest.

Erstellen Sie mit dem Cmdlet Write-Warning bzw. Write-Error eine Warn- oder Fehlermeldung. Aktivitäten können ebenfalls in diese Datenströme schreiben.

#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."

Ausführlicher Datenstrom

Der ausführliche Nachrichtendatenstrom dient für allgemeine Informationen zu Runbookvorgängen. Da der Debug Stream in einem Runbook nicht zur Verfügung steht, sollten ausführliche Meldungen zur Fehlersuche verwendet werden. Standardmäßig werden ausführliche Meldungen aus veröffentlichten Runbooks nicht im Auftragsverlauf gespeichert. Um ausführliche Nachrichten zu speichern, konfigurieren Sie veröffentlichte Runbooks auf der Registerkarte Konfigurieren des Runbooks im Verwaltungsportal zu Ausführliche Datensätze protokollieren. In den meisten Fällen sollte aus Leistungsgründen die Standardeinstellung (keine Protokollierung ausführlicher Datensätze) für Runbooks beibehalten werden. Aktivieren Sie diese Option nur zum Beheben oder Debuggen eines Runbooks.

Die Variable $VerbosePreference hat standardmäßig den Wert SilentlyContinue. Sie brauchen diese Variable in einem veröffentlichten Runbook nicht zu ändern, damit ausführliche Nachrichten gespeichert werden. Wenn dieser Wert in einem veröffentlichten Runbook jedoch explizit auf SilentlyContinue festgelegt ist, werden ausführliche Nachrichten nicht gespeichert, selbst wenn das Runbook so konfiguriert ist, dass ausführliche Datensätze protokolliert werden.

Beim Testen eines Runbookswerden auch dann keine ausführlichen Meldungen angezeigt, wenn das Runbook zum Protokollieren ausführlicher Datensätze konfiguriert ist. Um beim Testen eines Runbooksausführliche Meldungen anzuzeigen, müssen Sie die $VerbosePreference-Variable auf „Continue“ festlegen. Wenn diese Variable festgelegt ist, werden ausführliche Nachrichten im Testausgabebereich des Verwaltungsportals angezeigt.

Erstellen Sie eine ausführliche Meldung mit dem Cmdlet Write-Verbose .

#The following line creates a verbose message.

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

Debug-Stream

Der Debug-Stream ist für die Verwendung mit einem interaktiven Benutzenden gedacht und sollte nicht in Runbooks verwendet werden.

Statusdatensätze

Wenn Sie ein Runbook so konfigurieren, dass Fortschrittsprotokolle protokolliert werden (auf der Registerkarte Konfigurieren des Runbooks im Verwaltungsportal), wird vor und nach der Ausführung jeder Aktivität ein Datensatz in den Auftragsverlauf geschrieben. In den meisten Fällen sollte zum Maximieren der Leistung die Standardeinstellung (keine Protokollierung von Statusdatensätzen) für Runbooks beibehalten werden. Aktivieren Sie diese Option nur zum Beheben oder Debuggen eines Runbooks. Beim Testen eines Runbook werden Fortschrittsmeldungen nicht angezeigt, selbst wenn das Runbook so konfiguriert ist, dass Fortschrittsdatensätze protokolliert werden.

Das Cmdlet Write-Progress ist in einem Runbook nicht gültig, da es für die Verwendung mit einem interaktiven Benutzenden vorgesehen ist.

Einstellungsvariablen

Windows PowerShell ermittelt anhand von Einstellungsvariablen , wie auf Daten reagiert werden soll, die an verschiedene Ausgabedatenströme gesendet werden. Sie können diese Variablen in einem Runbook festlegen, um zu steuern, wie es auf die in unterschiedliche Datenströme gesendeten Daten reagiert.

In der folgenden Tabelle sind die Einstellungsvariablen, die in Runbooks verwendet werden können, mit ihren gültigen Werten und Standardwerten aufgeführt.

Hinweis

Diese Tabelle enthält nur die Werte, die in einem Runbook gültig sind. Zusätzliche Werte sind für die Einstellungsvariablen gültig, wenn sie in Windows PowerShell außerhalb von Service Management Automation verwendet werden.

Variable	Standardwert	Gültige Werte
WarningPreference	Fortfahren	Beenden Weiter<\br> \SilentlyContinue
ErrorActionPreference	Fortfahren	Beenden Fortfahren SilentlyContinue
VerbosePreference	SilentlyContinue	Beenden Fortfahren SilentlyContinue

In der folgenden Tabelle wird das Verhalten für die in Runbooks zulässigen Einstellungsvariablenwerte beschrieben.

Wert	Verhalten
Fortfahren	Protokolliert die Meldung und setzt die Ausführung des Runbooks fort.
SilentlyContinue	Setzt die Ausführung des Runbooks ohne Protokollierung der Meldung fort. Die Meldung wird ignoriert.
Beenden	Protokolliert die Meldung und hält das Runbook an.

Abrufen der Runbookausgabe und -meldungen

Verwaltungsportal

Sie können die Details eines Runbook-Jobs im Verwaltungsportal auf der Registerkarte Jobs eines Runbooks anzeigen. Die Zusammenfassung des Jobs zeigt die Eingabeparameter und den Ausgabestream an, zusätzlich zu allgemeinen Informationen über den Job und eventuelle Ausnahmen, falls diese aufgetreten sind. Der Verlauf enthält Meldungen aus dem Ausgabedatenstrom, den Warnungs- und Fehlerdatenströmen sowie dem ausführlichen Datenstrom und den Statusdatensätzen, wenn das Runbook zum Protokollieren von ausführlichen Meldungen und Statusdatensätzen konfiguriert ist.

Windows PowerShell

In Windows PowerShell können Sie Ausgaben und Meldungen aus einem Runbook mit dem Cmdlet Get-SmaJobOutput erhalten. Dieses Cmdlet erfordert die ID des Auftrags und hat einen Parameter namens Stream, in dem Sie angeben, welcher Stream zurückgegeben werden soll. Wenn Sie Any angeben, werde alle Datenströme für den Auftrag zurückgegeben.

Im folgenden Beispiel wird ein Beispielrunbook gestartet und anschließend auf seinen Abschluss gewartet. Danach wird der Ausgabedatenstrom aus dem Auftrag abgerufen.

$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

Nächste Schritte

Erstellen von Automation-Runbooks.