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

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  by changing `CopyDirectories` to `CopyPaths` - Fixes [Issue #332](https://github.com/dsccommunity/ComputerManagementDsc/issues/332).
  - 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
 

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 ([System.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