Freigeben über


Receive-Job

Ruft die Ergebnisse der PowerShell-Hintergrundaufträge in der aktuellen Sitzung ab.

Syntax

Receive-Job
       [-Job] <Job[]>
       [[-Location] <string[]>]
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]
Receive-Job
       [-Job] <Job[]>
       [[-ComputerName] <string[]>]
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]
Receive-Job
       [-Job] <Job[]>
       [[-Session] <PSSession[]>]
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]
Receive-Job
       [-Name] <string[]>
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]
Receive-Job
       [-InstanceId] <guid[]>
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]
Receive-Job
       [-Id] <int[]>
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [<CommonParameters>]

Beschreibung

Das Receive-Job Cmdlet ruft die Ergebnisse von PowerShell-Hintergrundaufträgen ab, z. B. die, die mit dem Start-Job Cmdlet oder dem AsJob-Parameter eines cmdlets gestartet wurden. Sie können die Ergebnisse aller Aufträge abrufen oder Aufträge nach Name, ID, Instanz-ID, Computername, Speicherort oder Sitzung oder durch Senden eines Auftragsobjekts identifizieren.

Wenn Sie einen PowerShell-Hintergrundauftrag starten, wird der Auftrag gestartet, aber die Ergebnisse werden nicht sofort angezeigt. Stattdessen gibt der Befehl ein Objekt zurück, das den Hintergrundauftrag darstellt. Das Auftragsobjekt enthält nützliche Informationen zum Auftrag, enthält aber nicht die Ergebnisse. Mit dieser Methode können Sie während der Ausführung des Auftrags weiterhin in der Sitzung arbeiten. Weitere Informationen zu Hintergrundaufträgen in PowerShell finden Sie unter about_Jobs.

Das Receive-Job Cmdlet ruft die Ergebnisse ab, die nach dem Senden des Receive-Job Befehls generiert wurden. Wenn die Ergebnisse noch nicht abgeschlossen sind, können Sie zusätzliche Receive-Job Befehle ausführen, um die verbleibenden Ergebnisse zu erhalten.

Standardmäßig werden Auftragsergebnisse beim Empfang aus dem System gelöscht, aber Sie können den Parameter "Keep" verwenden, um die Ergebnisse zu speichern, damit Sie sie erneut empfangen können. Um die Auftragsergebnisse zu löschen, führen Sie den Receive-Job Befehl erneut ohne den Parameter Keep aus, schließen Sie die Sitzung, oder verwenden Sie das Remove-Job Cmdlet, um den Auftrag aus der Sitzung zu löschen.

Ab Windows PowerShell 3.0 Receive-Job werden auch die Ergebnisse von benutzerdefinierten Auftragstypen abgerufen, z. B. Workflowaufträge und Instanzen von geplanten Aufträgen. Um die Ergebnisse einem benutzerdefinierten Auftragstyp zu ermöglichen Receive-Job , importieren Sie das Modul, das den benutzerdefinierten Auftragstyp unterstützt, in die Sitzung, bevor ein Receive-Job Befehl ausgeführt wird, entweder mithilfe des Import-Module Cmdlets oder durch Abrufen eines Cmdlets im Modul. Informationen zu einem bestimmten benutzerdefinierten Auftragstyp finden Sie in der Dokumentation der Funktion „Benutzerdefinierte Auftragstypen“.

Beispiele

Beispiel 1: Abrufen von Ergebnissen für einen bestimmten Auftrag

$job = Start-Job -ScriptBlock {Get-Process}
Start-Sleep -Seconds 1
Receive-Job -Job $job

Diese Befehle verwenden den Job-Parameter , Receive-Job um die Ergebnisse eines bestimmten Auftrags abzurufen.

Der erste Befehl startet einen Auftrag mit Start-Job und speichert das Auftragsobjekt in der $job Variablen.

Der zweite Befehl verwendet das Receive-Job Cmdlet, um die Ergebnisse des Auftrags abzurufen. Er verwendet den Job-Parameter , um den Auftrag anzugeben.

Beispiel 2: Verwenden des Keep-Parameters

$job = Start-Job -ScriptBlock {Get-Service dhcp, fakeservice}
Start-Sleep -Seconds 1
$job | Receive-Job -Keep

Cannot find any service with service name 'fakeservice'.
    + CategoryInfo          : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
    + FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
    + PSComputerName        : localhost

