Projects Level: Advanced Chapter 18: PowerShell Automation Projects

Schedule and run it safely

A scheduled task runs your tool at a set time without you typing the command. You build it from an action and a trigger, test it on demand, and log its output to a file you can check.

Lesson 3 of 4 in Chapter 18: PowerShell Automation Projects. Previous step in this path: Build a report module. 3 learning objectives, 5 examples, and a knowledge check.

Start: what you will learn

A scheduled task runs your tool at a set time without you typing the command. You build it from an action and a trigger, test it on demand, and log its output to a file you can check.

Learning objectives

  • Create a scheduled task with an action and a trigger
  • Test the task on demand
  • Log the task output to a file

Concept in simple words

What it is: A scheduled task is a job that Windows runs for you at a set time or on a set event. An action is what the task runs, such as a PowerShell command or script. A trigger is when the task runs, such as daily at a set time. Logging the output means saving what the tool printed to a file, so you can check the run later even if you were not watching.

Why it works

Why it exists: A report that only runs when you remember it will be missed sooner or later. People get busy, days slip by, and a weekly report quietly stops. A schedule makes the run reliable, because the computer starts the job at the agreed time. A log file makes the run checkable, because you can open the log afterwards and see what ran, what it found, and whether it failed.

What Task Scheduler does behind the command: Task Scheduler is the Windows service that stores task definitions and watches their triggers. When a trigger time arrives, it starts the action you registered. It does not run your typed commands from your session. It runs the program and arguments you stored in the action, in its own run, so the action must be complete on its own, with full paths where needed, and it must not depend on you being at the keyboard.

What the building blocks really are: New-ScheduledTaskAction and New-ScheduledTaskTrigger do not create a task yet. They create objects in memory, one for what runs and one for when it runs. Register-ScheduledTask is the step that saves those objects as a real task under a task name. Start-ScheduledTask runs that saved task at once, for testing, without changing its trigger. That split is helpful, because you can build the parts, check them, and only then save them.

What the action runs, in plain words: In this chapter, the action runs powershell.exe, which is the Windows PowerShell program, with an argument that names a script file. The argument -File .\Run-Report.ps1 tells PowerShell to run that script file instead of waiting for typed commands. The argument -NoProfile tells PowerShell to skip loading your profile, so the scheduled run is cleaner and does not depend on personal profile settings. Keep the action simple, so a failure is easy to trace to one program and one script.

Think of it like this

Think of it like this: A scheduled task is like an alarm clock with a job attached. The trigger is the alarm time, the action is the job the alarm starts, and the log file is the note left behind saying the job ran and what it found. If the alarm rings but no note is left, you cannot tell if the job ran well, ran badly, or did not run at all, so the log is part of the job, not an extra.

How it works, step by step

How it works, step by step, in order: First, write the script and run it by hand, and check its output. Second, add logging to the script, so each run writes its result to a file you can open later. Third, build an action with full paths for the program and the script. Fourth, build a trigger for the rhythm you need. Fifth, register the task with a clear name and a short description. Sixth, test it on demand with Start-ScheduledTask. Seventh, check the log file and the task info. Only then should you leave the task to run on its own schedule.

How to build a safe action: Use a full path for the script file, not only a relative path, because a scheduled run does not start in the same folder as your interactive session. If the script uses other files, give those files full paths too, or set the working folder for the action on purpose, so relative paths resolve where you expect. Test the exact action you registered, not a similar command typed by hand, because a small difference in path or argument is often the cause of a scheduled failure.

How to choose a trigger: A daily trigger runs once each day at a set time, which fits a daily report. A weekly trigger runs on chosen days of the week, which fits a weekly report. A once trigger runs a single time, which fits a one time check. A startup trigger runs when the computer starts, and a logon trigger runs when a user signs in. Pick the rhythm that matches the job, not the most frequent rhythm you can think of, because a report nobody reads is just noise.

