Receive-Job

  • Referencia
Módulo:
Microsoft.PowerShell.Core

Obtiene los resultados de los trabajos en segundo plano de PowerShell en la sesión actual.

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
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-Name] <String[]>
       [<CommonParameters>]
Receive-Job
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-InstanceId] <Guid[]>
       [<CommonParameters>]
Receive-Job
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-Id] <Int32[]>
       [<CommonParameters>]

Description

El Receive-Job cmdlet obtiene los resultados de los trabajos en segundo plano de PowerShell, como los iniciados mediante el Start-Job cmdlet o el parámetro AsJob de cualquier cmdlet. Puede obtener los resultados de todos los trabajos o identificar trabajos por su nombre, identificador, identificador de instancia, nombre de equipo, ubicación o sesión o mediante el envío de un objeto de trabajo.

Al iniciar un trabajo en segundo plano de PowerShell, se inicia el trabajo, pero los resultados no aparecen inmediatamente. En su lugar, el comando devuelve un objeto que representa el trabajo en segundo plano. El objeto de trabajo contiene información útil sobre el trabajo, pero no contiene los resultados. Este método le permite seguir trabajando en la sesión mientras se ejecuta el trabajo. Para obtener más información sobre los trabajos en segundo plano en PowerShell, consulte about_Jobs.

El Receive-Job cmdlet obtiene los resultados generados por el momento en que se envía el Receive-Job comando. Si los resultados aún no están completos, puede ejecutar comandos adicionales Receive-Job para obtener los resultados restantes.

De forma predeterminada, los resultados de los trabajos se eliminan del sistema cuando los recibe, pero puede usar el parámetro Keep para guardar los resultados para que pueda volverlos a recibir. Para eliminar los resultados del trabajo, vuelva a ejecutar el Receive-Job comando sin el parámetro Keep , cierre la sesión o use el Remove-Job cmdlet para eliminar el trabajo de la sesión.

A partir de Windows PowerShell 3.0, Receive-Job también obtiene los resultados de los tipos de trabajo personalizados, como trabajos de flujo de trabajo e instancias de trabajos programados. Para habilitar Receive-Job para obtener los resultados de un tipo de trabajo personalizado, importe el módulo que admite el tipo de trabajo personalizado en la sesión antes de ejecutar un Receive-Job comando, ya sea mediante el Import-Module cmdlet o mediante o obteniendo un cmdlet en el módulo. Para información sobre un tipo determinado de trabajo personalizado, vea la documentación de la característica del tipo de trabajo personalizado.

Ejemplos

Ejemplo 1: Obtención de resultados para un trabajo determinado

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

Estos comandos usan el parámetro Job de Receive-Job para obtener los resultados de un trabajo determinado.

El primer comando inicia un trabajo con Start-Job y almacena el objeto job en la $job variable .

El segundo comando usa el Receive-Job cmdlet para obtener los resultados del trabajo. Usa el parámetro Job para especificar el trabajo.

Ejemplo 2: Uso del parámetro Keep

$job = Start-Job -ScriptBlock {Get-Service dhcp, fakeservice}
$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

En este ejemplo se almacena un trabajo en la $job variable y se canaliza el trabajo al Receive-Job cmdlet . El -Keep parámetro también se usa para permitir que todos los datos de flujo agregados se recuperen de nuevo después de la primera vista.

Ejemplo 3: Obtención de resultados de varios trabajos en segundo plano

Cuando se usa el parámetro AsJob de Invoke-Command para iniciar un trabajo, el objeto de trabajo se crea en el equipo local, aunque el trabajo se ejecute en los equipos remotos. Como resultado, use comandos locales para administrar el trabajo.

Además, cuando se usa AsJob, PowerShell devuelve un objeto de trabajo que contiene un trabajo secundario para cada trabajo que se inició. En este caso, el objeto de trabajo contiene tres trabajos secundarios, uno para cada trabajo en cada equipo remoto.

# 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

Ejemplo 4: Obtención de resultados de trabajos en segundo plano en varios equipos remotos

# 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 job outputs the ComputerName of each server.
# Save the job objects in the $j variable.
$j = Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {$env:COMPUTERNAME}}
# 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    Job1     Completed  True          Localhost  $env:COMPUTERNAME
2    Job2     Completed  True          Localhost  $env:COMPUTERNAME
3    Job3     Completed  True          Localhost  $env:COMPUTERNAME

# 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 -Job $Using:j}

Server01
Server02
Server03

En este ejemplo se muestra cómo obtener los resultados de los trabajos en segundo plano que se ejecutan en tres equipos remotos. A diferencia del ejemplo anterior, el uso Invoke-Command de para ejecutar el Start-Job comando realmente inició tres trabajos independientes en cada uno de los tres equipos. Como resultado, el comando devolvió tres objetos de trabajo que representan tres trabajos que se ejecutan localmente en tres equipos distintos.

Nota

En el último comando, dado que $j es una variable local, el bloque de script usa el modificador Using scope ( Usar ámbito) para identificar la $j variable. Para obtener más información sobre el modificador Using scope ( Usar modificador de ámbito), vea about_Remote_Variables.

Ejemplo 5: Acceso a trabajos secundarios