Status   Name               DisplayName
------   ----               -----------
Running  dhcp               DHCP Client

$job | Receive-Job -Keep

Cannot find any service with service name 'fakeservice'.
    + CategoryInfo          : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
    + FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
    + PSComputerName        : localhost

Status   Name               DisplayName
------   ----               -----------
Running  dhcp               DHCP Client

In diesem Beispiel wird ein Auftrag in der $job Variablen gespeichert und der Auftrag an das Receive-Job Cmdlet weitergeleitet. Der -Keep Parameter wird auch verwendet, um zuzulassen, dass alle aggregierten Datenstromdaten nach der ersten Ansicht erneut abgerufen werden.

Beispiel 3: Abrufen von Ergebnissen mehrerer Hintergrundaufträge

Wenn Sie den AsJob-Parameter Invoke-Command verwenden, um einen Auftrag zu starten, wird das Auftragsobjekt auf dem lokalen Computer erstellt, obwohl der Auftrag auf den Remotecomputern ausgeführt wird. Folglich verwenden Sie lokale Befehle, um den Auftrag zu verwalten.

Wenn Sie AsJob verwenden, gibt PowerShell auch ein Auftragsobjekt zurück, das einen untergeordneten Auftrag für jeden Auftrag enthält, der gestartet wurde. In diesem Fall enthält das Auftragsobjekt drei untergeordnete Aufträge, einen für jeden Auftrag auf jedem Remotecomputer.

# Use the Invoke-Command cmdlet with the -AsJob parameter to start a background job that
# runs a Get-Service command on three remote computers. Store the resulting job object in
# the $j variable
$j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob
# Display the value of the **ChildJobs** property of the job object in $j. The display
# shows that the command created three child jobs, one for the job on each remote
# computer. You could also use the -IncludeChildJobs parameter of the Get-Job cmdlet.
$j.ChildJobs

Id   Name     State      HasMoreData   Location       Command
--   ----     -----      -----------   --------       -------
2    Job2     Completed  True          Server01       Get-Service
3    Job3     Completed  True          Server02       Get-Service
4    Job4     Completed  True          Server03       Get-Service

# Use the Receive-Job cmdlet to get the results of just the Job3 child job that ran on the
# Server02 computer. Use the *Keep* parameter to allow you to view the aggregated stream
# data more than once.
Receive-Job -Name Job3 -Keep

Status  Name        DisplayName                        PSComputerName
------  ----------- -----------                        --------------
Running AeLookupSvc Application Experience             Server02
Stopped ALG         Application Layer Gateway Service  Server02
Running Appinfo     Application Information            Server02
Running AppMgmt     Application Management             Server02

Beispiel 4: Abrufen von Ergebnissen von Hintergrundaufträgen auf mehreren Remotecomputern

