Runbookausgabe und -meldungen

Wichtig

Diese Version von Service Management Automation (SMA) hat das Supportende erreicht. Sie sollten ein Upgrade auf SMA 2019 durchführen.

Die meisten Automatisierungsrunbooks verfügen über eine Form der Ausgabe, z. B. eine Fehlermeldung an den Benutzer oder ein komplexes Objekt, das von einem anderen Workflow verwendet werden soll. Windows PowerShell bietet mehrere Streams zum Senden der Ausgabe aus einem Workflow. Service Management Automation funktioniert mit jedem dieser Datenströme unterschiedlich, und Sie sollten die bewährten Methoden für die Verwendung der einzelnen Datenströme befolgen, wenn Sie ein Runbook erstellen.

Die folgende Tabelle enthält eine kurze Beschreibung der einzelnen Streams und des Verhaltens im Verwaltungsportal beim Ausführen eines veröffentlichten Runbooks und beim Testen eines Runbooks. Ausführlichere Informationen zu den verschiedenen Datenströmen finden Sie in den nachfolgenden Abschnitten.

STREAM BESCHREIBUNG Veröffentlicht Test
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, die grundlegende oder Informationen zur Problembehandlung enthalten. Wird nur in den Auftragsverlauf geschrieben, wenn die ausführliche Protokollierung für das Runbook aktiviert ist. Wird nur im Testausgabebereich angezeigt, wenn $VerbosePreference im Runbook auf Continue festgelegt ist.
Status Datensätze, die automatisch vor und nach jeder Aktivität im Runbook generiert werden. Das Runbook sollte nicht versuchen, eigene Statusdatensätze zu erstellen, da diese für einen interaktiven Benutzer vorgesehen sind. Wird nur in den Auftragsverlauf geschrieben, wenn die Statusprotokollierung für das Runbook aktiviert ist. Wird nicht im Testausgabebereich angezeigt.
Debuggen 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 dient für die Ausgabe von Objekten, die bei ordnungsgemäßer Ausführung von einem Workflow erstellt werden. In Automation wird dieser Stream hauptsächlich für Objekte verwendet, die von übergeordneten Runbooks verwendet werden sollen, die das aktuelle Runbook aufrufen. Wenn Sie ein Runbook inline aus einem übergeordneten Runbook aufrufen, gibt es Daten aus dem Ausgabestream an das übergeordnete Runbook zurück. 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. Weist das Runbook diese Ausgabe einer Variablen zu, wird sie nicht in den Ausgabedatenstrom 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 $functionOutput-Variable würde den folgenden Wert aufweisen:

Output inside of fuction

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 Nachrichtenstreams für verschiedene Arten von Informationen, die von Automation unterschiedlich verarbeitet werden.

Warnungs- und Fehlerdatenströme

Die Warnungs- und Fehlerdatenströme dienen zum Protokollieren von Problemen, die in einem Runbook auftreten. Sie werden bei Ausführung eines Runbooks im Auftragsverlauf erfasst und sind beim Testen eines Runbooks im Testausgabebereich im Verwaltungsportal enthalten. 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 eine Preference-Variable im Runbook vor dem Erstellen der Meldung festlegen. Damit z. B. ein Runbook bei einem Fehler angehalten wird, wie es sonst bei einer Ausnahme der Fall wäre, legen Sie "$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 Debugstream in einem Runbook nicht verfügbar ist, sollten ausführliche Meldungen für Informationen zur Problembehandlung verwendet werden. Standardmäßig werden ausführliche Meldungen von veröffentlichten Runbooks nicht im Auftragsverlauf gespeichert. Wählen Sie zum Speichern von ausführlichen Meldungen Ausführliche Datensätze protokollieren auf der Registerkarte Konfigurieren des Runbooks im Verwaltungsportal. 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 $VerbosePreference-Variable weist standardmäßig den Wert SilentlyContinueauf. Sie müssen diese Variable in einem veröffentlichten Runbook nicht ändern, um ausführliche Meldungen zu speichern. Wenn dieser Wert jedoch explizit auf SilentlyContinue in einem veröffentlichten Runbook festgelegt ist, werden ausführliche Meldungen nicht gespeichert, selbst wenn das Runbook zum Protokollieren von ausführlichen Datensätzen konfiguriert ist.

Wenn Sie ein Runbook testen, werden ausführliche Meldungen auch dann nicht angezeigt, wenn das Runbook für die Protokollierung ausführlicher Datensätze konfiguriert ist. Um ausführliche Meldungen werden des Testens eines Runbooks anzuzeigen, müssen Sie die Variable "$VerbosePreference" auf Continue festlegen. Wenn diese Variable festgelegt ist, werden ausführliche Meldungen 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."

Debugdatenstrom

Der Debugdatenstrom dient zur Verwendung mit einem interaktiven Benutzer und sollte nicht in Runbooks benutzt werden.

Statusdatensätze

Wenn Sie ein Runbook zur Protokollierung von Statuseinträgen konfigurieren (auf der Registerkarte Konfigurieren des Runbooks im Verwaltungsportal), wird ein Datensatz im Auftragsverlauf vor und nach Ausführung jeder Aktivität erfasst. 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 Runbooks werden auch dann keine Statusmeldungen angezeigt, wenn das Runbook zum Protokollieren von Statusdatensätzen konfiguriert ist.

Das Cmdlet Write-Progress ist in einem Runbook ungültig, da es zur Verwendung mit einem interaktiven Benutzer 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. Beachten Sie, dass diese Tabelle nur die Werte enthält, die in einem Runbook zulässig 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 Continue Beenden
Continue
SilentlyContinue
ErrorActionPreference Continue Beenden
Continue
SilentlyContinue
VerbosePreference SilentlyContinue Beenden
Continue
SilentlyContinue

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

Wert Verhalten
Continue 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 von Ausgabe und Nachrichten eines Runbooks

Verwaltungsportal

Detaillierte Informationen zu einem Runbookauftrag können im Verwaltungsportal aus der Registerkarte Aufträge eines Runbooks angezeigt werden. In der Zusammenfassung des Auftrags werden die Eingabeparameter und der Ausgabestream sowie allgemeine Informationen zum Auftrag und ggf. aufgetretene Ausnahmen angezeigt. Der Verlauf enthält Meldungen aus dem Ausgabestream sowie Warnungs- und Fehler-Streams zusätzlich zu den ausführlichen Datenstrom- und Statusdatensätzen, wenn das Runbook so konfiguriert ist, dass ausführliche und Statusdatensätze protokolliert werden.

Windows PowerShell

In Windows PowerShell können Sie die Ausgabe und Nachrichten aus einem Runbook mit dem Get-SmaJobOutput -Cmdlet abrufen. Dieses Cmdlet erfordert die ID des Auftrags und verfügt über einen Parameter namens Stream, mit dem Sie angeben, welcher Stream zurückgegeben werden soll. Sie können Any angeben, um alle Streams für den Auftrag zurückzugeben.

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