Windows PowerShell Jobs and AsJob

Windows PowerShell Jobs and AsJob

In the context of PowerShell, a ‘Job’ is simply a package containing the results of running one or more cmdlets.  This article shows you two techniques for creating the PowerShell Job, then explains how you can extract the information stored in the job.

Topics for PowerShell -AsJob and Start-Job


Benefits of Creating a PowerShell Job

Large complex PowerShell script blocks could take ages to complete, consequently this processing could tie-up your command line.  Thus it’s better to have a ‘Job’ run in the background and free-up your keyboard so that you can issue other instructions.  Another benefit of creating a job is that thanks to the -keep parameter you can review the results again and again.

There are two strategies for employing ‘Jobs’; either append the parameter -asJob to a cmdlet such as Invoke-Command, or else create a new job id with start-Job followed by a PowerShell instruction in a scriptBlock.

Employing the -AsJob Parameter Strategy

This strategy relies on appending -asJob to a cmdlet such as invoke-Command, the results of the  scriptBlock are stored as a job.  The PowerShell commands between the scriptBlock {braces} run in the background on the remote machine, however, the results are automatically saved locally as a new job ID.  All that you see on-screen is a record that the job is running, however, you can check the state of all jobs with Get-Job.  Remember that you do not see the actual data until you run a sister command receive-Job.

Invoke-Command -computer Victim1 -scriptBlock {Get-Service} -asJob

Note: In real-life you may want to modify the cmdlet with a ‘where-Object’ clause, for example,
{Get-Service | where{$_.status -eq "Running"}}

I rarely pay attention to the object nature of PowerShell, however, when it comes to jobs, it really helps to think of each item as an object, which we can then recall and manipulate, for example, we can pipe the output to format-table and select just the properties we are most interested in.

Thanks to the -computer parameter, asJob runs the command on the remote machine, even though the job object itself is stored on the local computer.  Incidentally, -asJob works not only with invoke-Command, but also with Get-WmiObect.

Guy Recommends:  A Free Trial of the Network Performance Monitor (NPM)Review of Orion NPM v11.5 v11.5

SolarWinds’ Network Performance Monitor will help you discover what’s happening on your network.  This utility will also guide you through troubleshooting; the dashboard will indicate whether the root cause is a broken link, faulty equipment or resource overload.

What I like best is the way NPM suggests solutions to network problems.  Its also has the ability to monitor the health of individual VMware virtual machines.  If you are interested in troubleshooting, and creating network maps, then I recommend that you try NPM now.

Download a free trial of Solarwinds’ Network Performance Monitor

Employing the Start-Job Strategy

 Here is the PowerShell instruction to research members of the job family:

Get-Command -Noun job

  • Get-Job
  • Receive-Job
  • Remove-Job
  • Start-Job
  • Stop-Job
  • Wait-Job

See also PowerShell v 3.0’s workflow

The Basics: Start-Job -scriptBlock {cmdlet(s)}

Start-Job -scriptBlock {Get-eventlog "System"}

While there is a PowerShell cmdlet called ‘Stop-Job’ you don’t normally need to issue this command,  PowerShell’s intelligence automatically stops the job when all the instructions have completed.  Thus the only need for Stop-Job is when you have made a mistake in a very long script, for instance, it’s looping.

The only puzzle with Start-Job is how do you access the data?  Get-Job merely lists the objects, it does not show their contents.  To solve that mystery we employ the ‘Receive’ verb as you will see in the next example.

Key Cmdlet: Receive-Job

Receive-Job is the crucial member of the job family because it enables us to check the results of running the scriptBlock with start-Job.  As a preliminary I always run Get-Job so that I can make a note of the job name or unique ID number.  All things considered, it’s essential that receive-Job has a name or number so that it can decide which object to read, and then write the results to your screen.

receive-job job19 -keep

The first time I ran receive-Job the command completed successfully but it removed all the data from the object (HasMoreData – False).  This is why I now append the -keep parameter, so that I can run the command again and the data is still in the object.

More good news, because each job is an object, you pipe can the results into format-table, and thus control the output. 

receive-job job19 -keep | format-table name, property1 etc*

* Since your ‘job’ is different from mine, you need to research the names of its properties.  If you cannot remember then refer back to the scriptBlock in the original Start-Job instruction.

Engineer's Toolset v10Guy Recommends: SolarWinds Engineer’s Toolset v10

This Engineer’s Toolset v10 provides a comprehensive console of 50 utilities for troubleshooting computer problems.  Guy says it helps me monitor what’s occurring on the network, and each tool teaches me more about how the underlying system operates.

There are so many good gadgets; it’s like having free rein of a sweetshop.  Thankfully the utilities are displayed logically: monitoring, network discovery, diagnostic, and Cisco tools.  Try the SolarWinds Engineer’s Toolset now!

Download your fully functional trial copy of the Engineer’s Toolset v10

Cleaning up with Remove-Job

One side effect of experimenting is creating lots of failed jobs, thus it’s useful to have a clean-up, and for this task run Remove-Job *.  The famous * wildcard zaps all jobs in the cache.  If you preferred you could just remove a named job.  Even better, try the -state switch.

Remove-Job -state failed

Incidentally, note that PowerShell is consistent, it always employs the ‘Remove’ verb and never delete, erase, zap, kill or other synonyms for remove.

Summary of PowerShell Jobs and AsJob

The creators of Microsoft PowerShell seem to anticipate every need, and every problem with running scripts.  What members of the Job family bring is the ability to run scripts in the background.  Furthermore these commands enable you to run scripts on remote computers and collate them on the local machine.  Finally, working with ‘Jobs’ reinforces the benefits and the nature of object based scripting.

If you like this page then please share it with your friends


See more Microsoft PowerShell tutorials

PowerShell Home   • Real life tasks   • Invoke-Command   • PowerShell Windows 7

Remote PowerShell   • PowerShell WSMan  • -Online   • PowerShell WinRm   • Test-Connection

Jobs  -AsJob   • Receive-Job   • Get-Job   • Receive-Job   • Free WMI Monitor

Please email me if you have a better example script. Also please report any factual mistakes, grammatical errors or broken links, I will be happy to correct the fault.