Adding support for event based triggers by the OnEvent schedule type

Author: danielboth

Modules/ComputerManagementDsc/DSCResources/MSFT_ScheduledTask/MSFT_ScheduledTask.psm1

@@ -234,7 +234,7 @@ function Get-TargetResource
 
         [Parameter()]
         [System.String]
-        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn')]
+        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn','OnEvent')]
         $ScheduleType,
 
         [Parameter()]
@@ -376,7 +376,15 @@ function Get-TargetResource
         [Parameter()]
         [ValidateSet('Group', 'Interactive', 'InteractiveOrPassword', 'None', 'Password', 'S4U', 'ServiceAccount')]
         [System.String]
-        $LogonType
+        $LogonType,
+
+        [Parameter()]
+        [System.String]
+        $EventSubscription,
+
+        [Parameter()]
+        [System.String]
+        $Delay = '00:00:00'
     )
 
     $TaskPath = ConvertTo-NormalizedTaskPath -TaskPath $TaskPath
@@ -436,6 +444,12 @@ function Get-TargetResource
                 break
             }
 
+            'MSFT_TaskEventTrigger'
+            {
+                $returnScheduleType = 'OnEvent'
+                break
+            }
+
             default
             {
                 $returnScheduleType = ''
@@ -510,6 +524,8 @@ function Get-TargetResource
             RunOnlyIfNetworkAvailable       = $settings.RunOnlyIfNetworkAvailable
             RunLevel                        = [System.String] $task.Principal.RunLevel
             LogonType                       = [System.String] $task.Principal.LogonType
+            EventSubscription               = $trigger.Subscription
+            Delay                           = ConvertTo-TimeSpanStringFromScheduledTaskString -TimeSpan $trigger.Delay
         }
     }
 }
@@ -697,7 +713,7 @@ function Set-TargetResource
 
         [Parameter()]
         [System.String]
-        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn')]
+        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn','OnEvent')]
         $ScheduleType,
 
         [Parameter()]
@@ -839,7 +855,15 @@ function Set-TargetResource
         [Parameter()]
         [ValidateSet('Group', 'Interactive', 'InteractiveOrPassword', 'None', 'Password', 'S4U', 'ServiceAccount')]
         [System.String]
-        $LogonType
+        $LogonType,
+
+        [Parameter()]
+        [System.String]
+        $EventSubscription,
+
+        [Parameter()]
+        [System.String]
+        $Delay = '00:00:00'
     )
 
     $TaskPath = ConvertTo-NormalizedTaskPath -TaskPath $TaskPath
@@ -902,6 +926,13 @@ function Set-TargetResource
                 -ArgumentName DaysOfWeek
         }
 
+        if ($ScheduleType -eq 'OnEvent' -and -not([xml]$EventSubscription))
+        {
+            New-InvalidArgumentException `
+                -Message ($script:localizedData.OnEventSubscriptionError) `
+                -ArgumentName EventSubscription
+        }
+
         # Configure the action
         $actionParameters = @{
             Execute = $ActionExecutable
@@ -989,7 +1020,8 @@ function Set-TargetResource
         # Configure the trigger
         $triggerParameters = @{}
 
-        if ($RandomDelay -gt [System.TimeSpan]::FromSeconds(0))
+        # A random delay is not supported when the scheduleType is set to OnEvent
+        if ($RandomDelay -gt [System.TimeSpan]::FromSeconds(0) -and $ScheduleType -ne 'OnEvent')
         {
             $triggerParameters.Add('RandomDelay', $RandomDelay)
         }
@@ -1049,9 +1081,23 @@ function Set-TargetResource
 
                 break
             }
+
+            'OnEvent' 
+            {
+                Write-Verbose -Message ($script:localizedData.ConfigureTaskEventTrigger -f $TaskName) 
+
+                $cimTriggerClass = Get-CimClass -ClassName MSFT_TaskEventTrigger -Namespace Root/Microsoft/Windows/TaskScheduler:MSFT_TaskEventTrigger
+                $trigger = New-CimInstance -CimClass $cimTriggerClass -ClientOnly
+                $trigger.Enabled = $true
+                $trigger.Delay = (New-ScheduledTaskTrigger -RandomDelay $Delay -Once -At (Get-Date)).RandomDelay
+                $trigger.Subscription = $EventSubscription
+            }
         }
 
