Skip to content

Instantly share code, notes, and snippets.

@raandree
Created January 13, 2025 18:39
Show Gist options
  • Save raandree/48bfab7b916772f9c1007a87ebc63802 to your computer and use it in GitHub Desktop.
Save raandree/48bfab7b916772f9c1007a87ebc63802 to your computer and use it in GitHub Desktop.
This script registers a scheduled job to run the specified script on a schedule. It can register the job to run as local system or as the user who called this script.
<#
.SYNOPSIS
Registers a scheduled job to run the specified script on a schedule.
.DESCRIPTION
This script registers a scheduled job to run the specified script on a schedule. It can register the
job to run as local system or as the user who called this script.
.PARAMETER At
The time at which the job should be triggered. The format is 24 hours like 21:00.
.PARAMETER ScriptPath
The full path to the script.
.PARAMETER ScriptBlock
The script block to be executed.
.PARAMETER ArgumentList
If the script to be called by the scheduled job has parameters, you can pass them by means of the
ArgumentList parameter.
.PARAMETER JobName
This defines the name of the scheduled job in the task scheduler.
.PARAMETER RunAsLocalSystem
The task will run as the local machine account.
.PARAMETER Force
When set and if there is a scheduled job with the same name already existing, it will be overwritten.
.PARAMETER ExecutionHourTimeLimit
Can be used to set the execution time limit of the scheduled task. The value is in hours.
.PARAMETER RunNow
When set, the scheduled job will be started immediately.
.PARAMETER ReceiveData
When set, the output of the scheduled job will be received.
.EXAMPLE
& '.\Register-ScheduledTask2.ps1' -At 21:00 -ScriptPath 'D:\AD Backup Transfer\Copy-Backup.ps1' -ArgumentList \\dscfile01\Backup -RunAsLocalSystem -Force
This example registers a scheduled job to run the script 'C:\AD Backup Transfer\Start-Backup.ps1' to copy
Windows Backup data to the UNC path '\\dscfile01\Backup' at 21:00. It will run as the local system account.
#>
param (
[Parameter(Mandatory)]
[ValidatePattern('^(?:[01]?\d|2[0-3])(?::[0-5]\d){1,2}$')]
[string]$At,
[Parameter(Mandatory, ParameterSetName = 'Script')]
[ValidateScript({ Test-Path -Path $_ })]
[string]$ScriptPath,
[Parameter(Mandatory, ParameterSetName = 'ScriptBlock')]
[scriptblock]$ScriptBlock,
[Parameter()]
[object[]]$ArgumentList,
[Parameter()]
[string]$JobName = (New-Guid),
[Parameter()]
[switch]$RunAsLocalSystem,
[Parameter()]
[int]$ExecutionHourTimeLimit,
[Parameter()]
[switch]$RunNow,
[Parameter()]
[switch]$ReceiveData,
[Parameter()]
[switch]$Force
)
$trigger = New-JobTrigger -Daily -At $At
$accountId = 'NT AUTHORITY\SYSTEM'
$principal = New-ScheduledTaskPrincipal -UserId $accountId -LogonType ServiceAccount -RunLevel Highest
$psJobsPathInScheduler = '\Microsoft\Windows\PowerShell\ScheduledJobs'
$job = Get-ScheduledJob -Name $JobName -ErrorAction SilentlyContinue
if ($job -and $Force) {
Write-Verbose "Removing the old job with the name '$JobName' in path '$psJobsPathInScheduler'."
$job | Unregister-ScheduledJob -Confirm:$false
}
elseif ($job) {
Write-Error "A job with the name '$JobName' in path '$psJobsPathInScheduler' does already exsit."
return
}
$param = @{
Name = $JobName
Trigger = $trigger
}
if ($ArgumentList) {
$param.Add('ArgumentList', $argumentList)
}
if ($ScriptPath)
{
$param.Add('ScriptPath', $scriptPath)
}
if ($ScriptBlock)
{
$param.Add('ScriptBlock', $ScriptBlock)
}
$job = Register-ScheduledJob @param
if ($RunAsLocalSystem) {
Set-ScheduledTask -TaskPath $psJobsPathInScheduler -TaskName $JobName -Principal $principal | Out-Null
}
if ($ExecutionHourTimeLimit) {
$task = Get-ScheduledTask -TaskPath "$psJobsPathInScheduler\" -TaskName $JobName
$task.Settings.ExecutionTimeLimit = "PT$($ExecutionHourTimeLimit)H"
$task | Set-ScheduledTask | Out-Null
}
if ($RunNow)
{
$job = $job | Set-ScheduledJob -RunNow -PassThru
Start-Sleep -Seconds 1
if ($ReceiveData)
{
Get-Job -Name $job.Name | Receive-Job -Wait -AutoRemoveJob
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment