Register-StmClusteredScheduledTask
SYNOPSIS
Registers a new clustered scheduled task on a Windows failover cluster.
SYNTAX
XmlString (Default)
Register-StmClusteredScheduledTask -TaskName <String> -Cluster <String> -Xml <String>
-TaskType <ClusterTaskTypeEnum> [-Credential <PSCredential>] [-ProgressAction <ActionPreference>] [-WhatIf]
[-Confirm] [<CommonParameters>]
XmlFile
Register-StmClusteredScheduledTask -TaskName <String> -Cluster <String> -XmlPath <String>
-TaskType <ClusterTaskTypeEnum> [-Credential <PSCredential>] [-ProgressAction <ActionPreference>] [-WhatIf]
[-Confirm] [<CommonParameters>]
DESCRIPTION
The Register-StmClusteredScheduledTask function registers a new clustered scheduled task on a Windows failover cluster using an XML definition. This function supports two parameter sets: one for providing the XML content as a string and another for providing the path to an XML file. The function creates a CIM session to the cluster and registers the task using the native Register-ClusteredScheduledTask cmdlet. Clustered scheduled tasks can be configured to run on specific nodes, any node, or across the entire cluster depending on the task type specified.
EXAMPLES
EXAMPLE 1
$xmlContent = @"
<?xml version="1.0" encoding="UTF-16"?>
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
<Triggers>
<TimeTrigger>
<Repetition>
<Interval>PT1H</Interval>
<StopAtDurationEnd>false</StopAtDurationEnd>
</Repetition>
<Enabled>true</Enabled>
</TimeTrigger>
</Triggers>
<Principals>
<Principal id="Author">
<RunLevel>HighestAvailable</RunLevel>
</Principal>
</Principals>
<Settings>
<MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
<AllowHardTerminate>true</AllowHardTerminate>
<StartWhenAvailable>false</StartWhenAvailable>
<RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
<IdleSettings>
<StopOnIdleEnd>true</StopOnIdleEnd>
<RestartOnIdle>false</RestartOnIdle>
</IdleSettings>
<AllowStartOnDemand>true</AllowStartOnDemand>
<Enabled>true</Enabled>
<Hidden>false</Hidden>
<RunOnlyIfIdle>false</RunOnlyIfIdle>
<WakeToRun>false</WakeToRun>
<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
<Priority>7</Priority>
</Settings>
<Actions Context="Author">
<Exec>
<Command>powershell.exe</Command>
<Arguments>-Command "Write-Host 'Hello from clustered task'</Arguments>
</Exec>
</Actions>
</Task>
"@
Register-StmClusteredScheduledTask -TaskName "MyClusteredTask" -Cluster "MyCluster" -Xml $xmlContent -TaskType "AnyNode"
Registers a new clustered scheduled task named "MyClusteredTask" on cluster "MyCluster" using XML content provided as a string. The task is configured to run on any node in the cluster.
EXAMPLE 2
Register-StmClusteredScheduledTask -TaskName "BackupTask" -Cluster "MyCluster.contoso.com" -XmlPath "C:\Tasks\BackupTask.xml" -TaskType "ClusterWide"
Registers a new clustered scheduled task named "BackupTask" on cluster "MyCluster.contoso.com" using an XML file. The task is configured to run cluster-wide.
EXAMPLE 3
$creds = Get-Credential
Register-StmClusteredScheduledTask -TaskName "MaintenanceTask" -Cluster "MyCluster" -XmlPath "C:\Tasks\MaintenanceTask.xml" -TaskType "ResourceSpecific" -Credential $creds
Registers a new clustered scheduled task named "MaintenanceTask" on cluster "MyCluster" using specified credentials. The task is configured as resource-specific.
PARAMETERS
-TaskName
Specifies the name for the new clustered scheduled task. This parameter is mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Cluster
Specifies the name or FQDN of the cluster where the scheduled task will be registered. This parameter is mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Xml
Specifies the XML content that defines the scheduled task configuration. This parameter is mandatory when using the XmlString parameter set. The XML should follow the Task Scheduler schema format.
Type: String
Parameter Sets: XmlString
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-XmlPath
Specifies the path to an XML file that contains the scheduled task configuration. This parameter is mandatory when using the XmlFile parameter set. The file should contain valid Task Scheduler XML format.
Type: String
Parameter Sets: XmlFile
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TaskType
Specifies the type of clustered scheduled task to register. Valid values are: - ResourceSpecific: Task runs on a specific cluster resource - AnyNode: Task can run on any node in the cluster - ClusterWide: Task runs across the entire cluster This parameter is mandatory.
Type: ClusterTaskTypeEnum
Parameter Sets: (All)
Aliases:
Accepted values: ResourceSpecific, AnyNode, ClusterWide
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Credential
Specifies credentials to use when connecting to the cluster. If not provided, the current user's credentials will be used for the connection.
Type: PSCredential
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: [System.Management.Automation.PSCredential]::Empty
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
None. You cannot pipe objects to Register-StmClusteredScheduledTask.
OUTPUTS
Microsoft.Management.Infrastructure.CimInstance#MSFT_ClusteredScheduledTask
Returns the registered clustered scheduled task object containing:
- TaskName: The name of the registered task
- TaskType: The type of clustered task
- CurrentOwner: The current owner node
- State: The current state of the task
- Cluster: The cluster where the task is registered
NOTES
This function requires: - The FailoverClusters PowerShell module to be installed on the target cluster - Appropriate permissions to register clustered scheduled tasks - Network connectivity to the cluster - Valid Task Scheduler XML format for the task definition
The XML definition must follow the Task Scheduler schema and include all required elements such as triggers, principals, settings, and actions. The function validates the XML format before attempting to register the task.
Different task types have different behaviors: - ResourceSpecific: Task is tied to a specific cluster resource - AnyNode: Task can run on any available node - ClusterWide: Task runs across the entire cluster infrastructure