-        $trigger = New-ScheduledTaskTrigger @triggerParameters -ErrorAction SilentlyContinue
+        if($ScheduleType -ne 'OnEvent')
+        {
+            $trigger = New-ScheduledTaskTrigger @triggerParameters -ErrorAction SilentlyContinue
+        }
 
         if (-not $trigger)
         {
@@ -1423,7 +1469,7 @@ function Test-TargetResource
 
         [Parameter()]
         [System.String]
-        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn')]
+        [ValidateSet('Once', 'Daily', 'Weekly', 'AtStartup', 'AtLogOn','OnEvent')]
         $ScheduleType,
 
         [Parameter()]
@@ -1565,7 +1611,15 @@ function Test-TargetResource
         [Parameter()]
         [ValidateSet('Group', 'Interactive', 'InteractiveOrPassword', 'None', 'Password', 'S4U', 'ServiceAccount')]
         [System.String]
-        $LogonType
+        $LogonType,
+
+        [Parameter()]
+        [System.String]
+        $EventSubscription,
+
+        [Parameter()]
+        [System.String]
+        $Delay = '00:00:00'
     )
 
     $TaskPath = ConvertTo-NormalizedTaskPath -TaskPath $TaskPath
@@ -1580,7 +1634,15 @@ function Test-TargetResource
 
     if ($PSBoundParameters.ContainsKey('RandomDelay'))
     {
-        $PSBoundParameters['RandomDelay'] = (ConvertTo-TimeSpanFromTimeSpanString -TimeSpanString $RandomDelay).ToString()
+        if($ScheduleType -eq 'OnEvent')
+        {
+            # A random delay is not supported when the ScheduleType is set to OnEvent.
+            $null = $PSBoundParameters.Remove('RandomDelay')
+        }
+        else
+        {
+            $PSBoundParameters['RandomDelay'] = (ConvertTo-TimeSpanFromTimeSpanString -TimeSpanString $RandomDelay).ToString()
+        }
     }
 
     if ($PSBoundParameters.ContainsKey('RepetitionDuration'))

Modules/ComputerManagementDsc/DSCResources/MSFT_ScheduledTask/MSFT_ScheduledTask.schema.mof

@@ -42,4 +42,6 @@ class MSFT_ScheduledTask : OMI_BaseResource
     [Write, Description("Indicates that Task Scheduler runs the task only when a network is available. Task Scheduler uses the NetworkID parameter and NetworkName parameter that you specify in this cmdlet to determine if the network is available.")] Boolean RunOnlyIfNetworkAvailable;
     [Write, Description("Specifies the level of user rights that Task Scheduler uses to run the tasks that are associated with the principal. Defaults to 'Limited'."), ValueMap{"Limited","Highest"}, Values{"Limited","Highest"}] String RunLevel;
     [Write, Description("Specifies the security logon method that Task Scheduler uses to run the tasks that are associated with the principal."), ValueMap{"Group","Interactive","InteractiveOrPassword","None","Password","S4U","ServiceAccount"}, Values{"Group","Interactive","InteractiveOrPassword","None","Password","S4U","ServiceAccount"}] String LogonType;
+    [Write, Description("Specifies the EventSubscription in XML. This can be easily generated using the Windows Eventlog Viewer. Can only be used in combination with ScheduleType OnEvent")] String EventSubscription;
+    [Write, Description("Specifies a delay to the start of the trigger. The delay is a static delay before the task is executed. Can only be used in combination with ScheduleType OnEvent")] String Delay;
 };

Modules/ComputerManagementDsc/DSCResources/MSFT_ScheduledTask/en-US/MSFT_ScheduledTask.strings.psd1

@@ -10,6 +10,7 @@ ConvertFrom-StringData @'
     DaysIntervalError = DaysInterval must be greater than zero (0) for Daily schedules. DaysInterval specified is '{0}'.
     WeeksIntervalError = WeeksInterval must be greater than zero (0) for Weekly schedules. WeeksInterval specified is '{0}'.
     WeekDayMissingError = At least one weekday must be selected for Weekly schedule.
+    OnEventSubscriptionError = No (valid) XML Event Subscription was provided. This is required when the scheduletype is OnEvent.
     TriggerCreationError = Error creating new scheduled task trigger.
     ConfigureTriggerRepetitionMessage = Configuring trigger repetition.
     RepetitionIntervalError = Repetition interval is set to '{0}' but repetition duration is '{1}'.
@@ -20,6 +21,7 @@ ConvertFrom-StringData @'
     CreateScheduledTaskPrincipalMessage = Creating scheduled task principal for account '{0}' using logon type '{1}'.
     RemovePreviousScheduledTaskMessage = Removing previous scheduled task '{0}' from '{1}'.
     CreateNewScheduledTaskMessage = Creating new scheduled task '{0}' in '{1}'.
+    ConfigureTaskEventTrigger = Setting up an event based trigger on task {0}
     SetRepetitionTriggerMessage = Setting repetition trigger settings on task '{0}' in '{1}'.
     RegisterScheduledTaskMessage = Registering the scheduled task '{0}' in '{1}'.
     RetrieveScheduledTaskMessage = Retrieving the scheduled task '{0}' from '{1}'.