Delen via

Runbookuitvoer en -berichten

  • Artikel

Belangrijk

Deze versie van Service Management Automation (SMA) heeft het einde van de ondersteuning bereikt. U wordt aangeraden een upgrade uit te voeren naar SMA 2022.

De meeste automation-runbooks hebben een vorm van uitvoer, zoals een foutbericht voor de gebruiker of een complex object dat is bedoeld om te worden gebruikt door een andere werkstroom. Windows PowerShell biedt meerdere stromen voor het verzenden van uitvoer vanuit een werkstroom. Service Management Automation werkt met elk van deze streams op een andere manier en u moet de aanbevolen procedures volgen voor het gebruik van deze stromen wanneer u een runbook maakt.

De volgende tabel bevat een korte beschrijving van elk van de streams en hun gedrag in de beheerportal, zowel bij het uitvoeren van een gepubliceerd runbook als bij het testen van een runbook. Meer informatie over elke stream vindt u in de volgende secties.

Stream Description Gepubliceerd Testen
Uitvoer Objecten die zijn bedoeld om te worden verbruikt door andere runbooks. Wordt naar de taakgeschiedenis geschreven. Wordt in het deelvenster Testuitvoer weergegeven.
Waarschuwing Waarschuwingsbericht bedoeld voor de gebruiker. Wordt naar de taakgeschiedenis geschreven. Wordt in het deelvenster Testuitvoer weergegeven.
Fout Foutbericht bedoeld voor de gebruiker. Het runbook blijft standaard doorgaan na een foutbericht, wat niet het geval is na een uitzondering. Wordt naar de taakgeschiedenis geschreven. Wordt in het deelvenster Testuitvoer weergegeven.
Uitgebreid Berichten waarin algemene informatie of probleemoplossingsinformatie wordt verstrekt. Wordt alleen naar de taakgeschiedenis geschreven als uitgebreide logboekregistratie is ingeschakeld voor het runbook. Alleen weergegeven in het deelvenster Testuitvoer als $VerbosePreference is ingesteld op Doorgaan in het runbook.
Voortgang Records die automatisch worden gegenereerd voor en na elke activiteit in het runbook. Het runbook mag niet proberen zijn eigen voortgangsrecords te maken, omdat deze zijn bedoeld voor een interactieve gebruiker. Wordt alleen naar de taakgeschiedenis geschreven als voortgangslogboekregistratie is ingeschakeld voor het runbook. Wordt niet in het deelvenster Testuitvoer weergegeven.
Fouten opsporen Berichten die zijn bedoeld voor een interactieve gebruiker. Mag niet worden gebruikt in runbooks. Worden niet naar taakgeschiedenis geschreven. Worden niet naar het deelvenster Testuitvoer geschreven.

Uitvoerstroom

De uitvoerstroom is bedoeld voor de uitvoer van objecten die zijn gemaakt door een werkstroom wanneer deze correct wordt uitgevoerd. In Automation wordt deze stroom voornamelijk gebruikt voor objecten die zijn bedoeld om te worden gebruikt door bovenliggende runbooks die het huidige runbook aanroepen. Wanneer u een runbook inline aanroept vanuit een bovenliggend runbook, worden gegevens van de uitvoerstroom naar het bovenliggende runbook geretourneerd. Gebruik de uitvoerstroom alleen om algemene informatie terug naar de gebruiker te communiceren als u weet dat het runbook nooit door een ander runbook zal worden aangeroepen. Als best practice moet u echter meestal de uitgebreide Stream gebruiken om algemene informatie aan de gebruiker te communiceren.

U kunt gegevens naar de uitvoerstroom schrijven met behulp van Write-Output of door het object op een eigen regel in het runbook te plaatsen.

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

Uitvoer van een functie

Wanneer u schrijft naar de uitvoerstroom in een functie die in uw runbook is opgenomen, wordt de uitvoer terug naar het runbook doorgegeven. Als het runbook die uitvoer toewijst aan een variabele, wordt deze niet naar de uitvoerstroom geschreven. Schrijven naar andere stromen vanuit de functie, heeft tot gevolg dat er naar de bijbehorende stroom voor het runbook wordt geschreven.

Bekijk het volgende voorbeeldrunbook.

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

De uitvoerstroom voor de runbooktaak zou als volgt zijn:

Output outside of function

De uitgebreide stroom voor de runbooktaak zou als volgt zijn:

Verbose outside of function
Verbose inside of function

De variabele $functionOutput heeft dan de waarde:

Output inside of function

Uitvoergegevenstype declareren

Een werkstroom kan het gegevenstype van de uitvoer opgeven met behulp van het kenmerk OutputType. Dit kenmerk heeft geen effect tijdens runtime, maar het geeft de auteur van het runbook een aanwijzing bij het ontwerpen van de verwachte uitvoer van het runbook. Aangezien de toolset voor runbooks zich blijft ontwikkelen, zal het declareren van uitvoergegevenstypen in de ontwerpfase steeds belangrijker worden. Daarom is het een best practice om deze declaratie op te nemen in alle runbooks die u maakt.

