Messaggi e output del runbook

La maggior parte dei runbook di automazione avrà una forma di output, ad esempio un messaggio di errore per l'utente o un oggetto complesso che deve essere utilizzato da un altro flusso di lavoro. Windows PowerShell fornisce più flussi per inviare un output da un flusso di lavoro. Service Management Automation funziona in modo diverso con ognuno di questi flussi ed è consigliabile seguire le procedure ottimali per l'uso di ciascun flusso durante la creazione di un runbook.

La tabella seguente fornisce una breve descrizione di ognuno dei flussi e del relativo comportamento nel portale di gestione sia per l'esecuzione di un Runbook pubblicato che per il test di un Runbook. Altre informazioni su ogni flusso sono disponibili nelle sezioni successive.

Streaming	Descrizione	Pubblicato	Prova
Risultato	Oggetti destinati a essere utilizzati da altri runbook.	Scritto nella cronologia dei lavori.	Visualizzata nel pannello di output del test.
Avviso	Messaggio di avviso destinato all'utente.	Registrato nella cronologia dei lavori.	Visualizzata nel pannello di output del test.
Errore	Messaggio di errore previsto per l'utente. A differenza di un'eccezione, per impostazione predefinita, il runbook continua dopo un messaggio di errore.	Scritto nella cronologia delle attività.	Visualizzata nel pannello di uscita del test.
Verbose	Messaggi che forniscono informazioni generali o relativi alla risoluzione dei problemi.	Scritto nella cronologia del processo solo se viene attivata la registrazione dettagliata per il runbook.	Viene visualizzato nel riquadro di output del test solo se $VerbosePreference è impostato su Continue nel Runbook.
Avanzamento	Le registrazioni sono generate automaticamente prima e dopo ogni attività del runbook. Il runbook non dovrebbe tentare di creare le proprie registrazioni di avanzamento, perché sono destinate a un utente interattivo.	Scritti nella cronologia delle attività solo se la registrazione dei progressi è attivata per il runbook.	Non viene visualizzato nel pannello di output del test.
Risoluzione dei problemi	Messaggi destinati a un utente interattivo. Non dovrebbero essere utilizzati nei runbook.	Non scritti nella cronologia del lavoro.	Non scritti nel pannello di output del test.

Flusso di output

Il flusso di output è destinato all'output degli oggetti creati da un flusso di lavoro quando viene eseguito correttamente. In Automazione questo flusso viene usato principalmente per gli oggetti che devono essere utilizzati dai runbook padre che chiamano il runbook corrente. Quando chiami un runbook inline da un runbook padre, restituisce i dati dal flusso di output al runbook padre. Si dovrebbe utilizzare solo il flusso di output per comunicare informazioni generali all'utente se si è certi del fatto che il runbook non verrà mai chiamato da un altro runbook. Come procedura consigliata, tuttavia, è consigliabile in genere utilizzare il Flusso dettagliato per comunicare informazioni generali all'utente.

È possibile scrivere i dati per il flusso di output tramite Write-Output o inserendo l'oggetto nella relativa riga nel runbook.

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

Risultato da una funzione

Quando si scrive nel flusso di output in una funzione inclusa nel runbook, l'output viene passato nuovamente al runbook. Se il runbook assegna tale output a una variabile, esso non viene scritto nel flusso di output. Scrivere in altri flussi dall'interno della funzione scriverà nel flusso corrispondente per il runbook.

Si consideri il seguente esempio di manuale operativo.

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

Il flusso di output per l'attività di runbook sarà:

Output outside of function

Il flusso dettagliato per l'attività del runbook sarebbe:

Verbose outside of function
Verbose inside of function

Il valore della variabile $functionOutput sarà:

Output inside of function

Dichiarare il tipo di dati di output

Un flusso di lavoro può specificare il tipo di dati del relativo output utilizzando l’ attributo OutputType. Questo attributo non ha alcun effetto in fase di esecuzione, ma offre un'indicazione all'autore del runbook in fase di progettazione dell’output previsto del runbook. Man mano che il set di strumenti per i runbook continuano ad evolvere, l'importanza della dichiarazione dei tipi di dati di output in fase di progettazione aumenterà. Di conseguenza è consigliabile includere questa dichiarazione in qualsiasi runbook creato.

Il runbook di esempio seguente restituisce un oggetto string e include una dichiarazione del tipo di output. Se il runbook restituisce una matrice di un determinato tipo, è comunque necessario specificare il tipo invece di una matrice del tipo.

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

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

Flussi di messaggi

A differenza del flusso di output, i flussi di messaggi sono utili per comunicare informazioni all'utente. Esistono più flussi di messaggi per diversi tipi di informazioni e ognuno viene gestito in modo diverso dall'automazione.

Selezionare la scheda necessaria per saperne di più su questi flussi di messaggi:

Flussi di avviso e di errore

I flussi di errore e di avviso sono utili per registrare i problemi che si verificano in un runbook. Vengono scritti nella cronologia dei processi quando viene eseguito un runbook e sono inclusi nel riquadro di output del test nel portale di gestione quando un runbook viene testato. Per impostazione predefinita, il runbook continuerà l'esecuzione dopo un avviso o un errore. È possibile specificare che il runbook deve essere sospeso su un avviso o un errore impostando una variabile di preferenza nel runbook prima di creare il messaggio. Ad esempio, per far sì che un runbook venga sospeso in caso di errore come farebbe un'eccezione, impostare $ErrorActionPreference su Stop.

