Jobs

Jobs sind das Ergebnis der Ausführung eines Skripts. Jobs werden basierend auf den Einstellungen auf Skript- und Serverebene aufbewahrt.

Jobs anzeigen

Jobs können durch Klicken auf die Seite Automatisierung / Jobs angezeigt werden. Klicken Sie auf die Schaltfläche Anzeigen, um zum Job zu navigieren. Laufende Jobs können auch abgebrochen werden.

Job-Liste

Job-Ausgabe anzeigen

Standard-PowerShell-Streams wie Information, Host, Fehler, Warnung und Verbose werden im Ausgabebereich angezeigt.

Job-Stream-Ausgabe

Job-Pipeline-Ausgabe anzeigen

Das Speichern großer Mengen an Pipeline-Ausgaben kann die Leistung negativ beeinflussen. Sie können Pipeline-Ausgaben verwerfen, indem Sie die Einstellung Discard Pipeline für Skripte setzen.

Pipeline-Ausgaben für Jobs werden ebenfalls in PowerShell Universal gespeichert. Jedes Objekt, das in die Pipeline geschrieben wird, wird als CliXml gespeichert und kann auf der Registerkarte Pipeline Output angezeigt werden.

Sie können die Baumansicht erweitern, um die Objekte und Eigenschaften aus der Pipeline zu sehen.

Job-Pipeline-Ausgabe

Fehler anzeigen

Alle in den Fehlerstream geschriebenen Fehler sind auf der Registerkarte Error auf der Job-Seite verfügbar.

Job-Fehlerausgabe

Status

Jobs geben abhängig von der Konfiguration und dem Ergebnis der Ausführung verschiedene Statuswerte zurück. Einstellungen, die den Job-Status beeinflussen können, sind:

• ErrorActionPreference
• WarningActionPreference

Die folgende Tabelle beschreibt, wie PowerShell Universal Statuswerte behandelt.

Status	Beschreibung	Unterdrücken
Error	Ein Skript hatte einen nicht abbrechenden Fehler.	ErrorActionPreference auf SilentlyContinue setzen
Warning	Ein Skript hatte eine Warnung.	WarningActionPreference auf SilentlyContinue setzen
Failed	Ein Skript hatte einen abbrechenden Fehler.	Behandeln Sie den abbrechenden Fehler oder fangen Sie ihn ab.
Waiting on Feedback	Ein Skript wartet auf Feedback, z. B. Read-Host.	Vermeiden Sie Benutzer-Callbacks wie Read-Host.
Running	Das Skript wird derzeit ausgeführt.	N\A
Queued	Das Skript ist derzeit für die Ausführung in der Warteschlange.	N\A

Feedback

Einige Jobs erfordern Feedback. Jedes Skript, das einen Read-Host-Aufruf enthält, wartet, bis eine Benutzerinteraktion mit diesem Job erfolgt. Der Job befindet sich im Status Waiting for Feedback, und Sie können auf dieses Feedback antworten, indem Sie auf der Job-Seite auf die Schaltfläche Response to Feedback klicken.

Job wartet auf Feedback

Um einen SecureString mit einem Passwort-Eingabefeld zu akzeptieren, können Sie den Parameter -AsSecureString von Read-Host verwenden.

Jobs aus PowerShell aufrufen

Sie können Invoke-PSUScript verwenden, um Jobs von der Befehlszeile aus aufzurufen. Dazu benötigen Sie ein gültiges App Token. Parameter werden über dynamische Parameter des Cmdlets Invoke-PSUScript definiert.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello'

Skripte aus Skripten aufrufen

Sie können UA-Skripte auch aus UA-Skripten aufrufen. Wenn Sie einen Job in UA ausführen, müssen Sie kein App Token oder den Computernamen manuell definieren. Diese werden für Sie definiert. Sie können einfach Invoke-PSUScript innerhalb Ihres Skripts aufrufen, um ein anderes Skript zu starten. Beide Jobs werden in der Benutzeroberfläche angezeigt. Wenn Sie warten möchten, bis das Skript abgeschlossen ist, verwenden Sie Wait-PSUJob.

Auf den Abschluss eines Skripts warten

Sie können das Cmdlet Wait-PSUJob verwenden, um auf den Abschluss eines Jobs zu warten. Leiten Sie den Rückgabewert von Invoke-PSUScript per Pipe an Wait-UAJob weiter, um auf den Abschluss des Jobs zu warten. Wait-PSUJob wartet unbegrenzt, sofern nicht der Parameter -Timeout angegeben wird.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Wait-PSUJob