Het volgende voorbeeldrunbook voert een tekenreeksobject uit en bevat een declaratie van het uitvoertype. Als uw runbook een matrix van een bepaald type uitvoert, moet u nog steeds het type opgeven in tegenstelling tot een matrix van het type.

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

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

Berichtstromen

In tegenstelling tot de uitvoerstroom zijn berichtstromen bedoeld om informatie naar de gebruiker te communiceren. Er zijn meerdere berichtstromen voor verschillende soorten informatie en elke stroom wordt anders verwerkt door Automation.

Selecteer het vereiste tabblad voor meer informatie over deze berichtstromen:

De waarschuwings- en foutstromen zijn bedoeld om problemen die zich in een runbook voordoen, in een logboek te registreren. Ze worden naar de taakgeschiedenis geschreven wanneer een runbook wordt uitgevoerd en worden opgenomen in het deelvenster Testuitvoer in de beheerportal wanneer een runbook wordt getest. Het runbook blijft standaard in uitvoering na een waarschuwing of fout. U kunt opgeven dat het runbook moet worden onderbroken bij een waarschuwing of fout door een voorkeursvariabele in het runbook in te stellen voordat het bericht wordt gemaakt. Stel bijvoorbeeld $ErrorActionPreference in op Stoppen om ervoor te zorgen dat een runbook wordt onderbroken bij een fout, net als bij een uitzondering.

Maak een waarschuwing of foutbericht met behulp van de cmdlet Write-Warning of Write-Error . Activiteiten mogen ook naar deze stromen schrijven.

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

Voortgangsrecords

Als u een runbook configureert om voortgangsrecords te registreren (op het tabblad Configureren van het runbook in de beheerportal), wordt er een record naar de taakgeschiedenis geschreven voor en nadat elke activiteit is uitgevoerd. In de meeste gevallen moet u de standaardinstelling voor het niet registreren van voortgangsrecords voor een runbook behouden om de prestaties te maximaliseren. Schakel deze optie alleen in voor probleemoplossing of foutopsporing van een runbook. Bij het testen van een runbook worden voortgangsberichten niet weergegeven, zelfs niet als het runbook is geconfigureerd om voortgangsrecords te registreren.

De cmdlet Write-Progress is niet geldig in een runbook omdat deze is bedoeld voor gebruik met een interactieve gebruiker.

Voorkeursvariabelen

Windows PowerShell gebruikt voorkeursvariabelen om te bepalen hoe moet worden gereageerd op gegevens die naar verschillende uitvoerstromen worden verzonden. U kunt deze variabelen in een runbook instellen om te bepalen hoe het runbook reageert op gegevens die worden verzonden naar verschillende stromen.

De volgende tabel bevat een opsomming van de voorkeursvariabelen die kunnen worden gebruikt in runbooks met hun geldige waarden en hun standaardwaarden.

Notitie

Deze tabel bevat alleen de waarden die geldig zijn in een runbook. Aanvullende waarden zijn geldig voor de voorkeursvariabelen wanneer ze worden gebruikt in Windows PowerShell buiten Service Management Automation.

Variabele Standaardwaarde Geldige waarden
WarningPreference Doorgaan Stoppen
Doorgaan
SilentlyContinue
ErrorActionPreference Doorgaan Stoppen
Doorgaan
SilentlyContinue
VerbosePreference SilentlyContinue Stoppen
Doorgaan
SilentlyContinue

De volgende tabel bevat een opsomming van de werking van de voorkeursvariabelewaarden die geldig zijn in runbooks.

Waarde Gedrag
Doorgaan Registreert het bericht en blijft het runbook uitvoeren.
SilentlyContinue Blijft het runbook uitvoeren zonder het bericht te registreren. Dit heeft tot gevolg dat het bericht wordt genegeerd.
Stoppen Het bericht wordt geregistreerd en het runbook wordt onderbroken.

Runbookuitvoer en -berichten ophalen

Beheerportal

U kunt de details van een runbooktaak bekijken in de beheerportal op het tabblad Taken van een runbook. In de samenvatting van de taak worden de invoerparameters en de uitvoer Stream weergegeven, naast algemene informatie over de taak en eventuele uitzonderingen als deze zich hebben voorgedaan. De geschiedenis bevat berichten van de uitvoer-Stream en waarschuwings- en foutstromen, naast de uitgebreide Stream en voortgangsrecords als het runbook is geconfigureerd voor logboekregistratie en voortgangsrecords.

Windows PowerShell

In Windows PowerShell kunt u uitvoer en berichten van een runbook ophalen met behulp van de cmdlet Get-SmaJobOutput. Deze cmdlet vereist de id van de taak en heeft een parameter met de naam Stream waarin u opgeeft welke stream moet worden geretourneerd. U kunt Any opgeven om alle stromen voor de taak te retourneren.

In het volgende voorbeeld wordt een voorbeeldrunbook gestart en wordt gewacht tot dit is voltooid. Zodra het is voltooid, wordt de uitvoerstroom van de taak verzameld.

$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

Volgende stappen

Automatiseringsrunbooks maken.