Carbon.DSC

1.0.0

Modules/Carbon.ScheduledTasks/1.0.0/Carbon.ScheduledTasks.psm1

# Copyright WebMD Health Services
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

using namespace System.Collections.Generic;

#Requires -Version 5.1
Set-StrictMode -Version 'Latest'

# Functions should use $moduleRoot as the relative root from which to find
# things. A published module has its function appended to this file, while a
# module in development has its functions in the Functions directory.
$script:moduleRoot = $PSScriptRoot

$psModulesRoot = Join-Path -Path $script:moduleRoot -ChildPath 'Modules' -Resolve
Import-Module -Name (Join-Path -Path $psModulesRoot -ChildPath 'Carbon.Core' -Resolve) `
              -Function @('Add-CTypeData') `
              -Verbose:$false
Import-Module -Name (Join-Path -Path $psModulesRoot -ChildPath 'Carbon.Accounts' -Resolve) `
              -Function @('Resolve-CIdentityName') `
              -Verbose:$false
Import-Module -Name (Join-Path -Path $psModulesRoot -ChildPath 'Carbon.Security' -Resolve) `
              -Function @('Grant-CPrivilege') `
              -Verbose:$false

enum Carbon_ScheduledTasks_Month
{
    January = 1
    February
    March
    April
    May
    June
    July
    August
    September
    October
    November
    December
}

enum Carbon_ScheduledTasks_WeekOfMonth
{
    First = 1
    Second
    Third
    Fourth
    Last
}

enum Carbon_ScheduledTasks_ScheduleType
{
    Unknown
    Minute
    Hourly
    Daily
    Weekly
    Monthly
    Once
    OnLogon
    OnStart
    OnIdle
    OnEvent
    Registration
    SessionStateChange
    OnDemand
}

class Carbon_ScheduledTasks_ScheduleInfo
{
    Carbon_ScheduledTasks_ScheduleInfo()
    {
    }

    [int[]] $Days
    [DayOfWeek[]] $DaysOfWeek
    [TimeSpan] $Delay
    [DateTime] $EndDate
    [TimeSpan] $EndTime
    [String] $EventChannelName
    [int] $IdleTime
    [int] $Interval
    [int] $LastResult
    [String] $Modifier
    [Carbon_ScheduledTasks_Month[]] $Months
    [String] $RepeatEvery
    [String] $RepeatStopIfStillRunning
    [String] $RepeatUntilDuration
    [String] $RepeatUntilTime
    [bool] $StopAtEnd
    [String] $StopTaskIfRunsXHoursandXMins
    [Carbon_ScheduledTasks_ScheduleType] $ScheduleType
    [DateTime] $StartDate
    [TimeSpan] $StartTime

}

class Carbon_ScheduledTasks_TaskInfo
{
    Carbon_ScheduledTasks_TaskInfo(
        [String] $hostName, [String] $path, [String] $name, [String] $nextRunTime, [String] $status,
        [String] $logonMode, [String] $lastRunTime, [String] $author, [DateTime] $createDate, [String] $taskToRun,
        [String] $startIn, [String] $comment, [String] $scheduledTaskState, [String] $idleTime,
        [String] $powerManagement, [String] $runAsUser, [bool] $interactive, [bool] $noPassword,
        [bool] $highestAvailableRunLevel, [String] $deleteTaskIfNotRescheduled)
    {
        $this.HostName = $hostName;
        $this.TaskPath = $path;
        $this.TaskName = $name;
        $this.NextRunTime = $nextRunTime;
        $this.Status = $status;
        $this.LogonMode = $logonMode;
        $this.LastRunTime = $lastRunTime;
        $this.Author = $author;
        $this.CreateDate = $createDate;
        $this.TaskToRun = $taskToRun;
        $this.StartIn = $startIn;
        $this.Comment = $comment;
        $this.ScheduledTaskState = $scheduledTaskState;
        $this.IdleTime = $idleTime;
        $this.PowerManagement = $powerManagement;
        $this.RunAsUser = $runAsUser;
        $this.Interactive = $interactive;
        $this.NoPassword = $noPassword;
        $this.HighestAvailableRunLevel = $highestAvailableRunLevel;
        $this.DeleteTaskIfNotRescheduled = $deleteTaskIfNotRescheduled;
        $this.Schedules = [List[Object]]::New();
    }

    [String] $Author
    [String] $Comment
    [DateTime] $CreateDate
    [String] $DeleteTaskIfNotRescheduled
    [bool] $HighestAvailableRunLevel
    [String] $HostName
    [String] $IdleTime
    [bool] $Interactive
    [String] $LastRunTime
    [String] $LogonMode
    [String] $NextRunTime
    [bool] $NoPassword
    [String] $PowerManagement
    [String] $RunAsUser
    [IList[Object]] $Schedules
    [String] $ScheduledTaskState
    [String] $StartIn
    [String] $Status
    [String] $TaskToRun
    [String] $TaskName
    [String] $TaskPath
}

Add-CTypeData -Type ([Carbon_ScheduledTasks_TaskInfo]) -MemberType AliasProperty -MemberName 'State' -Value 'Status'
Add-CTypeData -Type ([Carbon_ScheduledTasks_TaskInfo]) `
              -MemberType ScriptProperty `
              -MemberName 'FullName' `
              -Value { return Join-Path -Path $this.TaskPath -ChildPath $this.TaskName }

# Store each of your module's functions in its own file in the Functions
# directory. On the build server, your module's functions will be appended to
# this file, so only dot-source files that exist on the file system. This allows
# developers to work on a module without having to build it first. Grab all the
# functions that are in their own files.
$functionsPath = Join-Path -Path $script:moduleRoot -ChildPath 'Functions\*.ps1'
if( (Test-Path -Path $functionsPath) )
{
    foreach( $functionPath in (Get-Item $functionsPath) )
    {
        . $functionPath.FullName
    }
}



# Leave this here so when Get-CScheduledTask moves to a Carbon.ScheduledTask module, this goes with it.
# COM object Schedule.Service
Add-CTypeData -TypeName 'System.__ComObject#{9c86f320-dee3-4dd1-b972-a303f26b061e}' `
              -MemberName 'Status' `
              -MemberType ScriptProperty `
              -Value {
                    switch( $this.State )
                    {
                        1 { return "Disabled" }
                        2 { return "Queued" }
                        3 { return "Ready" }
                        4 { return "Running" }
                        default { return "Unknown" }
                    }
                }

