Dane wyjściowe i komunikaty elementu Runbook

 

Opublikowano: marzec 2016

Dotyczy: Windows Azure Pack for Windows Server, System Center 2012 R2 Orchestrator

Większość elementów Runbook automatyzacji generuje dane wyjściowe w jakieś postaci — na przykład komunikat o błędzie dla użytkownika lub obiekt złożony przeznaczony do użycia przez inny przepływ pracy. Środowisko Windows PowerShell udostępnia wiele strumieni na potrzeby wysyłania danych wyjściowych z przepływu pracy. Program Automatyzacja zarządzania usługami działa z każdym z tych strumieni inaczej, a podczas tworzenia elementu Runbook należy stosować najlepsze rozwiązania w zakresie używania każdego z nich.

W poniższej tabeli przedstawiono krótki opis każdego strumienia i jego zachowanie w Portalu zarządzania zarówno podczas uruchamiania opublikowanego elementu Runbook, jak i podczas testowania elementu Runbook. W kolejnych sekcjach znajdują się dodatkowe informacje na temat każdego strumienia.

Strumień	Opis	Opublikowany	Testowy
Dane wyjściowe	Obiekty, które mają być używane przez inne elementy Runbook.	Zapisywany w historii zadań.	Wyświetlany w okienku danych wyjściowych testu.
Ostrzeżenie	Komunikat ostrzegawczy przeznaczony dla użytkownika.	Zapisywany w historii zadań.	Wyświetlany w okienku danych wyjściowych testu.
Błąd	Komunikat o błędzie przeznaczony dla użytkownika. Inaczej niż w przypadku wyjątku, element Runbook domyślnie kontynuuje pracę po zgłoszeniu komunikatu o błędzie.	Zapisywany w historii zadań.	Wyświetlany w okienku danych wyjściowych testu.
Pełny	Komunikaty z informacjami ogólnymi lub dotyczącymi rozwiązywania problemów.	Zapisywany w historii zadań tylko wtedy, gdy dla elementu Runbook jest włączone rejestrowanie pełne.	Wyświetlany w okienku danych wyjściowych testu tylko wtedy, gdy parametr $VerbosePreference ma ustawioną wartość Continue w elemencie Runbook.
Postęp	Rekordy generowane automatycznie przed każdym działaniem w elemencie Runbook i po nim. Element Runbook nie powinien podejmować próby tworzenia swoich własnych rekordów postępu, ponieważ są one przeznaczone dla użytkownika interaktywnego.	Zapisywany w historii zadań tylko wtedy, gdy dla elementu Runbook jest włączone rejestrowanie postępu.	Nie jest wyświetlany w okienku danych wyjściowych testu.
Debugowanie	Komunikaty przeznaczone dla użytkownika interaktywnego. Nie należy go używać w elementach Runbook.	Nie jest zapisywany w historii zadań.	Nie jest zapisywany w okienku danych wyjściowych testu.

Strumień wyjściowy

Strumień wyjściowy jest przeznaczony dla danych wyjściowych obiektów utworzonych przez poprawnie działający przepływ pracy. W programie Automatyzacja ten strumień jest używany głównie dla obiektów, które mają być używane przez nadrzędne elementy Runbook wywołujące bieżący element Runbook. Gdy element Runbook zostanie wywołany bezpośrednio z kodu nadrzędnego elementu Runbook, to zwróci dane strumienia wyjściowego do nadrzędnego elementu. Strumienia wyjściowego należy używać tylko do przekazywania ogólnych informacji do użytkownika, jeśli wiadomo, że element Runbook nigdy nie zostanie wywołany przez inny element Runbook. Najlepszym rozwiązaniem jest zwykle używanie strumienia Strumień pełny do przekazywania ogólnych informacji do użytkownika.

Możesz zapisać dane do strumienia wyjściowego przy użyciu polecenia Write-Output lub umieszczając obiekt w osobnym wierszu w elemencie Runbook.

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

Dane wyjściowe funkcji

Podczas zapisywania do strumienia wyjściowego w funkcji, która znajduje się w elemencie Runbook, dane wyjściowe są przekazywane z powrotem do elementu Runbook. Jeśli element Runbook przypisuje te dane wyjściowe do zmiennej, wtedy nie są one zapisywane do strumienia wyjściowego. Zapisanie do wszelkich innych strumieni w funkcji spowoduje zapisanie do odpowiedniego strumienia elementu Runbook.