Pipeline-Daten zurückgeben

Sie können das Cmdlet Get-PSUJobPipelineOutput verwenden, um die von einem Job erzeugte Pipeline-Ausgabe zurückzugeben. Diese Pipeline-Ausgabe besteht aus deserialisierten Objekten, die während des Jobs in die Pipeline geschrieben wurden. Sie können auf diese Daten von dort zugreifen, wo Sie Zugriff auf die PowerShell Universal Management-API haben.

Get-PSUJobPipelineOutput -JobId 10

Die Ausgabe des letzten Jobs zurückgeben

Möglicherweise ist es erforderlich, die Ausgabe der letzten Job-Ausführung eines Skripts zurückzugeben. Dazu müssen Sie eine Kombination von Cmdlets verwenden, um das Skript, die ID des letzten Jobs und dann die Pipeline- oder Host-Ausgabe abzurufen.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Gibt die Ausgabe des letzten Jobs als Objekt zurück

Standardmäßig gibt Get-PSUJobOutput die Ausgabe als Zeichenfolge zurück. Um die Ausgabe als Objekt mit Informationen über die Ausgabe zurückzugeben, verwenden Sie -AsObject.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobOutput -Job $Job -AsObject

Ein Skript aufrufen und auf die Ausgabe warten

Sie können den Parameter -Wait von Invoke-PSUScript verwenden, um dies zu erreichen.

$Output = Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' -Wait

Zusätzlich ruft das folgende Beispiel ein Skript auf, speichert das Job-Objekt in einer Variable $job, wartet auf den Abschluss des Jobs und gibt dann die Pipeline- und Host-Ausgabe zurück.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Tee-Object -Variable job | Wait-PSUJob

$Output = Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Integrierter Modus

Der integrierte Modus ermöglicht das Aufrufen dieser Cmdlets innerhalb von PowerShell Universal ohne App Token oder Computernamen. Er verwendet den internen RPC-Kanal zur Kommunikation.

Sie können den Parameter -Integrated setzen, um in den integrierten Modus zu wechseln. Dieser Parameter funktioniert außerhalb von PowerShell Universal nicht.

Invoke-PSUScript -Script 'Script.ps1' -Integrated

Die folgenden Cmdlets unterstützen den integrierten Modus.

• Get-PSUScript
• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Get-PSUJobFeedback
• Set-PSUJobFeedback
• Wait-PSUJob

Jobs mit REST aufrufen

Sie können Jobs über REST mithilfe der Management-API von PowerShell Universal aufrufen. Sie benötigen ein gültiges App Token, um Jobs aufzurufen.

Skripte mit REST aufrufen

Um ein Skript aufzurufen, führen Sie einen HTTP-POST an den Skript-Endpunkt mit der ID des Skripts aus, das Sie ausführen möchten.

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body "" -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Parameter bereitstellen

Sie können dem Job Parameter über eine Abfragezeichenfolge übergeben. Parameter werden Ihrem Skript als Zeichenfolgen bereitgestellt.

$Parameters = @{
    Uri = "http://localhost:5000/api/v1/script/path/PNP.ps1?Server=tester&Domain=test" 
    Method = "POST"
    Headers = @{Authorization = "Bearer $Apptoken"}
    ContentType = 'application/json'
    Body = '{}'
}

Invoke-RestMethod @Parameters

Die Umgebung festlegen

Sie können die Umgebung festlegen, indem Sie die Eigenschaft environment an den Job-Kontext übergeben. Die Eigenschaft muss der Name einer in Ihrer PSU-Instanz definierten Umgebung sein.