# Use the New-PSSession cmdlet to create three user-managed PSSessions on three servers,
# and save the sessions in the $s variable.
$s = New-PSSession -ComputerName Server01, Server02, Server03
# Use Invoke-Command run a Start-Job command in each of the PSSessions in the $s variable.
# The code creates a new job with a custom name to each server. The job outputs the
# datetime from each server. Save the job objects in the $j variable.
$invokeCommandSplat = @{
    Session = $s
    ScriptBlock = {
        Start-Job -Name $('MyJob-' +$env:COMPUTERNAME) -ScriptBlock {
            (Get-Date).ToString()
        }
    }
}
$j = Invoke-Command @invokeCommandSplat
# To confirm that these job objects are from the remote machines, run Get-Job to show no
# local jobs running.
Get-Job`
# Display the three job objects in $j. Note that the Localhost location is not the local
# computer, but instead localhost as it relates to the job on each Server.
$j

Id   Name               State      HasMoreData   Location   Command
--   ----               -----      -----------   --------   -------
1    MyJob-Server01     Completed  True          Localhost  (Get-Date).ToString()
2    MyJob-Server02     Completed  True          Localhost  (Get-Date).ToString()
3    MyJob-Server03     Completed  True          Localhost  (Get-Date).ToString()

# Use Invoke-Command to run a Receive-Job command in each of the sessions in the $s
# variable and save the results in the $results variable. The Receive-Job command must be
# run in each session because the jobs were run locally on each server.
$results = Invoke-Command -Session $s -ScriptBlock {
    Receive-Job -Name $('MyJob-' +$env:COMPUTERNAME)
}

3/22/2021 7:41:47 PM
3/22/2021 7:41:47 PM
3/22/2021 9:41:47 PM

Dieses Beispiel zeigt, wie Sie die Ergebnisse der Hintergrundaufträge abrufen können, die auf drei Computern ausgeführt werden. Im Gegensatz zum vorherigen Beispiel hat die Verwendung Invoke-Command des Start-Job Befehls tatsächlich drei unabhängige Aufträge auf jedem der drei Computer gestartet. Daher hat der Befehl drei Auftragsobjekte zurückgegeben, die drei Aufträge darstellen, die lokal auf drei verschiedenen Computern ausgeführt werden.

Beispiel 5: Zugreifen auf untergeordnete Aufträge

Der -Keep Parameter behält den Status der aggregierten Datenströme eines Auftrags bei, damit er wieder angezeigt werden kann. Ohne diesen Parameter werden alle aggregierten Datenstromdaten gelöscht, wenn der Auftrag empfangen wird. Weitere Informationen finden Sie unter about_Job_Details

Hinweis

Die aggregierten Datenströme enthalten die Datenströme aller untergeordneten Aufträge. Sie können die einzelnen Datenströme weiterhin über das Auftragsobjekt und untergeordnete Auftragsobjekte erreichen.

Start-Job -Name TestJob -ScriptBlock {dir C:\, Z:\}
# Without the Keep parameter, aggregated child job data is displayed once.
# Then destroyed.
Receive-Job -Name TestJob

Directory: C:\

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-r---        1/24/2019   7:11 AM                Program Files
d-r---        2/13/2019   8:32 AM                Program Files (x86)
d-r---        10/3/2018  11:47 AM                Users
d-----         2/7/2019   1:52 AM                Windows
Cannot find drive. A drive with the name 'Z' does not exist.
    + CategoryInfo          : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
    + FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
    + PSComputerName        : localhost

# It would seem that the child job data is gone.
Receive-Job -Name TestJob



# Using the object model, you can still retrieve child job data and streams.
$job = Get-Job -Name TestJob
$job.ChildJobs[0].Error

Cannot find drive. A drive with the name 'Z' does not exist.
    + CategoryInfo          : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
    + FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
    + PSComputerName        : localhost

Parameter

-AutoRemoveJob

Gibt an, dass dieses Cmdlet den Auftrag löscht, nachdem er die Auftragsergebnisse zurückgegeben hat. Wenn der Auftrag mehr Ergebnisse hat, wird der Auftrag weiterhin gelöscht, zeigt jedoch Receive-Job eine Meldung an.

Dieser Parameter kann nur für benutzerdefinierte Auftragstypen verwendet werden. Es wurde für Instanzen von Auftragstypen entwickelt, die den Auftrag oder den Typ außerhalb der Sitzung speichern, z. B. Instanzen von geplanten Aufträgen.

Dieser Parameter kann nicht ohne den Wait-Parameter verwendet werden.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ComputerName

Gibt ein Array von Namen von Computern an.

Mit diesem Parameter wird unter den Auftragsergebnissen ausgewählt, die auf dem lokalen Computer gespeichert sind. Es werden keine Daten für Aufträge abgerufen, die auf Remotecomputern ausgeführt werden. Um Auftragsergebnisse abzurufen, die auf Remotecomputern gespeichert sind, verwenden Sie das Invoke-Command Cmdlet, um einen Receive-Job Befehl remote auszuführen.

Typ:String[]
Aliase:Cn
Position:1
Standardwert:All computers available
Erforderlich:False
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:True

-Force

Gibt an, dass dieses Cmdlet weiterhin wartet, wenn Sich Aufträge im Zustand "Angehalten " oder "Getrennt " befinden. Standardmäßig wird der Wait-Parameter zurückgegeben Receive-Job oder beendet, wenn Aufträge in einem der folgenden Zustände vorhanden sind:

  • Abgeschlossen
  • Fehler
  • Beendet
  • Ausgesetzt
  • Getrennt

Der Force-Parameter ist nur gültig, wenn der Wait-Parameter auch im Befehl verwendet wird.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Id

Gibt ein Array von IDs an. Dieses Cmdlet ruft die Ergebnisse von Aufträgen mit den angegebenen IDs ab.

Die ID ist eine ganze Zahl, die den Auftrag in der aktuellen Sitzung eindeutig identifiziert. Es ist einfacher zu merken und einzugeben als die Instanz-ID, aber es ist nur in der aktuellen Sitzung eindeutig. Sie können eine oder mehrere IDs durch Kommas getrennt eingeben. Um die ID eines Auftrags zu finden, verwenden Sie Get-Job.

Typ:Int32[]
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-InstanceId

Gibt ein Array von Instanz-IDs an. Dieses Cmdlet ruft die Ergebnisse von Aufträgen mit den angegebenen Instanz-IDs ab.

Eine Instanz-ID ist eine GUID, die den Auftrag auf dem Computer eindeutig identifiziert. Verwenden Sie das Get-Job Cmdlet, um die Instanz-ID eines Auftrags zu finden.

Typ:Guid[]
Position:0
Standardwert:All instances
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-Job

Gibt den Auftrag an, für den Ergebnisse abgerufen werden.

Geben Sie eine Variable ein, die den Auftrag enthält, oder geben Sie einen Befehl ein, mit dem das Objekt abgerufen wird. Sie können ein Auftragsobjekt auch an Receive-Job.

Typ:Job[]
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-Keep

Gibt an, dass dieses Cmdlet die aggregierten Datenstromdaten auch nach dem Empfang im System speichert. Aggregierte Datenstromdaten werden standardmäßig gelöscht, nachdem sie mit Receive-Jobangezeigt wurden.

Wenn Sie die Sitzung schließen oder den Auftrag mit dem Remove-Job Cmdlet entfernen, werden auch aggregierte Datenstromdaten gelöscht.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Location

Gibt ein Array von Speicherorten an. Dieses Cmdlet ruft nur die Ergebnisse von Aufträgen an den angegebenen Speicherorten ab.

Typ:String[]
Position:1
Standardwert:All locations
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Name

Gibt ein Array von Anzeigenamen an. Dieses Cmdlet ruft die Ergebnisse von Aufträgen ab, die über die angegebenen Namen verfügen. Platzhalterzeichen werden unterstützt.

Typ:String[]
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:True

-NoRecurse

Gibt an, dass dieses Cmdlet nur Ergebnisse aus dem angegebenen Auftrag abruft. Ruft standardmäßig Receive-Job auch die Ergebnisse aller untergeordneten Aufträge des angegebenen Auftrags ab.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Session

Gibt ein Array von Sitzungen an. Dieses Cmdlet ruft die Ergebnisse von Aufträgen ab, die in der angegebenen PowerShell-Sitzung (PSSession) ausgeführt wurden. Geben Sie eine Variable ein, die die PSSession oder einen Befehl enthält, der die PSSession abruft, z. B. einen Get-PSSession Befehl.

Typ:PSSession[]
Position:1
Standardwert:All sessions
Erforderlich:False
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-Wait

Gibt an, dass dieses Cmdlet die Eingabeaufforderung unterdrückt, bis alle Auftragsergebnisse empfangen werden. Gibt standardmäßig Receive-Job sofort die verfügbaren Ergebnisse zurück.

Standardmäßig wartet der Wait-Parameter , bis sich der Auftrag in einem der folgenden Zustände befindet:

  • Abgeschlossen
  • Fehler
  • Beendet
  • Ausgesetzt
  • Getrennt

Um den Wait-Parameter weiterzuwarten, wenn der Auftragsstatus angehalten oder getrennt ist, verwenden Sie den Parameter Force zusammen mit dem Wait-Parameter .

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-WriteEvents

Gibt an, dass dieses Cmdlet Änderungen im Auftragszustand meldet, während er auf den Abschluss des Auftrags wartet.

Dieser Parameter ist nur gültig, wenn der Wait-Parameter im Befehl verwendet wird und der Parameter Keep ausgelassen wird.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-WriteJobInResults

Gibt an, dass dieses Cmdlet das Auftragsobjekt gefolgt von den Ergebnissen zurückgibt.

Dieser Parameter ist nur gültig, wenn der Wait-Parameter im Befehl verwendet wird und der Parameter Keep ausgelassen wird.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

Job

Sie können Auftragsobjekte an dieses Cmdlet weiterleiten.

Ausgaben

PSObject

Dieses Cmdlet gibt die Ergebnisse der Befehle im Auftrag zurück.

Hinweise

Windows PowerShell enthält die folgenden Aliase für Receive-Job:

  • rcjb