Summary: Microsoft Scripting Guy, Ed Wilson, talks about troubleshooting Windows PowerShell scheduled jobs.
Microsoft Scripting Guy, Ed Wilson, is here. This has been an awesome week at TechEd 2014 in Houston. I can avoid the "Houston we have a problem" joke for the simple reason that the Scripting Wife and I are on our way home to Charlotte, N.C. We saw a tremendous number of Windows PowerShell fans this week, and I can tell you that being the Scripting Guy is a lot of fun when representing a technology as awesome as Windows PowerShell. I mean, dude (or dudette), Windows PowerShell rocks, and it helps solve some difficult problems.
There were three Windows PowerShell resources that I was excited to talk to people about when they came to the Scripting Guys booth at TechEd:
Check them out. All three of these resources can help make your life easier and better. Of course, there is the Hey, Scripting Guy! Blog—but hey, you are already here.
Today I want to talk a bit about troubleshooting scheduled jobs. Here are some things to help you when you have to troubleshoot.
Import the module
To get the results of a Windows PowerShell scheduled job, you use the Get-Job cmdlet. But if you use that cmdlet and it shows no results from any scheduled jobs, don’t panic. It probably means that you have not imported the PSScheduledJob module.
Often I do not need to import it because it automatically loads when I use any cmdlet from the module, such as Get-ScheduledJob. But if I open a fresh Windows PowerShell console and immediately type Get-Job, I might not see the results I want. So remember, first import the module as shown here (ipmo is an alias for Import-Module):
ipmo PSScheduledJob
Look in the scheduled job Output directory
If you are not finding the results you seek, it is time to look in the scheduled job Output directory. This is located at the following path:
home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJob
On my computer, this resolves to the following:
C:\Users\ed\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs
Under ScheduledJobs, you will find a folder for the scheduled job and an Output folder as shown in the following image:
In the Output folder, there should be a results.xml file and a time-stamped folder for each execution of the scheduled job. If someone clears the job history, these folders are deleted. If there are no folders and XML files in the output directory, the job results cannot be displayed.
Use –Keep with Receive-Job
To receive the results from a scheduled job (assuming you do not write to an output file or some other file on a disk storage mechanism), you use the Receive-Job cmdlet, like for any other Windows PowerShell job.
But if you use Receive-Job and nothing comes back, it is possible that you have (or someone else has) already used Receive-Job to receive the output, and the –Keep parameter was not used. As a best practice, I always use –Keep with Receive-Job to keep myself from inadvertently deleting the job output.
Check the ExecutionHistoryLength value
If job results are still not forthcoming for a job, it is possible that the number of job instances exceeds the ExecutionHistoryLength value for that particular job. The default value for a Windows PowerShell scheduled job is 32. To double-check to see what this value is, you can use the following command:
(Get-ScheduledJob getservice).ExecutionHistoryLength
Note Yesterday I talked about setting this value in Advanced PowerShell Scheduled Jobs.
Check if Start-Job was used
The Windows PowerShell scheduled job may have been executed (immediately) by using Start-Job. Start-Job runs a normal Windows PowerShell background job, and the execution history and results are not stored to a disk.
Check if the job is disabled
If a Windows PowerShell scheduled job does not run, it might be disabled. By default, all newly created Windows PowerShell scheduled jobs are enabled. But it might have been created as disabled, or it might have been disabled at a later date.
Use the Get-ScheduledJob cmdlet to see if the scheduled job is enabled. The Disable-ScheduledJob cmdlet disables a Windows PowerShell scheduled job, and the Enable-ScheduledJob cmdlet enables a scheduled job. The following command illustrates enabling a scheduled job:
Get-ScheduledJob | Enable-ScheduledJob
The following image shows checking and enabling a scheduled job:
Check if the job failed
It is possible that the scheduled job failed. To see if it failed, use the Get-WinEvent cmdlet, for example:
Get-WinEvent -LogName Microsoft-Windows-TaskScheduler/Operational |
Where {$_.Message -like "*fail*"}
Check the permissions
Permissions are one common cause for scheduled jobs failing. Scheduled jobs run with the permissions of the user who created the job or the permissions of the user who is specified by the Credential parameter in the Register-ScheduledJob or Set-ScheduledJob command. If that user does not have permissions to run the commands, the job fails.
That is all there is to troubleshooting Windows PowerShell scheduled jobs. Join me tomorrow when I will have a guest post about Best Practices for enterprise Windows PowerShell scripting.
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