Compartir a través de


Receive-Job

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

Sintaxis

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>]

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 job 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 se han completado, puede ejecutar comandos adicionales Receive-Job para obtener los resultados restantes.

De forma predeterminada, los resultados del trabajo se eliminan del sistema cuando los recibe, pero puede usar el parámetro Keep para guardar los resultados para que pueda recibirlos de nuevo. 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 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 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}
Start-Sleep -Seconds 1
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 de trabajo 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}
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

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 de 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 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

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 inició realmente 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 diferentes.

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 obtener 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 de datos individuales 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 devolver 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 instancias de trabajos programados.

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

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

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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 que se ejecutan 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.

Tipo:String[]
Alias:Cn
Posición:1
Valor predeterminado:All computers available
Requerido:False
Aceptar entrada de canalización:True
Aceptar caracteres comodín: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:

  • Completado
  • Errónea
  • 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.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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.

Tipo:Int32[]
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín: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 .

Tipo:Guid[]
Posición:0
Valor predeterminado:All instances
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín: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.

Tipo:Job[]
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-Keep

Indica que este cmdlet guarda los datos de flujo agregados en el sistema, incluso después de recibirlos. 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 de flujo agregados.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Location

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

Tipo:String[]
Posición:1
Valor predeterminado:All locations
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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.

Tipo:String[]
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín: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.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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 psSession o un comando que obtenga psSession, como un Get-PSSession comando.

Tipo:PSSession[]
Posición:1
Valor predeterminado:All sessions
Requerido:False
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-Wait

Indica que este cmdlet suprime el símbolo del sistema hasta que se reciban 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 esté en uno de los estados siguientes:

  • Completado
  • Errónea
  • Detenido
  • Suspended
  • Escenario 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.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-WriteEvents

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

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

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

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-WriteJobInResults

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

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

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

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

Job

Puede canalizar objetos de trabajo a este cmdlet.

Salidas

PSObject

Este cmdlet devuelve los resultados de los comandos del trabajo.

Notas

PowerShell incluye los siguientes alias para Receive-Job:

  • Todas las plataformas:
    • rcjb