Table of contents

About Scheduled Jobs Advanced

JuanPablo Jofre|Last Updated: 12/14/2016
|
2 Contributors

about_Scheduled_Jobs_Advanced

SHORT DESCRIPTION

Explains advanced scheduled job topics, including the file structure that underlies scheduled jobs.

LONG DESCRIPTION

This topic includes the following sections:

-- Scheduled job directories and files -- Rename a scheduled job -- Start a scheduled job immediately -- Manage execution history

SCHEDULED JOB DIRECTORIES AND FILES

Windows PowerShell scheduled jobs are both Windows PowerShell jobs and Task Scheduler tasks. Each scheduled job is registered in Task Scheduler and saved on disk in Microsoft .Net Framework Serialization XML format.

When you create a scheduled job, Windows Powershell creates a directory for the scheduled job in the $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs directory on the local computer. The directory name is the same as the job name.

The following is a sample ScheduledJobs directory.

PS C:\ps-test> dir $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs

Directory: C:\Users\User01\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs

Mode LastWriteTime Length Name


d---- 9/29/2011 10:03 AM ArchiveProjects d---- 9/30/2011 1:18 PM Inventory d---- 10/20/2011 9:15 AM Backup-Scripts d---- 11/7/2011 10:40 AM ProcessJob d---- 11/2/2011 10:25 AM SecureJob d---- 9/27/2011 1:29 PM Test-HelpFiles d---- 9/26/2011 4:22 PM DeployPackage

Each scheduled job has its own directory. The directory contains the scheduled job XML file and an Output subdirectory.

PS C:> dir $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\ProcessJob

Directory: C:\Users\User1\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\ProcessJob

Mode LastWriteTime Length Name


d---- 11/1/2011 3:00 PM Output -a--- 11/1/2011 3:43 PM 7281 ScheduledJobDefinition.xml

The Output directory for a scheduled job contains its execution history. Each time a job trigger starts a scheduled job, Windows PowerShell creates a timestamp-named directory in the Output directory. The timestamp directory contains the results of the job in a Results.xml file and the job status in a Status.xml file.

The following command shows the execution history directories for the ProcessJob scheduled job.

PS C:> dir $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\ProcessJob\Output

Directory: C:\Users\User01\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\ProcessJob\Output

Mode LastWriteTime Length Name


d---- 11/2/2011 3:00 AM 20111102-030002-260 d---- 11/3/2011 3:00 AM 20111103-030002-277 d---- 11/4/2011 3:00 AM 20111104-030002-209 d---- 11/5/2011 3:00 AM 20111105-030002-251 d---- 11/6/2011 3:00 AM 20111106-030002-174 d---- 11/7/2011 12:00 AM 20111107-000001-914 d---- 11/7/2011 3:00 AM 20111107-030002-376

PS C:> dir $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\ProcessJob\Output\20111102-030002-260

Directory: C:\Users\juneb\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\testjob\output\20111102-030002-260

Mode LastWriteTime Length Name


-a--- 11/2/2011 3:00 AM 581106 Results.xml -a--- 11/2/2011 3:00 AM 9451 Status.xml

You can open and examine the ScheduledJobDefinition.xml, Results.xml and Status.xml files or use the Select-XML cmdlet to parse the files.

WARNING: Do not edit the XML files. If any XML file contains invalid XML, Windows PowerShell deletes the scheduled job and its execution history, including job results.

START A SCHEDULED JOB IMMEDIATELY

You can start a scheduled job immediately in one of two ways:

-- Run the Start-Job cmdlet to start any scheduled job -- Add the RunNow parameter to your Register-ScheduledJob command to start the job as soon as the command is run

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 -- and their output is not saved in the Output directory of the scheduled job directory.

The following command uses the DefinitionName parameter of the Start-Job cmdlet to start the ProcessJob scheduled job.

Start-Job -DefinitionName ProcessJob