How to register with a clear name and description: The task name is how you will find the task later, so make it specific, such as Daily Report, rather than vague, such as My Task. A short description helps too, because it says in plain words what the report does and why it exists. When you register a task with a name that already exists, PowerShell will ask about replacing it, and -Force tells it to replace the old task without asking, so use -Force only when you are sure you mean to replace that task.

Let us walk through the first example, part by part: In $action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-File .\Run-Report.ps1", New-ScheduledTaskAction builds the action, -Execute names the program, and -Argument passes the script file to run. In $trigger = New-ScheduledTaskTrigger -Daily -At "08:00", -Daily sets a daily rhythm, and -At sets the time to eight in the morning. In Register-ScheduledTask -TaskName "Daily Report" -Action $action -Trigger $trigger, -TaskName names the saved task, -Action supplies what runs, and -Trigger supplies when it runs.

What to look for in the output, and what changes if you change one part: The output shows TaskName and State, with Daily Report and Ready. Ready means the task is registered and waiting for its trigger, not that it is running right now. If you change 08:00 to another time, the next run moves to that time. If you change -Daily to a weekly trigger, the rhythm changes, and you must also say which days it runs on. If the script path is wrong, the task may register fine but fail when it runs, which is why an on demand test matters so much.

Let us walk through the on demand test, part by part: Start-ScheduledTask -TaskName "Daily Report" tells Task Scheduler to start that saved task at once, instead of waiting for its trigger. -TaskName names the task to test, so spelling matters, and the name must match the registered name exactly. After the test, check the log file and the task info. A test that you do not check is only half a test, because it proves the task started, but not that the report was correct.

Let us walk through the task info check, part by part: Get-ScheduledTask -TaskName "Daily Report" gets the saved task definition, including its state. Piping it to Get-ScheduledTaskInfo adds run time facts, such as LastRunTime, LastTaskResult, NextRunTime, and NumberOfMissedRuns. Select-Object then keeps only those facts, so the result is easy to read. LastRunTime tells you when the task last ran. A LastTaskResult of 0 points to success, while another value points to a problem worth checking. NextRunTime tells you when the next run is due.

Let us walk through the weekly example, part by part: The action uses a full path for the script, so the scheduled run does not depend on a starting folder. -Weekly sets a weekly rhythm, -DaysOfWeek Monday says the task runs on Mondays, and -At "08:00" sets the time. -Description adds a short plain words note about what the report does. If you change Monday to Friday, the next run moves to Friday. If you change the full path, the task will look for the script in the new place, so check that the file really is there.

Let us walk through the log check, part by part: Get-Content -Path .\report-log.txt -Tail 20 reads the log file, and -Tail 20 keeps only the last 20 lines, so you see the most recent run without reading the whole file. Look for the date of the run, the report result, and any error or warning lines. If the log file is missing, the script may not have written a log at all, or it may have written it to a different folder, and both cases need fixing before the next scheduled run.

How to clean up a test task safely: When you no longer need a test task, remove it with Unregister-ScheduledTask, using the exact task name, after you have checked with Get-ScheduledTask that you have the right task. Removing a test task keeps your task list tidy, and it stops a test report from running after you have moved on. Never remove a task by guessing its name. Check first, then remove, and confirm the list afterwards.

When to use it

When to use it, and when not to: Schedule a tool when the job repeats on a fixed rhythm and its output should be checked later. Do not schedule a tool that has not been tested on demand. Do not schedule a changing or deleting tool without a log file and a review step. A silent scheduled change is hard to trace, and a silent scheduled delete is worse, because the change may run many times before anyone notices.

Safety checks for every scheduled tool: Test the tool on small, safe data first, on your own computer, and back up anything it might change, before you schedule it. Do not put passwords or secrets in task arguments, because arguments can be seen in the task definition. Test the task under the same conditions it will run under, with the same files and folders, and read the first few scheduled logs by hand, even if the first on demand test looked fine.

Worked examples

Read each example in order. Each one explains its parts, then shows what to look for in the output.

Syntax

Syntax
New-ScheduledTaskAction -Execute <program> -Argument <args>

Example 1

New-ScheduledTaskAction builds what runs, with -Execute naming the program and -Argument passing the script. New-ScheduledTaskTrigger builds when it runs, daily at eight in the morning. Register-ScheduledTask joins them under the task name Daily Report. Look for State Ready to confirm the task is saved and waiting.

Example 1
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-File .\Run-Report.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At "08:00"
Register-ScheduledTask -TaskName "Daily Report" -Action $action -Trigger $trigger

Illustrative output: TaskName State -------- ----- Daily Report Ready

Example 2

Start-ScheduledTask runs a task at once, instead of waiting for its trigger. The -TaskName parameter names the task to test, so you can prove it works before its first scheduled run. After this command, check the log file, because starting the task alone does not prove the report was correct.

Example 2
Start-ScheduledTask -TaskName "Daily Report"

Illustrative output: Task Daily Report started.

Example 3

Get-ScheduledTask gets the saved task. Get-ScheduledTaskInfo adds run time facts, such as when it last ran and what the last result was. Select-Object keeps only the facts you need to read. Look at LastRunTime first, then LastTaskResult, where 0 points to success, then NextRunTime for the next due run.

Example 3
Get-ScheduledTask -TaskName "Daily Report" | Get-ScheduledTaskInfo | Select-Object TaskName, LastRunTime, LastTaskResult, NextRunTime

Illustrative output: TaskName LastRunTime LastTaskResult NextRunTime -------- ----------- -------------- ----------- Daily Report 2026-11-03 08:00:00 0 2026-11-04 08:00:00

Example 4

This action uses a full path for the script, so the scheduled run does not depend on a starting folder. -NoProfile skips profile loading for a cleaner run. The weekly trigger runs on Mondays at eight in the morning. -Description adds a plain words note about the job. If you change Monday to another day, the next run moves with it.

Example 4
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -File C:\Tools\Run-Report.ps1"
$trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At "08:00"
Register-ScheduledTask -TaskName "Weekly Report" -Action $action -Trigger $trigger -Description "Weekly service report on Mondays"

Illustrative output: TaskName State -------- ----- Weekly Report Ready

Example 5

Get-Content reads a text file, and -Tail 20 keeps only the last 20 lines, so you see the most recent run. Look for the run date, the report result, and any error lines. If the file is missing, the script may have written its log to a different folder, or it may not log at all, and you should fix that before the next run.

Example 5
Get-Content -Path .\report-log.txt -Tail 20

Illustrative output: 2026-11-03 08:00:00 Report started. 2026-11-03 08:00:05 Report finished. Rows written: 2.

Nothing on this page executes PowerShell code. The outputs above are illustrative only.

Common mistakes and troubleshooting

Read these before you try the examples, so you can spot the same problems in your own work.

  • Registering a task without testing it on demand, then finding a mistake only after a missed scheduled run.
  • Forgetting to log the output, so a failed run leaves no trace to check.
  • Using a vague task name, so later you cannot tell which task produced which report.
  • Using a relative script path in the action, so the scheduled run looks for the script in the wrong folder and fails.
  • Testing the script by hand in your own session, but never testing the exact registered action, so a path or argument difference stays hidden.
  • Checking that the task started, but never reading the log or the task info, so a report with wrong rows looks like a success.
  • Reusing a task name with -Force without checking which old task you are replacing.
  • Scheduling a tool that changes or deletes data before you have tested it by hand, logged its output, and reviewed what it will change.

Knowledge check

Knowledge check

Which cmdlet runs a scheduled task at once for testing?

Pick one answer. Feedback appears right away, and you can try again.

Remember this and next step

Remember this: An action says what runs, a trigger says when it runs, Register-ScheduledTask saves them under a clear name, Start-ScheduledTask tests the task on demand, Get-ScheduledTaskInfo shows when it last ran and what happened, and a log file lets you check every run afterwards. A scheduled tool is finished only when it has been tested, logged, and checked, not merely when it has been registered.

Next step: Handle errors and finish