powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Wait-Job



NAME
Wait-Job

SYNOPSIS
Suppresses the command prompt until one or all of the Windows PowerShell background jobs running in the session are
complete.

SYNTAX
Wait-Job [[-InstanceId] ] [-Any] [-Timeout ] []

Wait-Job [-Job] [-Any] [-Timeout ] []

Wait-Job [[-Name] ] [-Any] [-Timeout ] []

Wait-Job [-Id] [-Any] [-Timeout ] []

Wait-Job [-State {NotStarted | Running | Completed | Failed | Stopped | Blocked}] [-Any] [-Timeout ] [ arameters>]


DESCRIPTION
The Wait-Job cmdlet waits for Windows PowerShell background jobs to complete before it displays the command prompt.
You can wait until any background job is complete, or until all background jobs are complete, and you can set a ma
ximum wait time for the job.

You can use Wait-Job to get background jobs that were started by using Start-Job or the AsJob parameter of Invoke-C
ommand.

When the commands in the job are complete, Wait-Job displays the command prompt and returns a job object so that yo
u can pipe it to another command.


PARAMETERS
-Any []
Displays the command prompt (and returns the job object) when any job completes. By default, Wait-Job waits unt
il all of the specified jobs are complete before displaying the prompt.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Id
Waits for jobs with the specified IDs.

The ID is an integer that uniquely identifies the job within the current session. It is easier to remember and
type than the InstanceId, but it is unique only within the current session. You can type one or more IDs (separ
ated by commas). To find the ID of a job, type "Get-Job" without parameters.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-InstanceId
Waits for jobs with the specified instance IDs. The default is all jobs.

An instance ID is a GUID that uniquely identifies the job on the computer. To find the instance ID of a job, us
e Get-Job.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Job
Waits for the specified jobs. Enter a variable that contains the job objects or a command that gets the job obj
ects. You can also use a pipeline operator to send job objects to the Wait-Job cmdlet. By default, Wait-Job wai
ts for all jobs created in the current session.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-Name
Waits for jobs with the specified friendly name.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-State
Waits for jobs in the specified state. Valid values are NotStarted, Running, Completed, Stopped, Failed, and Bl
ocked.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Timeout
Determines the maximum wait time for each background job, in seconds. The default, -1, waits until the job comp
letes, no matter how long it runs. The timing starts when you submit the Wait-Job command, not the Start-Job co
mmand.

If this time is exceeded, the wait ends and the command prompt returns, even if the job is still running. No er
ror message is displayed.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.Management.Automation.RemotingJob
You can pipe a job object to Wait-Job.


OUTPUTS
System.Management.Automation.RemotingJob
Wait-Job returns job objects that represent the completed jobs. If the wait ends because the value of the Timeo
ut parameter is exceeded, Wait-Job does not return any objects.


NOTES





-------------------------- EXAMPLE 1 --------------------------

C:\PS>get-job | wait-job


Description
-----------
This command waits for all of the background jobs running in the session to complete.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>$s = new-pssession server01, server02, server03

C:\PS> invoke-command -session $s -scriptblock {start-job -name Date1 -scriptblock {get-date}}

C:\PS> $done = invoke-command -session $s -command {wait-job -name Date1}

C:\PS> $done.count
3


Description
-----------
This example shows how to use the Wait-Job cmdlet with jobs started on remote computers by using the Start-Job cmdl
et. Both the Start-Job and Wait-Job commands are submitted to the remote computer by using the Invoke-Command cmdle
t.

This example uses Wait-Job to determine whether a Get-Date command running as a background job on three different c
omputers is complete.

The first command creates a Windows PowerShell session (PSSession) on each of the three remote computers and stores
them in the $s variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the three sessions in $s. A
ll of the jobs are named Date1.

The third command uses the Invoke-Command cmdlet to run a Wait-Job command. This command waits for the Date1 jobs o
n each computer to complete. It stores the resulting collection (array) of job objects in the $done variable.

The fourth command uses the Count property of the array of job objects in the $done variable to determine how many
of the jobs are complete.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$s = new-pssession (get-content machines.txt)

C:\PS> $c = 'get-eventlog -log system | where {$_.EntryType -eq "error" -and $_.Source -eq "LSASRV"} | out-file err
ors.txt'

C:\PS> invoke-command -session $s -scriptblock {param($c)start-job -scriptblock {$c}} -ArgumentList $c

C:\PS> invoke-command -session $s -scriptblock {wait-job -any}


Description
-----------
This example uses the Any parameter of Wait-Job to determine when the first of many background jobs running in the
current session are complete. It also shows how to use the Wait-Job cmdlet to wait for remote jobs to complete.

The first command creates a PSSession on each of the computers listed in the Machines.txt file and stores the PSSes
sions in the $s variable. The command uses the Get-Content cmdlet to get the contents of the file. The Get-Content
command is enclosed in parentheses to ensure that it runs before the New-PSSession command.

The second command stores a Get-EventLog command string (in quotation marks) in the $c variable.

The third command uses the Invoke-Command cmdlet to run a Start-Job command in each of the sessions in $s. The Star
t-Job command starts a background job that runs the command in $c.

Because the $c variable is on the local computer, the command uses the "param" keyword to declare the local variabl
es in the command and the ArgumentList parameter to supply the values for those variables.

The fourth command uses the Invoke-Command cmdlet to run a Wait-Job command in the sessions. It uses the Wait-Job c
mdlet to wait until the first job on the remote computers is complete.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>$s = new-pssession Server01, Server02, Server03

C:\PS> $jobs = invoke-command -session $s -scriptblock {start-job -script {get-date}}

C:\PS> $done = invoke-command -session $s -scriptblock {wait-job -timeout 30}


Description
-----------
This example shows how to use the Timeout parameter of Wait-Job to set a maximum wait time for the jobs running on
remote computers.

The first command creates a PSSession on each of three remote computers (Server01, Server02, and Server03), and it
saves the PSSessions in the $s variable.

The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in $s. It sa
ves the resulting job objects in the $jobs variable.

The third command uses the Invoke-Command cmdlet to run a Wait-Job command in each of the PSSessions in $s. The Wai
t-Job command determines whether all of the commands have completed within 30 seconds. It uses the Timeout paramete
r with a value of 30 (seconds) to establish the maximum wait time and saves the results of the command in the $done
variable.

In this case, after 30 seconds, only the command on the Server02 computer has completed. Wait-Job ends the wait, di
splays the command prompt, and returns the object that represents the job that was completed.

The $done variable contains a job object that represents the job that ran on Server02.





-------------------------- EXAMPLE 5 --------------------------

C:\PS>wait-job -id 1,2,5 -any


Description
-----------
This command identifies three jobs by their IDs and waits until any of them are complete. The command prompt return
s when the first job completes.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>wait-job -name DailyLog -timeout 120


Description
-----------
This command waits 120 seconds (two minutes) for the DailyLog job to complete. If the job does not complete in the
next two minutes, the command prompt returns anyway, and the job continues to run in the background.





-------------------------- EXAMPLE 7 --------------------------

C:\PS>wait-job -name Job3


Description
-----------
This Wait-Job command uses the job name to identify the job to wait for.





-------------------------- EXAMPLE 8 --------------------------

C:\PS>C:\PS> $j = start-job -script {get-childitem *.ps1| where {$_lastwritetime -gt ((get-date) - (new-timespan -d
ays 7))}}

C:\PS> $j | wait-job


Description
-----------
This example shows how to use the Wait-Job cmdlet with jobs started on the local computer by using the Start-Job cm
dlet.

These commands start a job that gets the Windows PowerShell script files that were added or updated in the last wee
k.

The first command uses the Start-Job cmdlet to start a background job on the local computer. The job runs a Get-Chi
ldItem command that gets all of the files with a ".ps1" file name extension that were added or updated in the last
week.

The third command uses the Wait-Job cmdlet to wait until the job is complete. When the job completes, the command d
isplays the job object, which contains information about the job.





-------------------------- EXAMPLE 9 --------------------------

C:\PS>$s = new-pssession Server01, Server02, Server03

C:\PS> $j = invoke-command -session $s -scriptblock {get-process} -asjob

C:\PS> $j | wait-job


Description
-----------
This example shows how to use the Wait-Job cmdlet with jobs started on remote computers by using the AsJob paramete
r of the Invoke-Command cmdlet. When using AsJob, the job is created on the local computer and the results are auto
matically returned to the local computer, even though the job runs on the remote computers.

This example uses Wait-Job to determine whether a Get-Process command running in the sessions on three remote compu
ters is complete.

The first command creates PSSessions on three computers and stores them in the $s variable.

The second command uses the Invoke-Command cmdlet to run a Get-Process command in each of the three PSSessions in $
s. The command uses the AsJob parameter to run the command asynchronously as a background job. The command returns
a job object, just like the jobs started by using Start-Job, and the job object is stored in the $j variable.

The third command uses a pipeline operator (|) to send the job object in $j to the Wait-Job cmdlet. Notice that an
Invoke-Command command is not required in this case, because the job resides on the local computer.





-------------------------- EXAMPLE 10 --------------------------

C:\PS>get-job

Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 Job1 Completed True localhost,server01.. get-service
4 Job4 Completed True localhost dir | where

C:\PS> wait-job -id 1


Description
-----------
This command waits for the job with an ID value of 1.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113422
about_Jobs
about_Job_Details
about_Remote_Jobs
Start-Job
Get-Job
Receive-Job
Stop-Job
Remove-Job
Invoke-Command