We want to create a new scheduled task, so New-ScheduledTask seems like a grand place to start.
PS C:\> help new-scheduledtask -full NAME
New-ScheduledTask SYNTAX
New-ScheduledTask [[-Action] <CimInstance#MSFT_TaskAction[]>] [[-Trigger] <CimInstance#MSFT_TaskTrigger[]>] [[-Settings] <CimInstance#MSFT_TaskSettings>] [[-Principal]
<CimInstance#MSFT_TaskPrincipal>] [[-Description] <string>] [-CimSession <CimSession[]>] [-ThrottleLimit <int>] [-AsJob] [<CommonParameters>]
There don’t appear to be any mandatory parameters here, but the help suggests that -Trigger will be how we specify when the task should run, -Action will be what the task does, and we can probably ignore everything else. The help file indicates that those parameters each take an object as input—a TaskTrigger and TaskAction object, respectively. So we need to figure out how to make those objects. We could just read the examples at the end of the help, but let’s make this challenging and not do so for now.
Fortunately, we still have that list of commands from the ScheduledTasks module, and the list includes a New-ScheduledTaskTrigger and a New-ScheduledTaskAction command. Hopefully you can see where this is going:
PS C:\> help New-ScheduledTaskTrigger NAME
New-ScheduledTaskTrigger SYNOPSIS
SYNTAX
New-ScheduledTaskTrigger [-RandomDelay <TimeSpan>] [-At] <DateTime> -Once [<CommonParameters>]
New-ScheduledTaskTrigger [-DaysInterval <Int32>] [-RandomDelay <TimeSpan>] [-At] <DateTime> -Daily [<CommonParameters>] New-ScheduledTaskTrigger [-WeeksInterval <Int32>] [-RandomDelay <TimeSpan>] [-At] <DateTime> -DaysOfWeek <DayOfWeek[]> -Weekly [<CommonParameters>]
New-ScheduledTaskTrigger [-RandomDelay <TimeSpan>] [[-User] <String>] -AtLogOn [<CommonParameters>]
New-ScheduledTaskTrigger [[-RandomDelay] <TimeSpan>] -AtStartup [<CommonParameters>]
Well, we don’t want any random stuff. The second parameter set has mandatory -Daily and -At parameters, and that seems promising. Let’s see if we can quickly cre- ate a trigger using those:
PS C:\> New-ScheduledTaskTrigger -daily -at 0300
WARNING: column "Enabled" does not fit into the display and was removed Id Frequency Time DaysOfWeek
-- --- ---- --- 0 Daily 1/1/0001 12:00:00 AM
No, not quite right. It didn’t like our time format because it created it for midnight. Let’s try again:
PS C:\> New-ScheduledTaskTrigger -daily -at '3:00 am'
WARNING: column "Enabled" does not fit into the display and was removed. Id Frequency Time DaysOfWeek
-- --- ---- --- 0 Daily 4/18/2012 3:00:00 AM
There we go. So that’s the command to create the trigger we want. Excellent. Notice that both attempts produced a trigger with ID 0, and that there’s no command in the module to “Get-ScheduledTaskTrigger,” so that suggests that PowerShell isn’t tracking these things in memory. The command produces a trigger, and doesn’t store it. Good to know—and it shows the importance of looking at each piece of data (even a lowly
ID number) and thinking about what it might mean. Now for the action:
PS C:\> help New-ScheduledTaskAction NAME
New-ScheduledTaskAction SYNTAX
New-ScheduledTaskAction [-Execute] <string> [[-Argument] <string>] [[-WorkingDirectory] <string>] [-Id <string>] [-CimSession
<CimSession[]>] [-ThrottleLimit <int>] [-AsJob] [<CommonParameters>]
We have played with scheduled tasks in the GUI before, so we know that -WorkingDirectory sets the folder in which the task runs. -Argument probably passes command-line arguments to whatever we’re running, so we’re going to guess that -Execute specifies whatever it is we want to run. Let’s give it a shot:
PS C:\> New-ScheduledTaskAction -Execute 'dir'
Id : Arguments : Execute : dir WorkingDirectory : PSComputerName :
Yeah, okay, seems plausible. Let’s try the entire thing:
PS C:\> New-ScheduledTask -Action (New-ScheduledTaskAction -Execute 'Get-Pr intJob -printer "Accounting"') -Trigger (New-ScheduledTaskTrigger -daily -at '3:00 am') -Description "Reset accounting printer daily at 3am"
But having run that, we’re not seeing anything in the Task Scheduler GUI (once we eventually found it in the new “Metro” Start screen, of course). Rats. Back to the com- mand list for the module:
PS C:\> gcm -Module scheduledtasks Capability Name --- ---- CIM Get-ClusteredScheduledTask CIM Get-ScheduledTask CIM Get-ScheduledTaskInfo CIM New-ScheduledTask CIM New-ScheduledTaskAction CIM New-ScheduledTaskPrincipal CIM New-ScheduledTaskSettingsSet Cmdlet, Script New-ScheduledTaskTrigger CIM Register-ClusteredScheduledTask CIM Register-ScheduledTask CIM Set-ClusteredScheduledTask CIM Set-ScheduledTask CIM Start-ScheduledTask CIM Stop-ScheduledTask CIM Unregister-ClusteredScheduledTask CIM Unregister-ScheduledTask
Hmm. There’s that Register-ScheduledTask, which is starting to look interesting. “New” usually means “make something,” but maybe we have to also “register” the new task in order for Windows to realize it exists.
NAME
Register-ScheduledTask SYNTAX
Register-ScheduledTask [-TaskName] <string> [[-TaskPath] <string>] [-Action] <CimInstance#MSFT_TaskAction[]> [[-Trigger]
<CimInstance#MSFT_TaskTrigger[]>] [[-Settings]
<CimInstance#MSFT_TaskSettings>] [[-User] <string>] [[-Password] <string>] [[-RunLevel] <RunLevelEnum> {Limited | Highest}] [[-Description] <string>] [-Force] [-CimSession <CimSession[]>] [-ThrottleLimit <int>] [-AsJob] [<CommonParameters>]
Looks really similar to New-ScheduledTask, only with more. This, for example, has a -TaskName parameter, where we could presumably give our task a name—that makes sense. We’re also seeing -User and -Password, which we’d expected to see on a sched- uled task. Okay, let’s try this instead:
PS C:\> Register-ScheduledTask -TaskName "ResetAccountingPrinter" -Descript ion "Resets the Accounting print queue at 3am daily" -Action (New-Scheduled TaskAction -Execute 'Get-PrintJob -printer "Accounting"') -Trigger (New-Sch eduledTaskTrigger -daily -at '3:00 am')
WARNING: column "State" does not fit into the display and was removed. TaskPath TaskName
--- ---
Well, that looks like it did something. Back to the GUI where—as shown in figure 12.1— our task exists. SWEET! Sorry... we get excited when these things finally work.
Awesome. We feel like superheroes right now. But the point isn’t that we got it done—the point is that we figured out how to get it done. And we really, truly did, too. When we sat down to write this chapter we deliberately picked a task we’d been told was possible but had never done before. You’ve seen every bit of exploration and error that went along with our learning and discovery process.