function Get-CScheduledTask
{
    <#
    .SYNOPSIS
    Gets the scheduled tasks for the current computer.
 
    .DESCRIPTION
    The `Get-CScheduledTask` function gets the scheduled tasks on the current computer. It returns
    `[Carbon_ScheduledTask_TaskInfo]` objects for each one.
 
    With no parameters, `Get-CScheduledTask` returns all scheduled tasks. To get a specific scheduled task, use the
    `Name` parameter, which must be the full name of the task, i.e. path plus name. The name parameter accepts
    wildcards. If a scheduled task with the given name isn't found, an error is written.
 
    By default, `Get-CScheduledTask` uses the `schtasks.exe` application to get scheduled task information. Beginning in
    Carbon 2.8.0, you can return `RegisteredTask` objects from the `Schedule.Service` COM API with the `AsComObject`
    switch. Using this switch is an order of magnitude faster. In the next major version of Carbon, this will become the
    default behavior.
 
    Before Carbon 2.7.0, this function has the same name as the built-in `Get-CScheduledTask` function that comes on
    Windows 2012/8 and later. It returns objects with the same properties, but if you want to use the built-in function,
    use the `ScheduledTasks` qualifier, e.g. `ScheduledTasks\Get-CScheduledTask`.
 
    .LINK
    Test-CScheduledTask
 
    .EXAMPLE
    Get-CScheduledTask
 
    Demonstrates how to get all scheduled tasks.
 
    .EXAMPLE
    Get-CScheduledTask -Name 'AutoUpdateMyApp'
 
    Demonstrates how to get a specific task.
 
    .EXAMPLE
    Get-CScheduledTask -Name '*Microsoft*'
 
    Demonstrates how to get all tasks that match a wildcard pattern.
 
    .EXAMPLE
    ScheduledTasks\Get-CScheduledTask
 
    Demonstrates how to call the `Get-CScheduledTask` function in the `ScheduledTasks` module which ships on Windows
    2012/8 and later.
    #>
    [CmdletBinding()]
    param(
        [Parameter()]
        [Alias('TaskName')]
        [string]
        # The name of the scheduled task to return. Wildcards supported. This must be the *full task name*, i.e. the task's path/location and its name.
        $Name,

        [Switch]
        # Return the scheduled task as a [RegisteredTask Windows COM object](https://docs.microsoft.com/en-us/windows/desktop/taskschd/registeredtask), using the `Schedule.Service` COM API. This is faster and more reliable. See [Task Scheduler Reference](https://docs.microsoft.com/en-us/windows/desktop/taskschd/task-scheduler-reference) for more information.
        #
        # This parameter was introduced in Carbon 2.8.0.
        $AsComObject
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    function ConvertFrom-DurationSpec
    {
        param(
            $Duration
        )

        if( $Duration -match '^P((\d+)D)?T((\d+)H)?((\d+)M)?((\d+)S)?$' )
        {
            return New-Object 'TimeSpan' $Matches[2],$Matches[4],$Matches[6],$Matches[8]
        }
    }

    function ConvertFrom-RepetitionElement
    {
        param(
            [Xml.XmlElement]
            $TriggerElement
        )

        Set-StrictMode -Version 'Latest'

        [Carbon_ScheduledTasks_ScheduleType]$scheduleType = [Carbon_ScheduledTasks_ScheduleType]::Unknown
        $interval = $null
        $modifier = $null
        $duration = $null
        $stopAtEnd = $false
        [TimeSpan]$delay = [TimeSpan]::Zero

        if( $TriggerElement.GetElementsByTagName('Repetition').Count -gt 0 )
        {
            $repetition = $TriggerElement.Repetition

            $interval = $repetition.Interval
            if( $interval -match 'PT(\d+)(.*)$' )
            {
                $modifier = $Matches[1]
                $unit = $Matches[2]

                $hour = 0
                $minute = 0
                $second = 0
                switch( $unit )
                {
                    'H' { $hour = $modifier }
                    'M' { $minute = $modifier }
                }

                $scheduleTypes = @{
                                        'H' = 'Hourly';
                                        'M' = 'Minute';
                                  }
                if( $scheduleTypes.ContainsKey( $unit ) )
                {
                    $scheduleType = $scheduleTypes[$unit]
                }
                $timespan = New-Object 'TimeSpan' $hour,$minute,$second
                switch( $scheduleType )
                {
                    'Hourly' { $modifier = $timespan.TotalHours }
                    'Minute' { $modifier = $timespan.TotalMinutes }
                }
            }

            if( $repetition | Get-Member -Name 'Duration' )
            {
                $duration = $repetition.Duration
                $durationAsTimeSpan = ConvertFrom-DurationSpec -Duration $repetition.Duration
                if ( $null -ne $durationAsTimeSpan)
                {
                    $duration = $durationAsTimeSpan
                }
            }

            if( $repetition | Get-Member -Name 'StopAtDurationEnd' )
            {
                $stopAtEnd = ($repetition.StopAtDurationEnd -eq 'true')
            }
        }

        if( $TriggerElement | Get-Member -Name 'Delay' )
        {
            $delayAsTimeSpan = ConvertFrom-DurationSpec -Duration $TriggerElement.Delay
            if ($null -ne $delayAsTimeSpan)
            {
                $delay = $delayAsTimeSpan
            }
        }

        return $scheduleType,$modifier,$duration,$stopAtEnd,$delay
    }

    $optionalArgs = @()
    $wildcardSearch = $false
    if( $Name )
    {
        if( [Management.Automation.WildcardPattern]::ContainsWildcardCharacters($Name) )
        {
            $wildcardSearch = $true
        }
        else
        {
            $Name = Join-Path -Path '\' -ChildPath $Name
            $optionalArgs = @( '/tn', $Name )
        }
    }

    if( $AsComObject )
    {
        $taskScheduler = New-Object -ComObject 'Schedule.Service'
        $taskScheduler.Connect()


        function Get-Tasks
        {
            param(
                $Folder
            )

            $getHiddenTasks = 1

            $Folder.GetTasks($getHiddenTasks) | ForEach-Object { $_ }

            foreach( $subFolder in $Folder.GetFolders($getHiddenTasks) )
            {
                Get-Tasks -Folder $subFolder
            }
        }

        $tasks = Get-Tasks -Folder $taskScheduler.GetFolder("\") |
                    Where-Object {
                        if( -not $Name )
                        {
                            return $true
                        }

                        return $_.Path -like $Name
                    }

        if( -not $wildcardSearch -and -not $tasks )
        {
            Write-Error -Message ('Scheduled task "{0}" not found.' -f $Name) -ErrorAction $ErrorActionPreference
            return
        }

        return $tasks
    }

    $originalErrPreference = $ErrorActionPreference
    $originalEncoding = [Console]::OutputEncoding
    # Some tasks from Intel have special characters in them.
    $OutputEncoding = [Console]::OutputEncoding = [Text.Encoding]::GetEncoding(1252)
    $ErrorActionPreference = 'Continue'
    [object[]]$output = $null
    $errFile = Join-Path -Path $env:TEMP -ChildPath ('Carbon+Get-CScheduledTask+{0}' -f [IO.Path]::GetRandomFileName())
    try
    {
        $output = schtasks /query /v /fo csv $optionalArgs 2> $errFile |
                    ConvertFrom-Csv |
                    Where-Object { $_.HostName -ne 'HostName' }
    }
    finally
    {
        $ErrorActionPreference = $originalErrPreference
        $OutputEncoding = [Console]::OutputEncoding = $originalEncoding
    }

    if( $LASTEXITCODE )
    {
        if( (Test-Path -Path $errFile -PathType Leaf) )
        {
            $err = (Get-Content -Path $errFile) -join ([Environment]::NewLine)
            try
            {
                if ($err -match 'The\ system\ cannot\ find\ the\ (file|path)\ specified\.')
                {
                    Write-Error ('Scheduled task ''{0}'' not found.' -f $Name) -ErrorAction $ErrorActionPreference
                }
                else
                {
                    Write-Error ($error) -ErrorAction $ErrorActionPreference
                }
            }
            finally
            {
                Remove-Item -Path $errFile
            }
        }
        return
    }

    if( -not $output )
    {
        return
    }

    $comTasks = Get-CScheduledTask -AsComObject

    for( $idx = 0; $idx -lt $output.Count; ++$idx )
    {
        $csvTask = $output[$idx]

        $comTask = $comTasks | Where-Object { $_.Path -eq $csvTask.TaskName }
        if( $comTask )
        {
            $xmlDoc = [xml]$comTask.Xml
        }
        else
        {
            $xml = schtasks /query /tn $csvTask.TaskName /xml | Where-Object { $_ }
            $xml = $xml -join ([Environment]::NewLine)
            $xmlDoc = [xml]$xml
        }

        $taskPath = Split-Path -Parent -Path $csvTask.TaskName
        # Get-CScheduledTask on Win2012/8 has a trailing slash so we include it here.
        if( $taskPath -ne '\' )
        {
            $taskPath = '{0}\' -f $taskPath
        }
        $taskName = Split-Path -Leaf -Path $csvTask.TaskName

        if( -not ($xmlDoc | Get-Member -Name 'Task') )
        {
            Write-Error -Message ('Unable to get information for scheduled task "{0}": XML task information is missing the "Task" element.' -f $csvTask.TaskName) -ErrorAction $ErrorActionPreference
            continue
        }

        $xmlTask = $xmlDoc.Task
        $principal = $xmlTask.Principals.Principal
        $isInteractive = $false
        $noPassword = $false
        if( $principal | Get-Member 'LogonType' )
        {
            $isInteractive = $principal.LogonType -eq 'InteractiveTokenOrPassword'
            $noPassword = $principal.LogonType -eq 'S4U'
        }

        $highestRunLevel = $false
        if( $principal | Get-Member 'RunLevel' )
        {
            $highestRunLevel = ($principal.RunLevel -eq 'HighestAvailable')
        }

        $createDate = [DateTime]::MinValue
        if( $xmlTask | Get-Member -Name 'RegistrationInfo' )
        {
            $regInfo = $xmlTask.RegistrationInfo
            if( $regInfo | Get-Member -Name 'Date' )
            {
                $createDate = [datetime]$regInfo.Date
            }
        }

        $taskToRun = $csvTask.'Task To Run'
        if( ($xmlTask | Get-Member -Name 'Actions') -and $xmlTask.Actions.ChildNodes.Count -eq 1 )
        {
            $actions = $xmlTask.Actions
            if( ($actions | Get-Member -Name 'Exec') -and ($actions.Exec | Measure-Object | Select-Object -ExpandProperty 'Count') -eq 1)
            {
                $exec = $actions.Exec

                if( $exec | Get-Member -Name 'Command' )
                {
                    $taskToRun = $exec.Command
                }

                if( $exec | Get-Member -Name 'Arguments' )
                {
                    $taskToRun = '{0} {1}' -f $taskToRun,$exec.Arguments
                }
            }
        }

        $task = [Carbon_ScheduledTasks_TaskInfo]::New(
            $csvTask.HostName,
            $taskPath,
            $taskName,
            $csvTask.'Next Run Time',
            $csvTask.Status,
            $csvTask.'Logon Mode',
            $csvTask.'Last Run Time',
            $csvTask.Author,
            $createDate,
            $taskToRun,
            $csvTask.'Start In',
            $csvTask.Comment,
            $csvTask.'Scheduled Task State',
            $csvTask.'Idle Time',
            $csvTask.'Power Management',
            $csvTask.'Run As User',
            $isInteractive,
            $noPassword,
            $highestRunLevel,
            $csvTask.'Delete Task If Not Rescheduled'
        )

        $scheduleIdx = 0
        while( $idx -lt $output.Count -and $output[$idx].TaskName -eq $csvTask.TaskName )
        {
            $csvTask = $output[$idx++]
            [Carbon_ScheduledTasks_ScheduleType]$scheduleType = [Carbon_ScheduledTasks_ScheduleType]::Unknown

            [int[]]$days = @()
            [int]$csvDay = 0
            if( [int]::TryParse($csvTask.Days, [ref]$csvDay) )
            {
                $days = @( $csvDay )
            }

            $duration = $csvTask.'Repeat: Until: Duration'
            [Carbon_ScheduledTasks_Month[]]$months = @()
            $modifier = $null
            $stopAtEnd = $false
            [int]$interval = 0
            [TimeSpan]$endTime = [TimeSpan]::Zero
            [DayOfWeek[]]$daysOfWeek = @()
            [TimeSpan]$delay = [TimeSpan]::Zero
            [int]$idleTime = 0
            $eventChannelName = $null

            $triggers = $xmlTask.GetElementsByTagName('Triggers') | Select-Object -First 1
            if( -not $triggers -or $triggers.ChildNodes.Count -eq 0 )
            {
                $scheduleType = [Carbon_ScheduledTasks_ScheduleType]::OnDemand
            }
            elseif( $triggers.ChildNodes.Count -gt 0 )
            {
                [Xml.XmlElement]$trigger = $triggers.ChildNodes.Item($scheduleIdx++)
                if( $trigger | Get-Member -Name 'EndBoundary' )
                {
                    $endDateTime = [datetime]$trigger.EndBoundary
                    $endTime = New-TimeSpan -Hours $endDateTime.Hour -Minutes $endDateTime.Minute -Seconds $endDateTime.Second
                }

                $scheduleType,$modifier,$duration,$stopAtEnd,$delay = ConvertFrom-RepetitionElement $trigger
                if( $trigger.Name -eq 'TimeTrigger' )
                {
                    $days = @( )
                    if( $csvTask.'Schedule Type' -eq 'One Time Only' )
                    {
                        $scheduleType = 'Once'
                        $interval = $modifier
                        $modifier = $null
                    }
                }
                elseif( $trigger.Name -eq 'LogonTrigger' )
                {
                    $scheduleType = 'OnLogon'
                    $interval = 0
                    $modifier = $null
                }
                elseif( $trigger.Name -eq 'BootTrigger' )
                {
                    $scheduleType = 'OnStart'
                    $interval = 0
                    $modifier = $null
                }
                elseif( $trigger.Name -eq 'IdleTrigger' )
                {
                    $scheduleType = 'OnIdle'
                    $interval = 0
                    $modifier = $null
                    $settingsNode = $xmlTask.Settings
                    if( $settingsNode | Get-Member 'IdleSettings' )
                    {
                        $idleSettingsNode = $settingsNode.IdleSettings
                        if( $idleSettingsNode | Get-Member 'Duration' )
                        {
                            $idleTimeAsTimeSpan = ConvertFrom-DurationSpec -Duration $xmlTask.Settings.IdleSettings.Duration
                            if ($null -ne $idleTimeAsTimeSpan)
                            {
                                $idleTime = $idleTimeAsTimeSpan.TotalMinutes
                            }
                        }
                    }
                }
                elseif( $trigger.Name -eq 'EventTrigger' )
                {
                    $scheduleType = 'OnEvent'
                    $subscription = [xml]$trigger.Subscription
                    $selectNode = $subscription.QueryList.Query.Select
                    $modifier = $selectNode.InnerText
                    $eventChannelName = $selectNode.GetAttribute('Path')
                }
                elseif( $trigger.Name -eq 'SessionStateChangeTrigger' )
                {
                    $scheduleType = [Carbon_ScheduledTasks_ScheduleType]::SessionStateChange
                }
                elseif( $trigger.Name -eq 'RegistrationTrigger' )
                {
                    $scheduleType = [Carbon_ScheduledTasks_ScheduleType]::Registration
                }
                elseif( $trigger.Name -eq 'CalendarTrigger' )
                {
                    if( $trigger.GetElementsByTagName('ScheduleByDay').Count -eq 1 )
                    {
                        $scheduleType = 'Daily'
                        $modifier = $trigger.ScheduleByDay.DaysInterval
                        $null,$interval,$null,$null = ConvertFrom-RepetitionElement $trigger
                    }
                    elseif( $trigger.GetElementsByTagName('ScheduleByWeek').Count -eq 1 )
                    {
                        $scheduleType = 'Weekly'
                        $interval = $modifier
                        $modifier = $trigger.ScheduleByWeek.WeeksInterval
                        $days = @( )
                        $daysOfWeek = $trigger.ScheduleByWeek.DaysOfWeek.ChildNodes | ForEach-Object { [DayOfWeek]$_.Name }
                    }
                    elseif( $trigger.GetElementsByTagName('ScheduleByMonth').Count -eq 1 )
                    {
                        $scheduleType = 'Monthly'
                        $monthsNode = $trigger.ScheduleByMonth.Months
                        $daysOfMonth = $trigger.ScheduleByMonth.DaysOfMonth.ChildNodes | ForEach-Object { $_.InnerText }
                        if( $daysOfMonth -eq 'Last' )
                        {
                            $interval = $modifier
                            $modifier = 'LastDay'
                            $days = @()
                        }
                        else
                        {
                            $days = $daysOfMonth | ForEach-Object { [int]$_ }
                            $interval = $modifier
                            # Monthly tasks.
                            if( $monthsNode.ChildNodes.Count -eq 12 )
                            {
                                $modifier = 1
                            }
                            else
                            {
                                # Non-monthly tasks.
                                $modifier = $null
                            }
                        }

                        [Carbon_ScheduledTasks_Month[]]$months = $monthsNode.ChildNodes | ForEach-Object { ([Carbon_ScheduledTasks_Month]$_.Name) }
                    }
                    elseif( $triggers.GetElementsByTagName('ScheduleByMonthDayOfWeek').Count -eq 1 )
                    {
                        $scheduleType = 'Monthly'
                        $interval = $modifier
                        $scheduleNode = $trigger.ScheduleByMonthDayOfWeek
                        $daysOfWeek = $scheduleNode.DaysOfWeek.ChildNodes | ForEach-Object { [DayOfWeek]$_.Name }
                        $months = $scheduleNode.Months.ChildNodes | ForEach-Object { ([Carbon_ScheduledTasks_Month]$_.Name) }
                        switch( $scheduleNode.Weeks.Week )
                        {
                            1 { $modifier = 'First' }
                            2 { $modifier = 'Second' }
                            3 { $modifier = 'Third' }
                            4 { $modifier = 'Fourth' }
                            'Last' { $modifier = 'Last' }
                        }
                    }
                }
            }

            function ConvertFrom-SchtasksDate
            {
                param(
                    [Parameter(Mandatory=$true)]
                    [string]
                    $SchtasksDate,

                    [Parameter(Mandatory=$true)]
                    [DateTime]
                    $DefaultValue
                )

                Set-StrictMode -Version 'Latest'

                [DateTime]$dateTime = $DefaultValue
                if( -not [DateTime]::TryParse( $SchtasksDate, [ref] $dateTime ) )
                {
                    return $DefaultValue
                }
                return New-Object 'DateTime' $dateTime.Year,$dateTime.Month,$dateTime.Day
            }

            function ConvertFrom-SchtasksTime
            {
                param(
                    [Parameter(Mandatory=$true)]
                    [string]
                    $SchtasksTime
                )

                Set-StrictMode -Version 'Latest'

                [TimeSpan]$timespan = [TimeSpan]::Zero
                [DateTime]$dateTime = New-Object 'DateTime' 2015,11,6
                $schtasksTime = '{0} {1}' -f (Get-Date).ToString('d'),$SchtasksTime
                if( -not [DateTime]::TryParse( $SchtasksTime, [ref] $dateTime ) )
                {
                    return $timespan
                }

                return New-Object 'TimeSpan' $dateTime.Hour,$dateTime.Minute,$dateTime.Second
            }

            $startDate = ConvertFrom-SchtasksDate $csvTask.'Start Date' -DefaultValue ([DateTime]::MinValue)
            $startTime = ConvertFrom-SchtasksTime $csvTask.'Start Time'
            $endDate = ConvertFrom-SchtasksDate $csvTask.'End Date' -DefaultValue ([DateTime]::MaxValue)

            $schedule = [Carbon_ScheduledTasks_ScheduleInfo]::New()
            $schedule.LastResult = $csvTask.'Last Result'
            $schedule.StopTaskIfRunsXHoursandXMins = $csvTask.'Stop Task If Runs X Hours And X Mins'
            $schedule.ScheduleType = $scheduleType
            $schedule.Modifier = $modifier
            $schedule.Interval = $interval
            $schedule.StartTime = $startTime
            $schedule.StartDate = $startDate
            $schedule.EndTime = $endTime
            $schedule.EndDate = $endDate
            $schedule.DaysOfWeek = $daysOfWeek
            $schedule.Days = $days
            $schedule.Months = $months
            $schedule.RepeatEvery = $csvTask.'Repeat: Every'
            $schedule.RepeatUntilTime = $csvTask.'Repeat: Until: Time'
            $schedule.RepeatUntilDuration = $duration
            $schedule.RepeatStopIfStillRunning = $csvTask.'Repeat: Stop If Still Running'
            $schedule.StopAtEnd = $stopAtEnd
            $schedule.Delay = $delay
            $schedule.IdleTime = $idleTime
            $schedule.EventChannelName = $eventChannelName

            $task.Schedules.Add( $schedule )
        }
        --$idx;

        if( -not $wildcardSearch -or $task.FullName -like $Name )
        {
            $task
        }
    }

}



function Install-CScheduledTask
{
    <#
    .SYNOPSIS
    Installs a scheduled task on the current computer.
 
    .DESCRIPTION
    The `Install-CScheduledTask` function uses `schtasks.exe` to install a scheduled task on the current computer. If a
    task with the same name already exists, the existing task is left in place. Use the `-Force` switch to force
    `Install-CScheduledTask` to delete any existing tasks before installation.
 
    If a new task is created, a `[Carbon_ScheduledTasks_TaskInfo]` object is returned.
 
    The `schtasks.exe` command line application is pretty limited in the kind of tasks it will create. If you need a
    scheduled task created with options not supported by `Install-CScheduledTask`, you can create an XML file using the
    [Task Scheduler Schema](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx) or create a task with
    the Task Scheduler MMC then export that task as XML with the `schtasks.exe /query /xml /tn <TaskName>`. Pass the XML
    file (or the raw XML) with the `TaskXmlFilePath` or `TaskXml` parameters, respectively.
 
    .LINK
    Get-CScheduledTask
 
    .LINK
    Test-CScheduledTask
 
    .LINK
    Uninstall-CScheduledTask
 
    .LINK
    http://technet.microsoft.com/en-us/library/cc725744.aspx#BKMK_create
 
    .LINK
    http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 5
 
    Creates a scheduled task "CarbonSample" to run notepad.exe every five minutes. No credential or principal is
    provided, so the task will run as `System`.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 1 -TaskCredential (Get-Credential 'runasuser')
 
    Demonstrates how to run a task every minute as a specific user with the `TaskCredential` parameter.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'C:\Windows\system32\notepad.exe' -Minute 1 -Principal LocalService
 
    Demonstrates how to run a task every minute as a built-in principal, in this case `Local Service`.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'calc.exe' -Minute 5 -StartTime '12:00' -EndTime '14:00' -StartDate '6/6/2006' -EndDate '6/6/2006'
 
    Demonstrates how to run a task every 5 minutes between the given start date/time and end date/time. In this case,
    the task will run between noon and 2 pm on `6/6/2006`.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad' -Hourly 1
 
    Creates a scheduled task `CarbonSample` which runs `notepad.exe` every hour as the `LocalService` user.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Weekly 1
 
    Demonstrates how to run a task ever *N* weeks, in this case every week.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Monthly
 
    Demonstrates how to run a task the 1st of every month.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Monthly -DayOfMonth 15
 
    Demonstrates how to run a monthly task on a specific day of the month.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Month 1,4,7,10 -DayOfMonth 5
 
    Demonstrates how to run a task on specific months of the year on a specific day of the month.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -WeekOfMonth First -DayOfWeek Sunday
 
    Demonstrates how to run a task on a specific week of each month. In this case, the task will run the first Sunday of
    every month.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Month 1,5,9 -WeekOfMonth First -DayOfWeek Sunday
 
    Demonstrates how to run a task on a specific week of specific months. In this case, the task will run the first
    Sunday of January, May, and September.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -LastDayOfMonth
 
    Demonstrates how to run a task the last day of every month.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -LastDayOfMonth -Month 1,6
 
    Demonstrates how to run a task the last day of specific months. In this case, the task will run the last day of
    January and June.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -Once -StartTime '0:00'
 
    Demonstrates how to run a task once. In this case, the task will run at midnight of today (which means it probably
    won't run since it is always past midnight).
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnStart
 
    Demonstrates how to run a task when the computer starts up.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnStart -Delay '0:30'
 
    Demonstrates how to run a task when the computer starts up after a certain amount of time passes. In this case, the
    task will run 30 minutes after the computer starts.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnLogon -TaskCredential (Get-Credential 'runasuser')
 
    Demonstrates how to run a task when the user running the task logs on. Usually you want to pass a credential when
    setting up a logon task, since the built-in users never log in.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnLogon -Delay '1:45' -TaskCredential (Get-Credential 'runasuser')
 
    Demonstrates how to run a task after a certain amount of time passes after a user logs in. In this case, the task
    will run after 1 hour and 45 minutes after `runasuser` logs in.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnIdle
 
    Demonstrates how to run a task when the computer is idle.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -OnIdle -Delay '0:05'
 
    Demonstrates how to run a task when the computer has been idle for a desired amount of time. In this case, the task
    will run after the computer has been idle for 5 minutes.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'wevtvwr.msc' -OnEvent -EventChannelName System -EventXPathQuery '*[Sytem/EventID=101]'
 
    Demonstrates how to run an event when certain events are written to the event log. In this case, wevtvwr.msc will
    run whenever an event with ID `101` is published in the System event channel.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXmlFilePath $taskXmlPath
 
    Demonstrates how to create a task using the [Task Scheduler XML
    schema](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx) for a task that runs as a built-in
    principal. You can export task XML with the `schtasks /query /xml /tn <Name>` command.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXmlFilePath $taskXmlPath -TaskCredential (Get-Credential 'runasuser')
 
    Demonstrates how to create a task using the [Task Scheduler XML
    schema](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx) for a task that will run as a
    specific user. The username in the XML file should match the username in the credential.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXml $taskXml
 
    Demonstrates how to create a task using raw XML that conforms to the [Task Scheduler XML
    schema](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx) for a task that will run as a
    built-in principal. In this case, `$taskXml` should be an XML document.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonSample' -TaskToRun 'notepad.exe' -TaskXml $taskXml -TaskCredential (Get-Credential 'runasuser')
 
    Demonstrates how to create a task using raw XML that conforms to the [Task Scheduler XML
    schema](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383609.aspx) for a task that will run as a
    specific user. In this case, `$taskXml` should be an XML document. The username in the XML document should match
    the username in the credential.
 
    .EXAMPLE
    Install-CScheduledTask -Name 'CarbonTasks\CarbonSample' -TaskToRun 'notepad.exe' -Monthly
 
    Demonstrates how to create tasks under a folder/directory: use a path for the `Name` parameter.
    #>
    [CmdletBinding()]
    param(
        # The name of the scheduled task to create. Paths are allowed to create tasks under folders.
        [Parameter(Mandatory)]
        [ValidateLength(1,238)]
        [Alias('TaskName')]
        [String] $Name,

        # The task/program to execute, including arguments/parameters.
        [Parameter(Mandatory,ParameterSetName='Minute')]
        [Parameter(Mandatory,ParameterSetName='Hourly')]
        [Parameter(Mandatory,ParameterSetName='Daily')]
        [Parameter(Mandatory,ParameterSetName='Weekly')]
        [Parameter(Mandatory,ParameterSetName='Monthly')]
        [Parameter(Mandatory,ParameterSetName='Month')]
        [Parameter(Mandatory,ParameterSetName='LastDayOfMonth')]
        [Parameter(Mandatory,ParameterSetName='WeekOfMonth')]
        [Parameter(Mandatory,ParameterSetName='Once')]
        [Parameter(Mandatory,ParameterSetName='OnStart')]
        [Parameter(Mandatory,ParameterSetName='OnLogon')]
        [Parameter(Mandatory,ParameterSetName='OnIdle')]
        [Parameter(Mandatory,ParameterSetName='OnEvent')]
        [ValidateLength(1,262)]
        [String] $TaskToRun,

        # Create a scheduled task that runs every N minutes.
        [Parameter(ParameterSetName='Minute',Mandatory)]
        [ValidateRange(1,1439)]
        [int] $Minute,

        # Create a scheduled task that runs every N hours.
        [Parameter(ParameterSetName='Hourly',Mandatory)]
        [ValidateRange(1,23)]
        [int] $Hourly,

        # Stops the task at the `EndTime` or `Duration` if it is still running.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [switch] $StopAtEnd,

        # Creates a scheduled task that runs every N days.
        [Parameter(ParameterSetName='Daily',Mandatory)]
        [ValidateRange(1,365)]
        [int] $Daily,

        # Creates a scheduled task that runs every N weeks.
        [Parameter(ParameterSetName='Weekly',Mandatory)]
        [ValidateRange(1,52)]
        [int] $Weekly,

        # Create a scheduled task that runs every month.
        [Parameter(ParameterSetName='Monthly',Mandatory)]
        [switch] $Monthly,

        # Create a scheduled task that runs on the last day of every month. To run on specific months, specify the `Month` parameter.
        [Parameter(ParameterSetName='LastDayOfMonth',Mandatory)]
        [switch] $LastDayOfMonth,

        # Create a scheduled task that runs on specific months. To create a monthly task, use the `Monthly` switch.
        [Parameter(ParameterSetName='Month',Mandatory)]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Carbon_ScheduledTasks_Month[]] $Month,

        # The day of the month to run a monthly task.
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month',Mandatory)]
        [ValidateRange(1,31)]
        [int] $DayOfMonth,

        # Create a scheduled task that runs a particular week of the month.
        [Parameter(ParameterSetName='WeekOfMonth',Mandatory)]
        [Carbon_ScheduledTasks_WeekOfMonth] $WeekOfMonth,

        # The day of the week to run the task. Default is today.
        [Parameter(ParameterSetName='WeekOfMonth',Mandatory)]
        [Parameter(ParameterSetName='Weekly')]
        [DayOfWeek[]] $DayOfWeek,

        # Create a scheduled task that runs once.
        [Parameter(ParameterSetName='Once',Mandatory)]
        [switch] $Once,

        # Create a scheduled task that runs at startup.
        [Parameter(ParameterSetName='OnStart',Mandatory)]
        [switch] $OnStart,

        # Create a scheduled task that runs when the user running the task logs on. Requires the `TaskCredential` parameter.
        [Parameter(ParameterSetName='OnLogon',Mandatory)]
        [switch] $OnLogon,

        # Create a scheduled task that runs when the computer is idle for N minutes.
        [Parameter(ParameterSetName='OnIdle',Mandatory)]
        [ValidateRange(1,999)]
        [int] $OnIdle,

        # Create a scheduled task that runs when events appear in the Windows event log.
        [Parameter(ParameterSetName='OnEvent',Mandatory)]
        [switch] $OnEvent,

        # The name of the event channel to look at.
        [Parameter(ParameterSetName='OnEvent',Mandatory)]
        [String] $EventChannelName,

        # The XPath event query to use to determine when to fire `OnEvent` tasks.
        [Parameter(ParameterSetName='OnEvent',Mandatory)]
        [String] $EventXPathQuery,

        # Install the task from this XML path.
        [Parameter(Mandatory, ParameterSetName='XmlFile')]
        [String] $TaskXmlFilePath,

        # Install the task from this XML.
        [Parameter(Mandatory, ParameterSetName='Xml')]
        [xml] $TaskXml,

        # Re-run the task every N minutes.
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [ValidateRange(1,599940)]
        [int] $Interval,

        # The date the task can start running.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once')]
        [DateTime] $StartDate,

        # The start time to run the task. Must be less than `24:00`.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once',Mandatory)]
        [ValidateScript({ $_ -lt [timespan]'1' })]
        [TimeSpan] $StartTime,

        # The duration to run the task. Usually used with `Interval` to repeatedly run a task over a given time span. By
        # default, re-runs for an hour. Can't be used with `EndTime`.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [TimeSpan] $Duration,

        # The last date the task should run.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [DateTime] $EndDate,

        # The end time to run the task. Must be less than `24:00`. Can't be used with `Duration`.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [ValidateScript({ $_ -lt [timespan]'1' })]
        [TimeSpan] $EndTime,

        # Enables the task to run interactively only if the user is currently logged on at the time the job runs. The task will only run if the user is logged on. Must be used with `TaskCredential` parameter.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once')]
        [Parameter(ParameterSetName='OnStart')]
        [Parameter(ParameterSetName='OnLogon')]
        [Parameter(ParameterSetName='OnIdle')]
        [Parameter(ParameterSetName='OnEvent')]
        [switch] $Interactive,

        # No password is stored. The task runs non-interactively as the given user, who must be logged in. Only local
        # resources are available. Must be used with `TaskCredential` parameter.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once')]
        [Parameter(ParameterSetName='OnStart')]
        [Parameter(ParameterSetName='OnLogon')]
        [Parameter(ParameterSetName='OnIdle')]
        [Parameter(ParameterSetName='OnEvent')]
        [switch] $NoPassword,

        # If the user is an administrator, runs the task with full administrator rights. The default is to run with
        # limited administrative privileges.
        #
        # If UAC is enabled, an administrator has two security tokens: a filtered token that gets used by default and
        # grants standard user rights and a full token that grants administrative rights that is only used when a
        # program is "Run as administrator". Using this switch runs the scheduled task with the adminisrators full
        # token. (Information taken from [How does "Run with the highest privileges" really work in Task Scheduler
        # ?](https://social.technet.microsoft.com/Forums/windows/en-US/7167bb31-f375-4f77-b430-0339092e16b9/how-does-run-with-the-highest-privileges-really-work-in-task-scheduler-).)
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once')]
        [Parameter(ParameterSetName='OnStart')]
        [Parameter(ParameterSetName='OnLogon')]
        [Parameter(ParameterSetName='OnIdle')]
        [Parameter(ParameterSetName='OnEvent')]
        [switch] $HighestAvailableRunLevel,

        # The wait time to delay the running of the task after the trigger is fired. Must be less than 10,000 minutes
        # (6 days, 22 hours, and 40 minutes).
        [Parameter(ParameterSetName='OnStart')]
        [Parameter(ParameterSetName='OnLogon')]
        [Parameter(ParameterSetName='OnEvent')]
        [ValidateScript({ $_ -lt '6.22:40:00'})]
        [timespan] $Delay,

        # The principal the task should run as. Use `Principal` parameter to run as a built-in security principal.
        # Required if `Interactive` or `NoPassword` switches are used.
        [Management.Automation.PSCredential] $TaskCredential,

        # The built-in identity to use. The default is `System`. Use the `TaskCredential` parameter to run as
        # non-built-in security principal.
        [Parameter(ParameterSetName='Minute')]
        [Parameter(ParameterSetName='Hourly')]
        [Parameter(ParameterSetName='Daily')]
        [Parameter(ParameterSetName='Weekly')]
        [Parameter(ParameterSetName='Monthly')]
        [Parameter(ParameterSetName='Month')]
        [Parameter(ParameterSetName='LastDayOfMonth')]
        [Parameter(ParameterSetName='WeekOfMonth')]
        [Parameter(ParameterSetName='Once')]
        [Parameter(ParameterSetName='OnStart')]
        [Parameter(ParameterSetName='OnLogon')]
        [Parameter(ParameterSetName='OnIdle')]
        [Parameter(ParameterSetName='OnEvent')]
        [Parameter(ParameterSetName='XmlFile')]
        [Parameter(ParameterSetName='Xml')]
        [ValidateSet('System','LocalService','NetworkService')]
        [String] $Principal = 'System',

        # Create the task even if a task with the same name already exists (i.e. delete any task with the same name
        # before installation).
        [switch] $Force
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    if( (Test-CScheduledTask -Name $Name) )
    {
        if( $Force )
        {
            Uninstall-CScheduledTask -Name $Name
        }
        else
        {
            Write-Verbose ('Scheduled task ''{0}'' already exists. Use -Force switch to re-create it.' -f $Name)
            return
        }
    }

    $parameters = New-Object 'Collections.ArrayList'

    if( $TaskCredential )
    {
        [void]$parameters.Add( '/RU' )
        [void]$parameters.Add( $TaskCredential.UserName )
        [void]$parameters.Add( '/RP' )
        [void]$parameters.Add( $TaskCredential.GetNetworkCredential().Password )
        Grant-CPrivilege -Identity $TaskCredential.UserName -Privilege 'SeBatchLogonRight'
    }
    elseif ($Principal)
    {
        [void]$parameters.Add( '/RU' )
        [void]$parameters.Add( (Resolve-CIdentityName -Name $Principal) )
    }

    function ConvertTo-SchtasksCalendarNameList
    {
        param(
            [Parameter(Mandatory)]
            [object[]]
            $InputObject
        )

        Set-StrictMode -Version 'Latest'

        $list = $InputObject | ForEach-Object { $_.ToString().Substring(0,3).ToUpperInvariant() }
        return $list -join ','
    }

    $scheduleType = $PSCmdlet.ParameterSetName.ToUpperInvariant()
    $modifier = $null
    switch -Wildcard ( $PSCmdlet.ParameterSetName )
    {
        'Minute'
        {
            $modifier = $Minute
        }
        'Hourly'
        {
            $modifier = $Hourly
        }
        'Daily'
        {
            $modifier = $Daily
        }
        'Weekly'
        {
            $modifier = $Weekly
            if( $PSBoundParameters.ContainsKey('DayOfWeek') )
            {
                [void]$parameters.Add( '/D' )
                [void]$parameters.Add( (ConvertTo-SchtasksCalendarNameList $DayOfWeek) )
            }
        }
        'Monthly'
        {
            $modifier = 1
            if( $DayOfMonth )
            {
                [void]$parameters.Add( '/D' )
                [void]$parameters.Add( ($DayOfMonth -join ',') )
            }
        }
        'Month'
        {
            $scheduleType = 'MONTHLY'
            [void]$parameters.Add( '/M' )
            [void]$parameters.Add( (ConvertTo-SchtasksCalendarNameList $Month) )
            if( ($Month | Select-Object -Unique | Measure-Object).Count -eq 12 )
            {
                Write-Error ('It looks like you''re trying to schedule a monthly task, since you passed all 12 months as the `Month` parameter. Please use the `-Monthly` switch to schedule a monthly task.')
                return
            }

            if( $DayOfMonth )
            {
                [void]$parameters.Add( '/D' )
                [void]$parameters.Add( ($DayOfMonth -join ',') )
            }
        }
        'LastDayOfMonth'
        {
            $modifier = 'LASTDAY'
            $scheduleType = 'MONTHLY'
            [void]$parameters.Add( '/M' )
            if( $Month )
            {
                [void]$parameters.Add( (ConvertTo-SchtasksCalendarNameList $Month) )
            }
            else
            {
                [void]$parameters.Add( '*' )
            }
        }
        'WeekOfMonth'
        {
            $scheduleType = 'MONTHLY'
            $modifier = $WeekOfMonth
            [void]$parameters.Add( '/D' )
            if( $DayOfWeek.Count -eq 1 -and [Enum]::IsDefined([DayOfWeek],$DayOfWeek[0]) )
            {
                [void]$parameters.Add( (ConvertTo-SchtasksCalendarNameList $DayOfWeek[0]) )
            }
            else
            {
                Write-Error ('Tasks that run during a specific week of the month can only occur on a single weekday (received {0} days: {1}). Please pass one weekday with the `-DayOfWeek` parameter.' -f $DayOfWeek.Length,($DayOfWeek -join ','))
                return
            }
        }
        'OnIdle'
        {
            $scheduleType = 'ONIDLE'
            [void]$parameters.Add( '/I' )
            [void]$parameters.Add( $OnIdle )
        }
        'OnEvent'
        {
            $modifier = $EventXPathQuery
        }
        'Xml*'
        {
            if( $PSCmdlet.ParameterSetName -eq 'Xml' )
            {
                $TaskXmlFilePath = 'Carbon+Install-CScheduledTask+{0}.xml' -f [IO.Path]::GetRandomFileName()
                $TaskXmlFilePath = Join-Path -Path $env:TEMP -ChildPath $TaskXmlFilePath
                $TaskXml.Save($TaskXmlFilePath)
            }

            $scheduleType = $null
            $TaskXmlFilePath = Resolve-Path -Path $TaskXmlFilePath
            if( -not $TaskXmlFilePath )
            {
                return
            }

            [void]$parameters.Add( '/XML' )
            [void]$parameters.Add( $TaskXmlFilePath )
        }
    }

    try
    {
        if( $modifier )
        {
            [void]$parameters.Add( '/MO' )
            [void]$parameters.Add( $modifier )
        }

        if( $PSBoundParameters.ContainsKey('TaskToRun') )
        {
            [void]$parameters.Add( '/TR' )
            [void]$parameters.Add( $TaskToRun )
        }

        if( $scheduleType )
        {
            [void]$parameters.Add( '/SC' )
            [void]$parameters.Add( $scheduleType )
        }


        $parameterNameToSchtasksMap = @{
                                            'StartTime' = '/ST';
                                            'Interval' = '/RI';
                                            'EndTime' = '/ET';
                                            'Duration' = '/DU';
                                            'StopAtEnd' = '/K';
                                            'StartDate' = '/SD';
                                            'EndDate' = '/ED';
                                            'EventChannelName' = '/EC';
                                            'Interactive' = '/IT';
                                            'NoPassword' = '/NP';
                                            'Force' = '/F';
                                            'Delay' = '/DELAY';
                                      }

        foreach( $parameterName in $parameterNameToSchtasksMap.Keys )
        {
            if( -not $PSBoundParameters.ContainsKey( $parameterName ) )
            {
                continue
            }

            $schtasksParamName = $parameterNameToSchtasksMap[$parameterName]
            $value = $PSBoundParameters[$parameterName]
            if( $value -is [timespan] )
            {
                if( $parameterName -eq 'Duration' )
                {
                    $totalHours = ($value.Days * 24) + $value.Hours
                    $value = '{0:0000}:{1:00}' -f $totalHours,$value.Minutes
                }
                elseif( $parameterName -eq 'Delay' )
                {
                    $totalMinutes = ($value.Days * 24 * 60) + ($value.Hours * 60) + $value.Minutes
                    $value = '{0:0000}:{1:00}' -f $totalMinutes,$value.Seconds
                }
                else
                {
                    $value = '{0:00}:{1:00}' -f $value.Hours,$value.Minutes
                }
            }
            elseif( $value -is [datetime] )
            {
                $value = $value.ToString('MM/dd/yyyy')
            }

            [void]$parameters.Add( $schtasksParamName )

            if( $value -isnot [switch] )
            {
                [void]$parameters.Add( $value )
            }
        }

        if( $PSBoundParameters.ContainsKey('HighestAvailableRunLevel') -and $HighestAvailableRunLevel )
        {
            [void]$parameters.Add( '/RL' )
            [void]$parameters.Add( 'HIGHEST' )
        }

        $originalEap = $ErrorActionPreference
        $ErrorActionPreference = 'Continue'
        $paramLogString = $parameters -join ' '
        if( $TaskCredential )
        {
            $paramLogString = $paramLogString -replace ([Text.RegularExpressions.Regex]::Escape($TaskCredential.GetNetworkCredential().Password)),'********'
        }
        Write-Verbose ('/TN {0} {1}' -f $Name,$paramLogString)
        # Warnings get written by schtasks to the error stream. Fortunately, errors and warnings
        # are prefixed with ERRROR and WARNING, so we can combine output/error streams and parse
        # it later. We just have to make sure we remove any errors added to the $Error variable.
        $preErrorCount = $Global:Error.Count
        $output = '' | schtasks /create /TN $Name $parameters 2>&1
        $postErrorCount = $Global:Error.Count
        if( $postErrorCount -gt $preErrorCount )
        {
            $numToDelete = $postErrorCount - $preErrorCount
            for( $idx = 0; $idx -lt $numToDelete; ++$idx )
            {
                $Global:Error.RemoveAt(0)
            }
        }
        $ErrorActionPreference = $originalEap

        $createFailed = $false
        if( $LASTEXITCODE )
        {
            $createFailed = $true
        }

        $output | ForEach-Object {
            if( $_ -match '\bERROR\b' )
            {
                Write-Error $_
            }
            elseif( $_ -match '\bWARNING\b' )
            {
                Write-Warning ($_ -replace '^WARNING: ','')
            }
            else
            {
                Write-Verbose $_
            }
        }

        if( -not $createFailed )
        {
            Get-CScheduledTask -Name $Name
        }
    }
    finally
    {
        if( $PSCmdlet.ParameterSetName -eq 'Xml' -and (Test-Path -Path $TaskXmlFilePath -PathType Leaf) )
        {
            Remove-Item -Path $TaskXmlFilePath -ErrorAction SilentlyContinue
        }
    }
}



function Test-CScheduledTask
{
    <#
    .SYNOPSIS
    Tests if a scheduled task exists on the current computer.
 
    .DESCRIPTION
    The `Test-CScheduledTask` function uses `schtasks.exe` to tests if a task with a given name exists on the current computer. If it does, `$true` is returned. Otherwise, `$false` is returned. This name must be the *full task name*, i.e. the task's path/location and its name.
 
    .LINK
    Get-CScheduledTask
 
    .EXAMPLE
    Test-CScheduledTask -Name 'AutoUpdateMyApp'
 
    Demonstrates how to test if a scheduled tasks exists.
    #>
    [CmdletBinding()]
    [OutputType([bool])]
    param(
        [Parameter()]
        [Alias('TaskName')]
        [string]
        # The name of the scheduled task to check. This must be the *full task name*, i.e. the task's path/location and its name.
        $Name
    )

    Set-StrictMode -Version 'Latest'
    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    $Name = Join-Path -Path '\' -ChildPath $Name

    $task = Get-CScheduledTask -Name $Name -AsComObject -ErrorAction Ignore
    if( $task )
    {
        return $true
    }
    else
    {
        return $false
    }
}



function Uninstall-CScheduledTask
{
    <#
    .SYNOPSIS
    Uninstalls a scheduled task on the current computer.
 
    .DESCRIPTION
    The `Uninstall-CScheduledTask` function uses `schtasks.exe` to uninstall a scheduled task on the current computer. If the task doesn't exist, nothing happens.
 
    .LINK
    Get-CScheduledTask
 
    .LINK
    Test-CScheduledTask
 
    .LINK
    Install-CScheduledTask
 
    .EXAMPLE
    Uninstall-CScheduledTask -Name 'doc'
 
    Demonstrates how to delete a scheduled task named `doc`.
 
    .EXAMPLE
    Uninstall-CScheduledTask -Name 'doc' -Force
 
    Demonstrates how to delete a scheduled task that is currently running.
    #>
    [CmdletBinding(DefaultParameterSetName='AsBuiltinPrincipal')]
    param(
        [Parameter(Mandatory=$true)]
        [Alias('TaskName')]
        [string]
        # The name of the scheduled task to uninstall.
        $Name
    )

    Set-StrictMode -Version 'Latest'

    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState

    $Name = Join-Path -Path '\' -ChildPath $Name

    $MAX_TRIES = 5
    $tryNum = 0
    do
    {
        if( -not (Test-CScheduledTask -Name $Name) )
        {
            Write-Verbose ('Scheduled task ''{0}'' not found.' -f $Name)
            return
        }

        $lastTry = (++$tryNum -ge $MAX_TRIES)
        Write-Verbose ('Deleting scheduled task ''{0}''.' -f $Name)
        $errFile = Join-Path -Path $env:TEMP -ChildPath ('Carbon+Uninstall-CScheduledTask+{0}' -f ([IO.Path]::GetRandomFileName()))
        schtasks.exe /delete /tn $Name '/F' 2> $errFile | ForEach-Object { 
            if( $_ -match '\bERROR\b' )
            {
                if( $lastTry -or $err -notmatch 'The function attempted to use a name that is reserved for use by another transaction' )
                {
                    Write-Error $_
                }
            }
            elseif( $_ -match '\bWARNING\b' )
            {
                Write-Warning $_
            }
            else
            {
                Write-Verbose $_
            }
        }

        if( $LASTEXITCODE )
        {
            $err = (Get-Content -Path $errFile) -join ([Environment]::NewLine)
            if( -not $lastTry -and $err -match 'The function attempted to use a name that is reserved for use by another transaction' )
            {
                if( $Global:Error.Count -gt 0 )
                {
                    $Global:Error.RemoveAt(0)
                }
                if( $Global:Error.Count -gt 0 )
                {
                    $Global:Error.RemoveAt(0)
                }                    
                Write-Verbose ('Failed to delete scheduled task ''{0}'' (found ''The function attempted to use a name that is reserved for use by another transaction.'' error). Retrying (attempt #{1}).' -f $Name,$tryNum)
                Start-Sleep -Milliseconds 100
                continue
            }

            Write-Error $err
            break
        }
    }
    while( $true -and -not $lastTry)
}



function Use-CallerPreference
{
    <#
    .SYNOPSIS
    Sets the PowerShell preference variables in a module's function based on the callers preferences.
 
    .DESCRIPTION
    Script module functions do not automatically inherit their caller's variables, including preferences set by common
    parameters. This means if you call a script with switches like `-Verbose` or `-WhatIf`, those that parameter don't
    get passed into any function that belongs to a module.
 
    When used in a module function, `Use-CallerPreference` will grab the value of these common parameters used by the
    function's caller:
 
     * ErrorAction
     * Debug
     * Confirm
     * InformationAction
     * Verbose
     * WarningAction
     * WhatIf
     
    This function should be used in a module's function to grab the caller's preference variables so the caller doesn't
    have to explicitly pass common parameters to the module function.
 
    This function is adapted from the [`Get-CallerPreference` function written by David Wyatt](https://gallery.technet.microsoft.com/scriptcenter/Inherit-Preference-82343b9d).
 
    There is currently a [bug in PowerShell](https://connect.microsoft.com/PowerShell/Feedback/Details/763621) that
    causes an error when `ErrorAction` is implicitly set to `Ignore`. If you use this function, you'll need to add
    explicit `-ErrorAction $ErrorActionPreference` to every `Write-Error` call. Please vote up this issue so it can get
    fixed.
 
    .LINK
    about_Preference_Variables
 
    .LINK
    about_CommonParameters
 
    .LINK
    https://gallery.technet.microsoft.com/scriptcenter/Inherit-Preference-82343b9d
 
    .LINK
    http://powershell.org/wp/2014/01/13/getting-your-script-module-functions-to-inherit-preference-variables-from-the-caller/
 
    .EXAMPLE
    Use-CallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
    Demonstrates how to set the caller's common parameter preference variables in a module function.
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        #[Management.Automation.PSScriptCmdlet]
        # The module function's `$PSCmdlet` object. Requires the function be decorated with the `[CmdletBinding()]`
        # attribute.
        $Cmdlet,

        [Parameter(Mandatory)]
        # The module function's `$ExecutionContext.SessionState` object. Requires the function be decorated with the
        # `[CmdletBinding()]` attribute.
        #
        # Used to set variables in its callers' scope, even if that caller is in a different script module.
        [Management.Automation.SessionState]$SessionState
    )

    Set-StrictMode -Version 'Latest'

    # List of preference variables taken from the about_Preference_Variables and their common parameter name (taken
    # from about_CommonParameters).
    $commonPreferences = @{
                              'ErrorActionPreference' = 'ErrorAction';
                              'DebugPreference' = 'Debug';
                              'ConfirmPreference' = 'Confirm';
                              'InformationPreference' = 'InformationAction';
                              'VerbosePreference' = 'Verbose';
                              'WarningPreference' = 'WarningAction';
                              'WhatIfPreference' = 'WhatIf';
                          }

    foreach( $prefName in $commonPreferences.Keys )
    {
        $parameterName = $commonPreferences[$prefName]

        # Don't do anything if the parameter was passed in.
        if( $Cmdlet.MyInvocation.BoundParameters.ContainsKey($parameterName) )
        {
            continue
        }

        $variable = $Cmdlet.SessionState.PSVariable.Get($prefName)
        # Don't do anything if caller didn't use a common parameter.
        if( -not $variable )
        {
            continue
        }

        if( $SessionState -eq $ExecutionContext.SessionState )
        {
            Set-Variable -Scope 1 -Name $variable.Name -Value $variable.Value -Force -Confirm:$false -WhatIf:$false
        }
        else
        {
            $SessionState.PSVariable.Set($variable.Name, $variable.Value)
        }
    }
}