Private/New-SpecScheduledTaskTrigger.ps1
|
Function New-SpecScheduledTaskTrigger { <# .SYNOPSIS This function creates a new scheduled task trigger based on the provided parameters. .DESCRIPTION The New-SpecScheduledTaskTrigger function creates a new scheduled task trigger based on the specified parameters. It supports different types of triggers such as "AtStartup," "AtLogon," and "Daily." .PARAMETER trigger Specifies the type of trigger to create: "AtStartup," "AtLogon," or "Daily." .PARAMETER time Specifies the time for the trigger (used with the "Daily" trigger type). .PARAMETER RandomiseTaskUpToXMinutes Specifies the number of minutes to randomly delay the task execution (used with the "Daily" trigger type). If you need over an hour please use minutes eg 78 (Equivalent to 1 hour 18 minutes) .PARAMETER DelayTaskUpToXMinutes Specifies the number of minutes to delay the task execution. If you need over an hour please use minutes eg 78 (Equivalent to 1 hour 18 minutes) .EXAMPLE $taskTrigger = New-SpecScheduledTaskTrigger -trigger "AtLogon" Creates a new scheduled task trigger that executes at user logon. .EXAMPLE $taskTrigger = New-SpecScheduledTaskTrigger -trigger "Daily" -time "02:00" -RandomiseTaskUpToXMinutes 30 Creates a new scheduled task trigger that executes daily at 2:00 AM and includes a random delay of up to 30 minutes. .EXAMPLE $taskTrigger = New-SpecScheduledTaskTrigger -trigger "Daily" -time "08:00" -DelayTaskUpToXMinutes 15 Creates a new scheduled task trigger that executes daily at 8:00 AM and includes a fixed delay of 15 minutes. .NOTES Author: owen.heaume Date: August 10, 2023 Version - 1.0 Initial Creation - 1.1 Added ability to Repeat the task every x minutes indefinitely Status Codes: - Successful assignment: Returns the created task trigger object. - Error occurred: Returns 911. #> [cmdletbinding()] param ( [string]$trigger, [datetime]$time, [int]$RandomiseTaskUpToXMinutes, [int]$DelayTaskUpToXMinutes, [int]$RepeatEveryXMinutes ) # Task Trigger try { Write-Verbose "Assigning Trigger settings" switch ($trigger) { 'AtStartup' { Write-Verbose "Selected trigger is: AtStartup"; $taskTrigger = New-ScheduledTaskTrigger -AtStartup -ea Stop -ev x } 'AtLogon' { Write-Verbose "Selected trigger is: AtLogon"; $taskTrigger = New-ScheduledTaskTrigger -AtLogOn -ea Stop -ev x } 'Daily' { Write-Verbose "Selected trigger is: Daily"; $taskTrigger = New-ScheduledTaskTrigger -Daily -At $time -ea Stop -ev x if ($RandomiseTaskUpToXMinutes) { # $randomDelay = New-TimeSpan -Minutes 0 -ea Stop -ev x $randomDelay = New-TimeSpan -Minutes $RandomiseTaskUpToXMinutes -ea stop $randomDelayString = 'PT' + $randomDelay.Hours.ToString('00') + 'H' + $randomDelay.Minutes.ToString('00') + 'M' + $randomDelay.Seconds.ToString('00') + 'S' $taskTrigger.RandomDelay = $randomDelayString Write-Verbose "A new time span: $($randomDelayString) has been set. ($randomiseTaskUpToXMinutes minutes)" } } } # Add a task delay if selected if ($DelayTaskUpToXMinutes) { $taskDelay = New-TimeSpan -Minutes $DelayTaskUpToXMinutes $delayTime = "PT" + $taskDelay.ToString('hh') + "H" + $taskDelay.ToString('mm') + "M" + $taskDelay.ToString('ss') + "S" $tasktrigger.delay = $delaytime Write-Verbose "A new time span: $($delayTime) has been set. ($DelayTaskUpToXMinutes minutes)" } # Repeat the task every x minutes indefinitely if ($RepeatEveryXMinutes) { # Modified Repetition Handling $repetitionPattern = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes $RepeatEveryXMinutes) # # RepetitionDuration is not needed for indefinite repetition $tasktrigger.Repetition = $repetitionPattern.Repetition } Write-Verbose "Trigger settings assigned successfully" return $taskTrigger } catch { Write-Warning "An error occured assigning the Trigger settings: $x" return 911 } } |