$JobContext = @{
    Environment = "PowerShell 7"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Das Run As-Konto festlegen

Sie können das Run As-Konto festlegen, indem Sie den Namen einer PSCredential-Variable an die Eigenschaft Credential übergeben.

$JobContext = @{
    Credential = "MyUser"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Jobs aus Apps aufrufen

Sie können dieselben Cmdlets, die Sie in anderen PowerShell-Skripten verwenden, nutzen, um Skripte in Apps auszuführen. Möglicherweise möchten Sie dabei ein interaktiveres Erlebnis. Unten finden Sie einige Beispiele, wie Sie dies mit dem App-Framework erreichen.

Ausgabe anzeigen

Sie können die Cmdlets Invoke-PSUScript und Get-PSUJobOutput verwenden, um ein UI-Element zu erstellen, das während der Skriptausführung aktualisiert wird. Angenommen, Sie haben ein Skript wie das unten stehende. Es schreibt einfach 100 Mal alle 100 Millisekunden in den Information-Stream.

1..100 | % {
    Write-Output "Hello $_"
    Start-Sleep -Milliseconds 100
}

Innerhalb Ihrer App können Sie das Skript basierend auf einer Benutzerinteraktion starten und dann ein Element aktualisieren, während das Skript ausgeführt wird. Das folgende Beispiel erstellt eine Schaltfläche und ein pre-Tag-Element, das als Ziel für die Ausgabe des Skripts dient. Wenn der Benutzer auf die Schaltfläche klickt, wird der Job gestartet und auf dessen Abschluss gewartet. Innerhalb der Schleife wird die Ausgabe des Skripts abgerufen und anschließend das pre-Element mit dem Ausgabeinhalt aktualisiert.

Schließlich ruft es einen aktualisierten Status des Jobs ab und wartet 100 Millisekunden, bevor es erneut ausgeführt wird.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        $Job = Invoke-PSUScript -Name "AppExample.ps1" -Integrated
        while($Job.Status -eq 'Queued' -or $Job.Status -eq 'Running')
        {
            $Output = Get-PSUJobOutput -Job $Job
            Set-UDElement -Id 'output' -Content {
                $Output | ForEach-Object {
                    $_ +  [Environment]::NewLine
                }
            }
            $Job = Get-PSUJob -Id $Job.Id
            Start-Sleep -Milliseconds 100
        }
    } -ShowLoading

    New-UDElement -Tag 'pre' -Id 'output'
}

Fortschritt anzeigen

Der PowerShell-Host des App-Frameworks verbindet sich automatisch mit Funktionen von PowerShell wie Write-Progress.

Wenn Sie den Parameter -Wait von Invoke-PSUScript verwenden, wird der Fortschritt des Skripts automatisch in einem Dialog in Ihrer App angezeigt. Angenommen, wir haben ein Skript wie unten definiert. Dieses Skript schreibt alle 100 Millisekunden Fortschritt.

1..100 | % {
    Write-Progress -Activity "Working..." -PercentComplete $_
    Start-Sleep -Milliseconds 100
}

Innerhalb unserer App können wir das Skript einfach mit dem Parameter -Wait aufrufen. Wenn der Benutzer auf die Schaltfläche klickt, wird der Fortschritt in der App angezeigt.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

Eingabe anfordern

Der PowerShell-Host des App-Frameworks verbindet sich automatisch mit Funktionen von PowerShell wie Read-Host.

Wenn Sie den Parameter -Wait von Invoke-PSUScript verwenden, wird der Benutzer automatisch zur Eingabe aufgefordert, wenn der Befehl Read-Host auftritt. Angenommen, wir haben ein Skript, das mit Read-Host eine Benutzereingabe anfordert.

Read-Host -Prompt "What should I say?"

Rufen Sie in Ihrer App das Skript einfach mit dem Parameter -Wait auf.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

Der Benutzer wird dann während der Skriptausführung zur Eingabe aufgefordert.

In Jobs definierte Variablen

In Jobs definierte Variablen finden Sie auf der Variablen-Seite.

Job-Ausführungs-ID

Das Standardverhalten von PowerShell Universal besteht darin, Jobs anhand einer automatisch inkrementierenden, auf int64 basierenden ID zu verfolgen. Jedes Mal, wenn ein neuer Job ausgeführt wird, ist die ID des Jobs um eins höher als die des letzten. Aufgrund dieses Verhaltens ist es einfach, andere Job-IDs zu erraten, was potenziell zu einem Sicherheitsrisiko führen kann.

Um dieses Problem zu vermeiden, können Sie die experimentelle Funktion JobRunID aktivieren. Obwohl das System intern weiterhin Jobs mit aufsteigenden numerischen IDs erstellt, können Sie nicht anhand dieser IDs auf Jobs zugreifen. Stattdessen wird ein neues Feld namens RunID verwendet. RunID verwendet für Suchvorgänge eine GUID anstelle einer ID. Dies verringert die Möglichkeit für einen Angreifer, eine Job-ID zu erraten, erheblich.

Sie müssen diese Funktion aktivieren, um sie zu verwenden.

Set-PSUSetting -JobRunId

API

• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobFeedback
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Wait-PSUJob