El -Keep parámetro conserva el estado de las secuencias agregadas de un trabajo para que se pueda volver a ver. Sin este parámetro, se borran todos los datos de flujo agregados cuando se recibe el trabajo. Para más información, consulte about_Job_Details

Nota

Los flujos agregados incluyen los flujos de todos los trabajos secundarios. Todavía puede llegar a los flujos individuales de datos a través del objeto de trabajo y los objetos de trabajo secundarios.

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

Parámetros

-AutoRemoveJob

Indica que este cmdlet elimina el trabajo después de que devuelva los resultados del trabajo. Si el trabajo tiene más resultados, el trabajo se sigue eliminando, pero Receive-Job muestra un mensaje.

Este parámetro solo funciona en tipos de trabajo personalizados. Está diseñado para instancias de tipos de trabajo que guardan el trabajo o el tipo fuera de la sesión, como las instancias de los trabajos programados.

Este parámetro no se puede usar sin el parámetro Wait .

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ComputerName

Especifica una matriz de nombres de equipos.

Este parámetro se selecciona entre los resultados del trabajo que se almacenan en el equipo local. No obtiene datos para los trabajos ejecutados en equipos remotos. Para obtener los resultados del trabajo almacenados en equipos remotos, use el Invoke-Command cmdlet para ejecutar un Receive-Job comando de forma remota.

Type:String[]
Aliases:Cn
Position:1
Default value:All computers available
Required:False
Accept pipeline input:True
Accept wildcard characters:True

-Force

Indica que este cmdlet continúa esperando si los trabajos están en estado Suspendido o Desconectado . De forma predeterminada, el parámetro Wait de Receive-Job devuelve o finaliza la espera, cuando los trabajos se encuentran en uno de los estados siguientes:

  • Completed
  • Con error
  • Detenido
  • Suspended
  • Desconectado

El parámetro Force solo es válido cuando el parámetro Wait también se usa en el comando.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Id

Especifica una matriz de identificadores. Este cmdlet obtiene los resultados de los trabajos con los identificadores especificados.

El identificador es un entero que identifica de forma única el trabajo en la sesión actual. Es más fácil recordar y escribir que el identificador de instancia, pero solo es único en la sesión actual. Puede escribir uno o varios identificadores separados por comas. Para buscar el identificador de un trabajo, use Get-Job.

Type:Int32[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-InstanceId

Especifica una matriz de identificadores de instancia. Este cmdlet obtiene los resultados de los trabajos con los identificadores de instancia especificados.

Un identificador de instancia es un GUID que identifica de forma única la tarea en el equipo. Para buscar el identificador de instancia de un trabajo, use el Get-Job cmdlet .

Type:Guid[]
Position:0
Default value:All instances
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Job

Especifica el trabajo para el que se están recuperando los resultados.

Escriba una variable que contenga el trabajo o un comando que obtenga el trabajo. También puede canalizar un objeto de trabajo a Receive-Job.

Type:Job[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Keep

Indica que este cmdlet guarda los datos de flujo agregados en el sistema, incluso después de haber recibidolos. De forma predeterminada, los datos de flujo agregados se borran después de verlos con Receive-Job.

Al cerrar la sesión o quitar el trabajo con el Remove-Job cmdlet también se eliminan los datos agregados de la secuencia.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Location

Especifica una matriz de ubicaciones. Este cmdlet solo obtiene los resultados de los trabajos en las ubicaciones especificadas.

Type:String[]
Position:1
Default value:All locations
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Especifica una matriz de nombres descriptivos. Este cmdlet obtiene los resultados de los trabajos que tienen los nombres especificados. Se admite el uso de caracteres comodín.

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:True

-NoRecurse

Indica que este cmdlet obtiene los resultados solo del trabajo especificado. De forma predeterminada, Receive-Job también obtiene los resultados de todos los trabajos secundarios del trabajo especificado.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Session

Especifica una matriz de sesiones. Este cmdlet obtiene los resultados de los trabajos que se ejecutaron en la sesión de PowerShell especificada (PSSession). Escriba una variable que contenga la PSSession o un comando que obtiene la PSSession, como un Get-PSSession comando.

Type:PSSession[]
Position:1
Default value:All sessions
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Wait

Indica que este cmdlet suprime el símbolo del sistema hasta que se reciben todos los resultados del trabajo. De forma predeterminada, Receive-Job devuelve inmediatamente los resultados disponibles.

De forma predeterminada, el parámetro Wait espera hasta que el trabajo tiene uno de los siguientes estados:

  • Completed
  • Con error
  • Detenido
  • Suspended
  • Desconectado

Para dirigir el parámetro Wait para continuar esperando si el estado del trabajo es Suspendido o Desconectado, use el parámetro Force junto con el parámetro Wait .

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WriteEvents

Indica que este cmdlet notifica los cambios en el estado del trabajo mientras espera a que finalice el trabajo.

Este parámetro solo es válido cuando el parámetro Wait se usa en el comando y se omite el parámetro Keep.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WriteJobInResults

Indica que este cmdlet devuelve el objeto de trabajo seguido de los resultados.

Este parámetro solo es válido cuando el parámetro Wait se usa en el comando y se omite el parámetro Keep.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

Job

Puede canalizar objetos de trabajo a este cmdlet.

Salidas

PSObject

Este cmdlet devuelve los resultados de los comandos del trabajo.