Summary: Microsoft Scripting Guy, Ed Wilson, talks about advanced aspects of Windows PowerShell scheduled jobs.

Microsoft Scripting Guy, Ed Wilson, is here. Today I want to look at some of the more advanced aspects of Windows PowerShell scheduled jobs. Windows PowerShell scheduled jobs do not have to be complicated. But because Windows PowerShell scheduled jobs are very flexible, there are many options.

Running a scheduled job manually

There are two ways to manually run a scheduled job instead of running it as an actual scheduled job with a trigger. The first way is to use the –RunNow parameter when creating a new scheduled job with the Register-ScheduledJob cmdlet. In the following command, I get a list of service information on my Surface Pro 2, and I pipe the output to a text file in the C:\fso directory. I give the scheduled job a name, and I elect to run the job immediately, instead at a later time via a trigger:

Register-ScheduledJob -Name GetGSV -ScriptBlock {GSV > c:\fso\gsv.txt} –RunNow

I then check the status of the job by using the Get-Job cmdlet. I pipe the object to the Format-List cmdlet so I can see all the details:

The other way to run a scheduled job immediately is to use the Start-Job cmdlet. An example of this is shown here:

Start-Job -DefinitionName getgsv

Jobs that are started by using the Start-Job cmdlet are standard Windows PowerShell background jobs, not instances of the scheduled job. Like all background jobs, these jobs start immediately. They are not subject to job options or affected by job triggers. Their output is not saved in the Output directory of the scheduled job directory.

Renaming a scheduled job is fairly easy. I use the –name parameter of the Set-ScheduledJob cmdlet. In the following example, I rename the GetGSV scheduled job to GetService. Notice that at this time, there is only a single scheduled job, so there was no reason to specify parameters for the Get-ScheduledJob cmdlet because it is only returning a single job.

Get-ScheduledJob | Set-ScheduledJob -Name GetService

The following image shows where I use Get-ScheduledJob to find scheduled jobs, and I rename the job. Then I again use Get-ScheduledJob to see what jobs are scheduled. You will see that the name change took place.

To change the command (or the script) that a scheduled job runs, I use exactly the same technique. In the following example, I change the script block to use the full cmdlet name, and then I select the Status, Name, and DisplayName of the services. I then sort the results and pipe them to a text file. I also change it so that I am not appending to the file, but overwriting the file. The command is shown here:

Get-ScheduledJob | Set-ScheduledJob -ScriptBlock {Get-Service | select status, name, displayname | sort status > c:\fso\gsv.txt}

I might want to generate a report about the history of my scheduled job. To do this, I once again use Windows PowerShell and the Get-Job cmdlet. This time, however, I get the PSBeginTime property and the PSEndTime property, and I calculate the elapsed time for the job. I then display the output in a table. The command is shown here:

Get-Job getservice |

ft ID, PSBeginTime, PSEndTime, @{L='totaltime';E={$_.psendtime – $_.psbegintime}} –auto

The command and the output from the command is shown here:

I can clear the execution history of scheduled job by using the –ClearExecutionHistory parameter from the Set-ScheduledJob cmdlet as shown here:

Get-ScheduledJob getservice | Set-ScheduledJob -ClearExecutionHistory

I can also configure the execution history value at the time of scheduled job creation. (By default, it keeps 32 history items for the job.) To do this, I use the –MaxResultCount parameter. This is the same parameter name I use with Set-ScheduledJob if I want to change the number of job items stored in the history. This technique is shown here:

Register-ScheduledJob -Name GetService  -ScriptBlock {gsv > c:\fso\gsv.txt} -MaxResultCount 12

That is all there is to using advanced scheduled jobs. Windows PowerShell Scheduled Job Week will continue tomorrow when I will talk about troubleshooting scheduled jobs.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy