ScheduledTask: Add 'StopExisting' to valid values for MultipleInstances parameter

CHANGELOG.md

@@ -12,6 +12,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Pin `Pester` module to 4.10.1 because Pester 5.0 is missing code
     coverage - Fixes [Issue #336](https://github.com/dsccommunity/ComputerManagementDsc/issues/336).
 
+- ScheduledTask
+  - Add "StopExisting" to valid values for MultipleInstances parameter - Fixes [Issue #333](https://github.com/dsccommunity/ComputerManagementDsc/issues/333).
+
 ## [8.2.0] - 2020-05-05
 
 ### Changed

source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.psm1

@@ -390,7 +390,7 @@ function Set-TargetResource
         $ExecutionTimeLimit = '08:00:00',
 
         [Parameter()]
-        [ValidateSet('IgnoreNew', 'Parallel', 'Queue')]
+        [ValidateSet('IgnoreNew', 'Parallel', 'Queue', 'StopExisting')]
         [System.String]
         $MultipleInstances = 'Queue',
 
@@ -546,12 +546,16 @@ function Set-TargetResource
             WakeToRun                       = $WakeToRun
             RestartOnIdle                   = $RestartOnIdle
             DontStopOnIdleEnd               = $DontStopOnIdleEnd
-            MultipleInstances               = $MultipleInstances
             Priority                        = $Priority
             RestartCount                    = $RestartCount
             RunOnlyIfNetworkAvailable       = $RunOnlyIfNetworkAvailable
         }
 
+        if ($MultipleInstances -ne 'StopExisting')
+        {
+            $settingParameters.Add('MultipleInstances', $MultipleInstances)
+        }
+
         if ($IdleDuration -gt [System.TimeSpan] '00:00:00')
         {
             $settingParameters.Add('IdleDuration', $IdleDuration)
@@ -579,6 +583,16 @@ function Set-TargetResource
 
         $setting = New-ScheduledTaskSettingsSet @settingParameters
 
+    <#  The following workaround is needed because the TASK_INSTANCES_STOP_EXISTING value of
+        https://docs.microsoft.com/en-us/windows/win32/taskschd/tasksettings-multipleinstances is missing
+        from the Microsoft.PowerShell.Cmdletization.GeneratedTypes.ScheduledTask.MultipleInstancesEnum,
+        which is used for the other values of $MultipleInstances. (at least currently, as of June, 2020)
+    #>
+        if ($MultipleInstances -eq 'StopExisting')
+        {
+            $setting.CimInstanceProperties.Item('MultipleInstances').Value = 3
+        }
+
         $scheduledTaskArguments += @{
             Settings = $setting
         }
@@ -1262,7 +1276,7 @@ function Test-TargetResource
         $ExecutionTimeLimit = '08:00:00',
 
         [Parameter()]
-        [ValidateSet('IgnoreNew', 'Parallel', 'Queue')]
+        [ValidateSet('IgnoreNew', 'Parallel', 'Queue', 'StopExisting')]
         [System.String]
         $MultipleInstances = 'Queue',
 
@@ -1810,6 +1824,19 @@ function Get-CurrentResource
             $PrincipalId = 'UserId'
         }
 
+    <#  The following workaround is needed because Get-StartedTask currently returns NULL for the value
+        of $settings.MultipleInstances when the started task is set to "Stop the existing instance".
+        https://windowsserver.uservoice.com/forums/301869-powershell/suggestions/40685125-bug-get-scheduledtask-returns-null-for-value-of-m
+    #>
+        $MultipleInstances = [System.String] $settings.MultipleInstances
+        if ([String]::IsNullOrEmpty($MultipleInstances))
+        {
+            if ($task.settings.CimInstanceProperties.Item('MultipleInstances').Value -eq 3)
+            {
+                $MultipleInstances = 'StopExisting'
+            }
+        }
+
         $result = @{
             TaskName                        = $task.TaskName
             TaskPath                        = $task.TaskPath
@@ -1847,7 +1874,7 @@ function Get-CurrentResource
             RestartOnIdle                   = $settings.IdleSettings.RestartOnIdle
             DontStopOnIdleEnd               = -not $settings.IdleSettings.StopOnIdleEnd
             ExecutionTimeLimit              = ConvertTo-TimeSpanStringFromScheduledTaskString -TimeSpan $settings.ExecutionTimeLimit
-            MultipleInstances               = [System.String] $settings.MultipleInstances
+            MultipleInstances               = $MultipleInstances
             Priority                        = $settings.Priority
             RestartCount                    = $settings.RestartCount
             RestartInterval                 = ConvertTo-TimeSpanStringFromScheduledTaskString -TimeSpan $settings.RestartInterval

source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.schema.mof

@@ -38,7 +38,7 @@ class DSC_ScheduledTask : OMI_BaseResource
     [Write, Description("Indicates that Task Scheduler restarts the task when the computer cycles into an idle condition more than once.")] Boolean RestartOnIdle;
     [Write, Description("Indicates that Task Scheduler does not terminate the task if the idle condition ends before the task is completed.")] Boolean DontStopOnIdleEnd;
     [Write, Description("Specifies the amount of time that Task Scheduler is allowed to complete the task.")] String ExecutionTimeLimit;
-    [Write, Description("Specifies the policy that defines how Task Scheduler handles multiple instances of the task."), ValueMap{"IgnoreNew","Parallel","Queue"}, Values{"IgnoreNew","Parallel","Queue"}] String MultipleInstances;
+    [Write, Description("Specifies the policy that defines how Task Scheduler handles multiple instances of the task."), ValueMap{"IgnoreNew","Parallel","Queue", "StopExisting"}, Values{"IgnoreNew","Parallel","Queue", "StopExisting"}] String MultipleInstances;
     [Write, Description("Specifies the priority level of the task. Priority must be an integer from 0 (highest priority) to 10 (lowest priority). The default value is 7. Priority levels 7 and 8 are used for background tasks. Priority levels 4, 5, and 6 are used for interactive tasks.")] Uint32 Priority;
     [Write, Description("Specifies the number of times that Task Scheduler attempts to restart the task.")] Uint32 RestartCount;
     [Write, Description("Specifies the amount of time that Task Scheduler attempts to restart the task.")] String RestartInterval;

source/DSCResources/DSC_ScheduledTask/README.md

@@ -6,6 +6,16 @@ scheduled tasks.
 
 ## Known Issues
 
+One of the values needed for the `MultipleInstances` parameter is missing from the
+`Microsoft.PowerShell.Cmdletization.GeneratedTypes.ScheduledTask.MultipleInstancesEnum`
+enumerator. There are four valid values defined for the `MultipleInstances` property of the
+Task Settings ([TaskSettings.MultipleInstances Property](https://docs.microsoft.com/en-us/windows/win32/taskschd/tasksettings-multipleinstances "TaskSettings.MultipleInstances Property")).
+The `MultipleInstancesEnum` enumerator has three values, which can be mapped to three
+of the four valid values, but there is no value corresponding to `TASK_INSTANCES_STOP_EXISTING`.
+The result of this omission is that a workaround is required to
+accommodate the `StopExisting` value for the `MultipleInstances` parameter,
+which would not be necessary if the enumerator had all four valid values.
+
 ### ExecuteAsCredential
 
 #### When Using a BUILTIN Group