Public/New-SpecScheduledTask.ps1

Function New-SpecScheduledTask {
    <#
    .SYNOPSIS
    This function creates a new scheduled task with specified settings and options.
 
    .DESCRIPTION
    The New-SpecScheduledTask function creates a new scheduled task based on the provided parameters. It supports creating various types of tasks with different triggers, actions, principals, settings, and options.
 
    .PARAMETER Taskname
    Specifies the name of the scheduled task. If not provided, the leaf name of the specified path will be used.
 
    .PARAMETER Description
    Specifies the description of the scheduled task.
 
    .PARAMETER TaskFolder
    Specifies the folder in which the task will be created. Default is 'Specsavers'.
 
    .PARAMETER Path
    Specifies the path to the executable or script for the task action.
 
    .PARAMETER Arguments
    Specifies the arguments to be passed to the task action. (Do not use if it is a .ps1 file)
 
    .PARAMETER StartIn
    Specifies the working directory for the task action. (Do not use if it is a .ps1 file)
 
    .PARAMETER Trigger
    Specifies the trigger type for the task. Valid values are "AtLogon," "AtStartup," and "Daily."
 
    .PARAMETER RunAs
    Specifies the user account or security group to run the task as. Valid values are 'NT AUTHORITY\SYSTEM' and 'BUILTIN\Users'. Default is 'NT AUTHORITY\SYSTEM''.
 
    .PARAMETER DelayTaskByXMinutes
    Specifies the number of minutes to delay the task execution. e.g. 15 If you need to use over an hour, continue to use minutes, eg 68 (equivalent to 1 hour 8 minutes)
 
    .PARAMETER RunWithHighestPrivilege
    Indicates whether the task should be run with the highest privileges.
 
    .PARAMETER StartTaskImmediately
    Indicates whether to start the task immediately after creating it.
 
    .PARAMETER IgnoreTestPath
    Allows ignoring the path verification step. If the path does not exist then the scheduled task will still be created.
 
    .PARAMETER RandomiseTaskUpToXMinutes
    Specifies the number of minutes to randomly delay the task execution (used with the "Daily" trigger type). eg 30 If you need to use over an hour, continue to use minutes, eg 68 (equivalent to 1 hour 8 minutes)
 
    .PARAMETER Time
    Specifies the time for the trigger (used with the "Daily" trigger type). '04:00pm', '16:00', '3:12am' and '03:12' are all valid time values.
 
    .EXAMPLE
    $taskStatus = New-SpecScheduledTask -Description "My Task" -Path "C:\Scripts\MyScript.ps1" -Trigger "Daily" -Time "02:00" -RunWithHighestPrivilege -StartTaskImmediately
    Creates a new scheduled task named "My Task" that runs a PowerShell script daily at 2:00 AM with highest privileges and starts the task immediately.
 
    .EXAMPLE
    $taskStatus = New-SpecScheduledTask -Taskname "MyTask" -Description "My Task" -Path "C:\Program Files\MyApp.exe" -RunAs "NT AUTHORITY\SYSTEM" -DelayTaskByXMinutes 15 -IgnoreTestPath
    Creates a new scheduled task named "MyTask" that runs an executable with a 15-minute delay and ignores path verification.
 
    .NOTES
    Author: owen.heaume
    Date: August 10, 2023
    Version: 2.0
 
    .OUTPUTS
    Status Codes:
    - 901: Path does not exist and -IgnoreTestPath not used.
    - 900: Task already exists.
    - 910: An error occurred assigning task action configuration.
    - 911: An error occurred assigning task trigger configuration.
    - 912: An error occurred assigning task principal configuration.
    - 913: An error occurred assigning task settings configuration.
    - 914: An error occurred creating the task using Register-ScheduledTask.
    - 915: An error occurred starting the task using Start-ScheduledTask.
    - 916: Incorrect parameter combination ( -arguments or -Startin with .ps1 extension n path)
    - 917: Incorrect parameter combination (Do not use '-DelayTaskByXMinutes' with '-randomiseTaskUpToXminutes')
 
    - 0: Successful task creation.
    #>


    [cmdletbinding()]

    Param (
        [parameter (mandatory = $false)]
        [string]$Taskname,

        [parameter (mandatory = $true)]
        [string]$Description,

        [parameter (mandatory = $false)]
        [string]$TaskFolder = 'Specsavers',

        [parameter (mandatory = $true)]
        [string]$Path,

        [parameter (mandatory = $false)]
        [string]$Arguments,

        [parameter (mandatory = $false)]
        [string]$StartIn,

        [parameter (mandatory = $false)]
        [ValidateSet('AtLogon', 'AtStartup', 'Daily')]
        [string]$Trigger = 'AtStartUp',

        [parameter (mandatory = $false)]
        [ValidateSet('BUILTIN\Users', 'NT AUTHORITY\SYSTEM','BUILTIN\Administrators')]
        [string]$RunAs = 'NT AUTHORITY\SYSTEM',

        [parameter (mandatory = $false)]
        [int]$DelayTaskByXMinutes,

        [switch]$RunWithHighestPrivilege,

        [switch]$StartTaskImmediately,

        [switch]$IgnoreTestPath
    )

    DynamicParam {
        if ($Trigger -eq 'Daily') {
            # Define parameter attributes
            $paramAttributes = New-Object -Type System.Management.Automation.ParameterAttribute
            $paramAttributes.Mandatory = $true

            # Create collection of the attributes
            $paramAttributesCollect = New-Object -Type `
                System.Collections.ObjectModel.Collection[System.Attribute]
            $paramAttributesCollect.Add($paramAttributes)

            # Create parameter with name, type, and attributes
            $dynParam1 = New-Object -Type `
                System.Management.Automation.RuntimeDefinedParameter("RandomiseTaskUpToXMinutes", [int], $paramAttributesCollect)
            $dynParam2 = New-Object -Type `
                System.Management.Automation.RuntimeDefinedParameter("Time", [string], $paramAttributesCollect)

            # Add parameter to parameter dictionary and return the object
            $paramDictionary = New-Object -Type System.Management.Automation.RuntimeDefinedParameterDictionary
            $paramDictionary.Add("RandomiseTaskUpToXMinutes", $dynParam1)
            $paramDictionary.Add("Time", $dynParam2)
            return $paramDictionary
        }
    }

    Begin {
        # Assign dynamic parameters to variables so they can be tested if they were used later in the script.
        $RandomiseTaskUpToXMinutes = $PSBoundParameters['RandomiseTaskUpToXMinutes']
        $Time = $PSBoundParameters['Time']

    }

    Process {
        # check parameters combinations are valid
        if ((Test-SpecPS1Extension -filePath $path -verbose:$false) -and ($Arguments -or $StartIn)) {
            Write-warning "Please do not use '-Arguments' or '-StartIn' when the path contains a PowerShell (.ps1) script"
            return 916
        }

        if ($Trigger -eq 'Daily' -and $RandomiseTaskUpToXMinutes -and $DelayTaskByXMinutes) {
            Write-warning "Please do not use '-DelayTaskByXMinutes' with '-randomiseTaskUpToXminutes'"
            return 917
        }

        # Path check
        $pathExists = Test-Path $Path -PathType Leaf

        if ($IgnoreTestPath) {
            Write-Verbose "Skipping path verification due to -IgnoreTestPath switch"
        }

        if ($pathExists -eq $false -and $IgnoreTestPath -eq $false) {
            Write-Warning "The path $path does not exist. Please use the -IgnoreTestPath switch to override this error."
            return 901
        }

        # If -TaskName was not used, then get the leaf name of the path to use instead
        if ([string]::IsNullOrEmpty($taskname)) {
            $TaskName = Get-SpecLeafName -Path $Path
        }

        # Check if the task already exists
        $TaskExists = Get-SpecScheduledTask -TaskName $TaskName

        if ($TaskExists -eq 900) {
            # 900 is the error code for the Get-SpecScheduledTask function
            Write-Warning "The task $TaskName already exists. Please use a different name."
            return 900
        }

        # Create the scheduled task action
        $taskAction = New-SpecScheduledTaskAction -IsPs1Script (Test-SpecPS1Extension -filePath $Path) -path $Path -arguments $Arguments -startin $StartIn

        if ($TaskAction -eq 910) {
            # 910 is the error code for the New-SpecScheduledTaskAction function
            Write-Warning "New-SpecScheduledTaskAction: Task Action configuration could not be assigned."
            return 910
        }

        # Create the task trigger
        if ($Trigger -eq 'daily') {
            Write-Verbose "The '-daily' trigger has been selected"
            $taskTrigger = New-SpecScheduledTaskTrigger -trigger $Trigger -time $Time -RandomiseTaskUpTo $RandomiseTaskUpToXMinutes
        } else {
            $taskTrigger = New-SpecScheduledTaskTrigger -trigger $Trigger -DelayTaskUpToXMinutes $DelayTaskByXMinutes
        }

        if ($taskTrigger -eq 911) {
            # 911 is the error code for the New-SpecScheduledTaskTrigger function
            Write-Warning "New-SpecScheduledTaskTrigger: Trigger configuration could not be assigned."
            return 911
        }

        # Set the task run level
        if ($RunWithHighestPrivilege.IsPresent) {
            Write-Verbose "The '-RunWithHighestPrivilege' switch has been selected"
            $taskPrincipal = New-SpecScheduledTaskPrincipal -RunAs $RunAs -RunWithHighestPrivilege
        } else {
            $taskPrincipal = New-SpecScheduledTaskPrincipal -RunAs $RunAs
        }

        if ($taskPrincipal -eq 912) {
            # 912 is the error code for the New-SpecScheduledTaskPrincipal function
            Write-Warning "New-SpecScheduledTaskPrincipal: Task principal could not be assigned."
            return 912
        }

        # Set the task settings
        $taskSettings = New-SpecScheduledTaskSettingsSet

        if ($taskSettings -eq 913) {
            # 913 is the error code for the New-SpecScheduledTaskSettingsSet function
            Write-Warning "New-SpecScheduledTaskSettingsSet: Task settings could not be assigned."
            return 913
        }

        # Create the scheduled task
        $params = @{
            TaskName    = $TaskName
            Description = $Description
            TaskPath    = "\$TaskFolder"
            Action      = $taskAction
            Trigger     = $taskTrigger
            Principal   = $taskPrincipal
            Settings    = $taskSettings
        }

        $result = Create-SpecScheduledTask @params

        if ($result -eq 914) {
            Write-Warning "Create-SpecScheduledTask: An error occured creating the task."
            return 914
        }

        # Start the task immediately if the -StartTaskImmediately switch was used
        if ($StartTaskImmediately.IsPresent) {
            try {
                write-verbose "Starting task $TaskName"
                Start-ScheduledTask -TaskName $TaskName -TaskPath "\$TaskFolder" -ea stop -ev x
                write-verbose "Task $TaskName started successfully."
            } catch {
                Write-Warning "Start-ScheduledTask: An error occured starting the task: $x"
                return 915
            }
        }

        #write-verbose "Task $TaskName created successfully."
        return 0
    }
}