Zapoznaj się z następującym przykładowym elementem Runbook.

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

Odpowiedni strumień wyjściowy dla zadania elementu Runbook:

Output outside of function

Odpowiedni strumień pełny dla zadania elementu Runbook:

Verbose outside of function
Verbose inside of function

Zmienna $functionOutput będzie mieć wartość:

Output inside of function

Deklarowanie typu danych wyjściowych

Przepływ pracy może określić typ swoich danych wyjściowych przy użyciu atrybutu OutputType. Ten atrybut nie ma znaczenia w czasie wykonywania, ale stanowi wskazówkę dla twórcy elementu Runbook podczas projektowania informującą o oczekiwanym typie danych wyjściowych elementu Runbook. Ponieważ zestaw narzędzi dla elementów Runbook jest w dalszym ciągu rozwijany, deklarowanie typów danych wyjściowych w czasie projektowania będzie zyskiwać na znaczeniu. W związku z tym najlepsze rozwiązanie to dołączenie tej deklaracji w każdym tworzonym elemencie Runbook.

Następujący przykładowy element Runbook generuje obiekt ciągu i zawiera deklarację typu jego danych wyjściowych. Jeśli element Runbook generuje tablicę pewnego typu, należy także określić typ, a nie tablicę typu.

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

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

Strumienie komunikatów

W przeciwieństwie do strumienia wyjściowego strumienie komunikatów są przeznaczone do przekazywania informacji do użytkownika. Istnieje wiele strumieni komunikatów dla różnych typów informacji, a program Automatyzacja obsługuje inaczej każdy z nich.

Strumienie ostrzeżeń i błędów

Strumienie ostrzeżeń i błędów są przeznaczone do rejestrowania problemów występujących w elemencie Runbook. Są one zapisywane w historii zadań podczas wykonywania elementu Runbook, a podczas testowania elementu Runbook są umieszczane w okienku danych wyjściowych testu w Portalu zarządzania. Domyślnie element Runbook kontynuuje wykonywanie po ostrzeżeniu lub błędzie. Można określić, że element Runbook ma zostać zawieszony w przypadku ostrzeżenia lub błędu, przez ustawienie zmiennej preferencji w elemencie Runbook przed utworzeniem komunikatu. Na przykład aby spowodować zawieszenie elementu Runbook w przypadku błędu (tak jak w przypadku wyjątku), ustaw dla zmiennej $ErrorActionPreference wartość Stop.

Komunikaty ostrzegawcze lub o błędach tworzy się przy użyciu polecenia cmdlet Write-Warning lub Write-Error. Działania mogą także zapisywać do tych strumieni.

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

Strumień pełny

Strumień komunikatów pełnych jest przeznaczony dla ogólnych informacji o działaniu elementu Runbook. Ponieważ strumień debugowania nie jest dostępny w elemencie Runbook, strumienia pełnego należy używać na potrzeby przekazywania informacji dotyczących rozwiązywania problemów. Domyślnie komunikaty pełne z opublikowanych elementów Runbook nie są zapisywane w historii zadań. Aby zapisywać komunikaty pełne, skonfiguruj opublikowane elementy Runbook pod kątem rejestrowania rekordów pełnych na karcie Konfiguracja elementu Runbook w Portalu zarządzania. W większości przypadków należy pozostawić domyślne ustawienie elementu Runbook (tzn. bez rejestrowania rekordów pełnych) ze względu na wydajność. Włącz tę opcję tylko podczas rozwiązywania problemów z elementem Runbook lub jego debugowania.

Domyślna wartość zmiennej $VerbosePreference to SilentlyContinue. Nie trzeba zmieniać tej zmiennej w opublikowanym elemencie Runbook, aby spowodować zapisywanie komunikatów pełnych. Jeśli ta zmienna zostanie jednak jawnie ustawiona na wartość SilentlyContinue w opublikowanym elemencie Runbook, komunikaty pełne nie będą zapisywane, nawet jeśli element Runbook skonfigurowano pod kątem rejestrowania rekordów pełnych.

Podczas testowania elementu Runbook komunikaty pełne nie są wyświetlane nawet wtedy, gdy element Runbook jest skonfigurowany pod kątem rejestrowania rekordów pełnych. Aby wyświetlić komunikaty pełne podczas testowania elementu Runbook, musisz ustawić dla zmiennej $VerbosePreference wartość Continue. Gdy ta zmienna jest ustawiona, komunikaty pełne są wyświetlane w okienku danych wyjściowych testu Portalu zarządzania.

Komunikat pełny tworzy się za pomocą polecenia cmdlet Write-Verbose.

#The following line creates a verbose message.

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

Strumień debugowania

Strumień debugowania jest przeznaczony dla użytkowników interakcyjnych i nie należy go używać w elementach Runbook.

Rekordy postępu

Jeśli element Runbook zostanie skonfigurowany pod kątem rejestrowania rekordów postępu (na karcie Konfiguracja elementu Runbook w Portalu zarządzania), rekord zostanie zapisany w historii zadań przed każdym uruchomieniem działania i po nim. W większości przypadków należy zachować domyślne ustawienie elementu Runbook (tzn. bez rejestrowania rekordów postępu), aby zwiększyć wydajność. Włącz tę opcję tylko podczas rozwiązywania problemów z elementem Runbook lub jego debugowania. Podczas testowania elementu Runbook komunikaty o postępie nie są wyświetlane nawet wtedy, gdy element Runbook jest skonfigurowany pod kątem rejestrowania rekordów postępu.

Polecenie cmdlet Write-Progress jest nieprawidłowe w elemencie Runbook, ponieważ jest przeznaczone dla użytkownika interaktywnego.

Zmienne preferencji

Środowisko Windows PowerShell korzysta ze zmiennych preferencji do określenia, jak odpowiedzieć na dane wysyłane do różnych strumieni wyjściowych. Te zmienne możesz ustawić w elemencie Runbook, aby kontrolować sposób odpowiadania przez niego na dane przesyłane do różnych strumieni.

W poniższej tabeli przedstawiono zmienne preferencji, których można użyć w elementach Runbook, oraz ich prawidłowe i domyślne wartości. Zwróć uwagę na to, że tabela zawiera tylko wartości, które są prawidłowe w elemencie Runbook. Dodatkowe wartości są prawidłowe dla zmiennych preferencji, gdy są używane w środowisku Windows PowerShell poza programem Automatyzacja zarządzania usługami.

Zmienna	Wartość domyślna	Prawidłowe wartości
WarningPreference	Continue	Stop Continue SilentlyContinue
ErrorActionPreference	Continue	Stop Continue SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continue SilentlyContinue

W poniższej tabeli przedstawiono zachowania dla wartości zmiennych preferencji, które są prawidłowe w elementach Runbook.

Wartość	Zachowanie
Continue	Rejestruje komunikat i kontynuuje wykonywanie elementu Runbook.
SilentlyContinue	Kontynuuje wykonywanie elementu Runbook bez rejestrowania komunikatu. To powoduje zignorowanie komunikatu.
Stop	Rejestruje komunikat i zawiesza element Runbook.

Pobieranie danych wyjściowych i komunikatów elementu Runbook

Portal zarządzania

Szczegóły zadania elementu Runbook możesz wyświetlić w Portalu zarządzania — na karcie Zadania elementu Runbook. Karta Podsumowanie zawiera parametry wejściowe i strumień Strumień wyjściowy, a także ogólne informacje o zadaniu i wszystkie zgłoszone wyjątki, jeśli takie były. Karta Historia zawiera komunikaty ze strumienia wyjściowego i strumieni Strumienie ostrzeżeń i błędów, a także strumień Strumień pełny i rekordy Rekordy postępu, jeśli element Runbook jest skonfigurowany pod kątem rejestrowania rekordów pełnych i postępu.

Windows PowerShell

W środowisku Windows PowerShell można pobrać dane wyjściowe i komunikaty z elementu Runbook za pomocą polecenia cmdlet Get-SmaJobOutput. To polecenie cmdlet wymaga identyfikatora zadania i ma parametr o nazwie Stream, za pomocą którego należy określić strumień do zwrócenia. Możesz określić wartość Any, aby spowodować zwrócenie wszystkich strumieni zadania.

W poniższym przykładzie jest uruchamiany przykładowy element Runbook, a następnie kod czeka na jego zakończenie. Po zakończeniu jego strumień wyjściowy jest zbierany z zadania.

$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

Zobacz też

Rozszerzanie struktury Automatyzacja zarządzania usługami za pomocą elementów Runbook
Runbook Authoring