To manage the job and get the job results, use the Job cmdlets. For more information about the Job cmdlets, see about_Jobs (http://go.microsoft.com/fwlink/?LinkID=113251).

NOTE: To use the Job cmdlets on instances of scheduled jobs, the PSScheduledJob module must be imported into the session. To import the PSScheduledJob module, type "Import-Module PSScheduledJob" (without quotation marks) or use any Scheduled Job cmdlet, such as Get-ScheduledJob.

RENAME A SCHEDULED JOB

To rename a scheduled job, use the Name parameter of the Set-ScheduledJob cmdlet. When you rename a scheduled job, Windows PowerShell changes the name of the scheduled job and the scheduled job directory. However, it doesn't change the names of instances of the scheduled job that have already run.

GET START AND END TIMES

To get the dates and times that job instances started and ended, use the PSBeginTime and PSEndTime properties of the ScheduledJob object that Get-Job returns for scheduled jobs.

The following example uses the Property parameter of the Format-Table cmdlet to display the PSBeginTime and PSEndTime properties of each job instance in a table. The command uses a calculated property to display the elapsed time of each job instance.

PS C:> Get-job -Name UpdateHelpJob | Format-Table -Property ID, PSBeginTime, PSEndTime, @{Label="Elapsed Time";Expression={$.PsEndTime - $.PSBeginTime}}

Id PSBeginTime PSEndTime Elapsed Time


2 11/3/2011 3:00:01 AM 11/3/2011 3:00:39 AM 00:00:38.0053854

3 11/4/2011 3:00:02 AM 11/4/2011 3:01:01 AM 00:00:59.1188475

4 11/5/2011 3:00:02 AM 11/5/2011 3:00:50 AM 00:00:48.3692034

5 11/6/2011 3:00:01 AM 11/6/2011 3:00:54 AM 00:00:52.8013036

6 11/7/2011 3:00:01 AM 11/7/2011 3:00:38 AM 00:00:37.1930350

7 11/8/2011 3:00:01 AM 11/8/2011 3:00:57 AM 00:00:56.2570556

8 11/9/2011 3:00:03 AM 11/9/2011 3:00:55 AM 00:00:51.8142222

9 11/10/2011 3:00:02 AM 11/10/2011 3:00:42 AM 00:00:40.7195954

MANAGE EXECUTION HISTORY

You can determine the number of job instance results that are saved for each schedule job and delete the execution history and saved job results of any scheduled job at any time.

The ExecutionHistoryLength property of a scheduled job determines how many job instance results are saved for the scheduled job. When the number of saved results exceeds the value of the ExecutionHistoryLength property, Windows PowerShell deletes the results of the oldest instance to make room for the results of the newest instance.

By default, Windows PowerShell saves the execution history and results of 32 instances of each scheduled job. To change that value, use the MaxResultCount parameters of the Register-ScheduledJob or Set-ScheduledJob cmdlets.

To delete the execution history and all results for a scheduled job, use the ClearExecutionHistory parameter of the Set-ScheduledJob cmdlet. Deleting this execution history does not prevent Windows PowerShell from saving the results of new instances of the scheduled job.

The following command uses the Register-ScheduledJob cmdlet to creates a scheduled job. The command uses the MaxResultCount parameter with a value of 12 to save only the 12 newest job instance results of the scheduled job.

Register-ScheduledJob -Name ProcessJob -ScriptBlock {Get-Process} -MaxResultCount 12

The following command uses the MaxResultCount parameter of the Set-ScheduledJob cmdlet to increase the number of saved instance results to 15.

Get-ScheduledJob ProcessJob | Set-ScheduledJob -MaxResultCount 15

The following command deletes the execution history and all currently saved results of the ProcessJob scheduled job.

Get-ScheduledJob ProcessJob | Set-ScheduledJob -ClearExecutionHistory

The following command gets the values of the name and ExecutionHistoryLength properties of all scheduled jobs on the computer and displays them in a table.

Get-ScheduledJob | Format-Table -Property Name, ExecutionHistoryLength -AutoSize

SEE ALSO

about_Scheduled_Jobs about_Scheduled_Jobs_Troubleshooting about_Jobs

© 2017 Microsoft