From 5965697f1af9c85ddee1118c4d9ca85a8547421d Mon Sep 17 00:00:00 2001 From: Chris H <53898223+Borgquite@users.noreply.github.com> Date: Fri, 15 Nov 2024 11:29:08 +0000 Subject: [PATCH] ScheduledTask: Update documentation with more parameter requirements (#439) --- CHANGELOG.md | 1 + .../DSC_ScheduledTask/DSC_ScheduledTask.psm1 | 18 ++++++++++++------ .../DSC_ScheduledTask.schema.mof | 8 ++++---- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e46d0eb1..0e1d0ce1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Updated RandomDelay logic from a blacklist to a whitelist. - Updated Delay parameter logic to reflect other TimeSpan based values. - Updated unit tests to use Should -Invoke for Pester 5 compatibility. + - Updated various parameters with requirements in documentation. - `VirtualMemory` fix incorrect variable name - `SmbServerConfiguration` remove errant argument - Update all calls to edit the registry so that the value Type is explicitly set. diff --git a/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.psm1 b/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.psm1 index b96e2ac1..0125e405 100644 --- a/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.psm1 +++ b/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.psm1 @@ -124,7 +124,8 @@ function Get-TargetResource .PARAMETER DaysInterval Specifies the interval between the days in the schedule. An interval of 1 produces - a daily schedule. An interval of 2 produces an every-other day schedule. + a daily schedule. An interval of 2 produces an every-other day schedule. This + parameter is only valid in combination with the Daily Schedule Type. .PARAMETER RandomDelay Specifies a random amount of time to delay the start time of the trigger. The @@ -143,11 +144,13 @@ function Get-TargetResource Specifies the amount of time for the trigger that Task Scheduler is allowed to complete the task. .PARAMETER DaysOfWeek - Specifies an array of the days of the week on which Task Scheduler runs the task. + Specifies an array of the days of the week on which Task Scheduler runs the task. This + parameter is only valid in combination with the Weekly Schedule Type. .PARAMETER WeeksInterval Specifies the interval between the weeks in the schedule. An interval of 1 produces - a weekly schedule. An interval of 2 produces an every-other week schedule. + a weekly schedule. An interval of 2 produces an every-other week schedule. This + parameter is only valid in combination with the Weekly Schedule Type. .PARAMETER User Specifies the identifier of a user that will trigger the task to start. This @@ -1130,7 +1133,8 @@ function Set-TargetResource .PARAMETER DaysInterval Specifies the interval between the days in the schedule. An interval of 1 produces - a daily schedule. An interval of 2 produces an every-other day schedule. + a daily schedule. An interval of 2 produces an every-other day schedule. This + parameter is only valid in combination with the Daily Schedule Type. .PARAMETER RandomDelay Specifies a random amount of time to delay the start time of the trigger. The @@ -1149,11 +1153,13 @@ function Set-TargetResource Specifies the amount of time for the trigger that Task Scheduler is allowed to complete the task. .PARAMETER DaysOfWeek - Specifies an array of the days of the week on which Task Scheduler runs the task. + Specifies an array of the days of the week on which Task Scheduler runs the task. This + parameter is only valid in combination with the Weekly Schedule Type. .PARAMETER WeeksInterval Specifies the interval between the weeks in the schedule. An interval of 1 produces - a weekly schedule. An interval of 2 produces an every-other week schedule. + a weekly schedule. An interval of 2 produces an every-other week schedule. This + parameter is only valid in combination with the Weekly Schedule Type. .PARAMETER User Specifies the identifier of a user that will trigger the task to start. This diff --git a/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.schema.mof b/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.schema.mof index ff5c6731..7583fe4d 100644 --- a/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.schema.mof +++ b/source/DSCResources/DSC_ScheduledTask/DSC_ScheduledTask.schema.mof @@ -16,13 +16,13 @@ class DSC_ScheduledTask : OMI_BaseResource [Write, Description("Run the task as one of the built in service accounts. When set ExecuteAsCredential will be ignored and LogonType will be set to 'ServiceAccount'."), ValueMap{"SYSTEM", "LOCAL SERVICE", "NETWORK SERVICE"}, Values{"SYSTEM", "LOCAL SERVICE", "NETWORK SERVICE"}] string BuiltInAccount; [Write, Description("The credential this task should execute as. If not specified defaults to running as the local system account."), EmbeddedInstance("MSFT_Credential")] string ExecuteAsCredential; [Write, Description("The gMSA (Group Managed Service Account) this task should execute as. Cannot be used in combination with ExecuteAsCredential or BuiltInAccount.")] string ExecuteAsGMSA; - [Write, Description("Specifies the interval between the days in the schedule. An interval of 1 produces a daily schedule. An interval of 2 produces an every-other day schedule.")] Uint32 DaysInterval; + [Write, Description("Specifies the interval between the days in the schedule. An interval of 1 produces a daily schedule. An interval of 2 produces an every-other day schedule. Can only be used in combination with ScheduleType Daily.")] Uint32 DaysInterval; [Write, Description("Specifies a random amount of time to delay the start time of the trigger. The delay time is a random time between the time the task triggers and the time that you specify in this setting. Can only be used in combination with ScheduleType Once, Daily and Weekly.")] String RandomDelay; [Write, Description("Specifies how long the repetition pattern repeats after the task starts. May be set to `Indefinitely` to specify an indefinite duration.")] String RepetitionDuration; [Write, Description("Indicates that Task Scheduler stops all running tasks at the end of the repetition duration. Defaults to $false.")] Boolean StopAtDurationEnd; [Write, Description("Specifies the amount of time for the trigger that Task Scheduler is allowed to complete the task.")] String TriggerExecutionTimeLimit; - [Write, Description("Specifies an array of the days of the week on which Task Scheduler runs the task.")] String DaysOfWeek[]; - [Write, Description("Specifies the interval between the weeks in the schedule. An interval of 1 produces a weekly schedule. An interval of 2 produces an every-other week schedule.")] Uint32 WeeksInterval; + [Write, Description("Specifies an array of the days of the week on which Task Scheduler runs the task. Can only be used in combination with ScheduleType Weekly.")] String DaysOfWeek[]; + [Write, Description("Specifies the interval between the weeks in the schedule. An interval of 1 produces a weekly schedule. An interval of 2 produces an every-other week schedule. Can only be used in combination with ScheduleType Weekly.")] Uint32 WeeksInterval; [Write, Description("Specifies the identifier of a user that will trigger the task to start. Can only be used in combination with ScheduleType AtLogon and OnSessionState.")] String User; [Write, Description("Indicates whether the task is prohibited to run on demand or not. Defaults to $false.")] Boolean DisallowDemandStart; [Write, Description("Indicates whether the task is prohibited to be terminated or not. Defaults to $false.")] Boolean DisallowHardTerminate; @@ -48,7 +48,7 @@ class DSC_ScheduledTask : OMI_BaseResource [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. For the query schema please check: https://docs.microsoft.com/en-us/windows/desktop/WES/queryschema-schema. Can only be used in combination with ScheduleType OnEvent.")] String EventSubscription; - [Write, Description("Specifies the EventValueQueries. Receives a hashtable where the key is a property value for an event and the value is an XPath event query. For more detailed syntax check: https://learn.microsoft.com/en-us/windows/win32/taskschd/eventtrigger-valuequeries."), EmbeddedInstance("MSFT_KeyValuePair")] String EventValueQueries[]; + [Write, Description("Specifies the EventValueQueries. Receives a hashtable where the key is a property value for an event and the value is an XPath event query. For more detailed syntax check: https://learn.microsoft.com/en-us/windows/win32/taskschd/eventtrigger-valuequeries. Can only be used in combination with ScheduleType OnEvent."), EmbeddedInstance("MSFT_KeyValuePair")] String EventValueQueries[]; [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 AtLogon, AtStartup, OnEvent, AtCreation and OnSessionState.")] String Delay; [Write, Description("Specifies the kind of session state change that would trigger a task launch. Can only be used in combination with ScheduleType OnSessionState."), ValueMap{"OnConnectionFromLocalComputer", "OnDisconnectFromLocalComputer", "OnConnectionFromRemoteComputer", "OnDisconnectFromRemoteComputer", "OnWorkstationLock", "OnWorkstationUnlock"}, Values{"OnConnectionFromLocalComputer", "OnDisconnectFromLocalComputer", "OnConnectionFromRemoteComputer", "OnDisconnectFromRemoteComputer", "OnWorkstationLock", "OnWorkstationUnlock"}] string StateChange; };