Teilen über

Runbookausgabe und Meldungen

  • Artikel

Die meisten Automatisierungsrunbooks haben eine Form der Ausgabe, z. B. eine Fehlermeldung für den Benutzer oder ein komplexes Objekt, das von einem anderen Workflow genutzt werden soll. Windows PowerShell stellt mehrere Datenströme zum Senden der Ausgabe aus einem Workflow bereit. Die Dienstverwaltungsautomatisierung funktioniert mit jedem dieser Datenströme unterschiedlich, und Sie sollten bewährte 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 Datenströme und deren Verhalten im Verwaltungsportal sowohl beim Ausführen eines veröffentlichten Runbook als auch beim Testen eines Runbook. Weitere Details zu den einzelnen Datenströmen sind in den nachfolgenden Abschnitten angegeben.

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 Nachrichten, die allgemeine oder Problembehandlungsinformationen bereitstellen. Wird nur in den Auftragsverlauf geschrieben, wenn die ausführliche Protokollierung für das Runbook aktiviert ist. Wird im Bereich "Ausgabe testen" nur angezeigt, wenn $VerbosePreference im Runbook auf "Weiter" festgelegt ist.
Status Datensätze, die automatisch vor und nach jeder Aktivität im Runbook generiert werden. Das Runbook sollte nicht versuchen, eigene Fortschrittsdatensätze zu erstellen, da sie 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.
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 Ausgabedatenstrom ist für die Ausgabe von Objekten vorgesehen, die von einem Workflow erstellt wurden, wenn er ordnungsgemäß ausgeführt wird. In der Automatisierung wird dieser Datenstrom in erster Linie für Objekte verwendet, die von übergeordneten Runbooks verwendet werden sollen, die das aktuelle Runbook aufrufen. 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 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 variable $functionOutput hätte den Wert:

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 Informationsarten, und jede wird durch Automatisierung unterschiedlich behandelt.

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

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 im Bereich "Ausgabe testen" im Verwaltungsportal enthalten ist, 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."

Statusdatensätze

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

Das Cmdlet "Write-Progress " ist in einem Runbook nicht gültig, da es für die 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.

Hinweis

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

Variable Standardwert Gültige Werte
WarningPreference Fortfahren Beenden
Fortfahren
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 Runbook-Ausgabe und -Nachrichten

Verwaltungsportal

Sie können die Details eines Runbookauftrags im Verwaltungsportal auf der Registerkarte "Aufträge " eines Runbook anzeigen. Die Zusammenfassung des Auftrags zeigt die Eingabeparameter und den Ausgabedatenstrom zusätzlich zu allgemeinen Informationen zum Auftrag und ausnahmen an, wenn sie 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 Ausgabe und Nachrichten aus einem Runbook mithilfe des Cmdlets Get-SmaJobOutput abrufen. Dieses Cmdlet erfordert die ID des Auftrags und verfügt über einen Parameter namens Stream , in dem Sie angeben, welcher Datenstrom 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 Automatisierungsrunbooks.