Creare un avviso o un messaggio di errore usando il cmdlet Write-Warning o Write-Error. Anche le attività possono scrivere in questi flussi.

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

Flusso dettagliato

Il flusso del messaggio verboso è destinato a fornire informazioni generali sull'operazione del runbook. Poiché il flusso di debug non è disponibile in un runbook, è consigliabile usare i messaggi dettagliati per la risoluzione dei problemi. Per impostazione predefinita, i messaggi dettagliati dei runbook pubblicati non verranno archiviati nella cronologia dei processi. Per archiviare i messaggi verbosi, configurare i Runbook pubblicati per Registrare record verbosi nella scheda Configura del Runbook nel portale di gestione. Nella maggior parte dei casi, è consigliabile mantenere l'impostazione predefinita che non registra record dettagliati per un runbook per motivi di prestazioni. Attivare questa opzione solo per risolvere i problemi o eseguire il debug di un runbook.

Il valore predefinito della variabile $VerbosePreference è SilentlyContinue. Non è necessario modificare questa variabile in un runbook pubblicato per memorizzare i messaggi verbosi. Se questo valore è impostato in modo esplicito su SilentlyContinue in un runbook pubblicato, tuttavia, i messaggi dettagliati non verranno archiviati anche se il runbook è configurato per registrare record dettagliati.

Quando si esegue il test di un runbook i messaggi dettagliati non vengono visualizzati, anche se il runbook è configurato per registrare i record dettagliati. Per visualizzare i messaggi dettagliati durante il test di un runbook, è necessario impostare la variabile $VerbosePreference su Continue. Con l'impostazione di tale variabile, i messaggi dettagliati verranno visualizzati nel pannello di output dei test del portale di gestione.

Creare un messaggio verboso utilizzando il cmdlet Write-Verbose.

#The following line creates a verbose message.

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

Flusso di debug

Il flusso di debug è destinato all'uso con un utente interattivo e non deve essere usato nei runbook.

Registri di progresso

Se si configura un runbook per la registrazione dei record di avanzamento (nella scheda Configura del runbook nel portale di gestione), verrà scritto un record nella cronologia del processo prima e dopo l'esecuzione di ogni attività. Nella maggior parte dei casi, è consigliabile mantenere l'impostazione predefinita di non registrare i record di avanzamento per un runbook, al fine di massimizzare le prestazioni. Attivare questa opzione solo per risolvere i problemi o eseguire il debug di un runbook. Durante il test di un runbook, i messaggi di stato non vengono visualizzati anche se il runbook è configurato per registrare i record di stato.

Il cmdlet Write-Progress non è valido in un runbook perché è destinato all'uso con un utente interattivo.

Variabili di preferenza

Windows PowerShell utilizza le variabili di preferenza per stabilire come rispondere ai dati inviati ai diversi flussi di output. È possibile impostare queste variabili in un runbook per controllare la modalità di risposta ai dati inviati in diversi flussi.

La tabella seguente elenca le variabili di preferenza che possono essere utilizzate nei runbook con i relativi valori validi e predefiniti.

Nota

Queste tabelle includono solo i valori validi in un runbook. I valori aggiuntivi sono validi per le variabili di preferenza quando vengono usate in Windows PowerShell all'esterno di Service Management Automation.

Variabile	Valore predefinito	Valori validi
PreferenzaAvviso	Continua	Ferma Continua<\br> \SilentlyContinue
ErrorActionPreference	Continua	Stop Continua SilentlyContinue
VerbosePreference	ProseguiSilenziosamente	Fermati Continua SilentlyContinue

Nella tabella seguente è elencato il comportamento dei valori delle variabili di preferenza valide nei runbook.

Valore	Comportamento
Continua	Registra il messaggio e prosegue con l'esecuzione del runbook.
ContinuareSilenziosamente	Continua l'esecuzione del runbook senza registrare il messaggio. Questo ha l'effetto di ignorare il messaggio.
Fermati	Registra il messaggio e sospende il runbook.

Recupero dell'output e dei messaggi del Runbook

Portale di gestione

È possibile visualizzare i dettagli di un processo del Runbook nel portale di gestione dalla scheda Processi di un Runbook. Il Riepilogo del processo visualizzerà i parametri di input e il Output Stream oltre alle informazioni generali sul processo e alle eventuali eccezioni, nel caso in cui si siano verificate. La cronologia includerà i messaggi dal flusso di output e dai flussi di avviso ed errore, oltre al flusso dettagliato e ai record di avanzamento, se il runbook è configurato per registrare sia i record dettagliati che quelli di avanzamento.

Windows PowerShell

In Windows PowerShell è possibile recuperare i messaggi e l'output di un Runbook con il cmdlet Get-SmaJobOutput . Questo cmdlet richiede l'ID del processo e contiene un parametro denominato Stream che consente di specificare il flusso da restituire. È possibile specificare Any per restituire tutti i flussi per il processo.

Nell'esempio seguente viene avviato un runbook di esempio e si attende il suo completamento. Una volta completato, il relativo output viene raccolto dal processo.

$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

Passaggi successivi

Redigere runbook di automazione.