Export (0) Print
Expand All

about_Scheduled_Jobs_Advanced

Updated: May 8, 2014

Applies To: Windows PowerShell 3.0, Windows PowerShell 4.0

TOPIC
    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



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft