Carbon_ScheduledTask

DSC resource for configuring scheduled tasks.

Syntax

Carbon_ScheduledTask [String] #ResourceName
{
    Name = [string]
    [DependsOn = [string[]]]
    [Ensure = [string]{ Absent | Present }]
    [PsDscRunAsCredential = [PSCredential]]
    [TaskCredential = [PSCredential]]
    [TaskXml = [string]]
}

Description

The Carbon_ScheduledTask resource configures scheduled tasks using schtasks.exe with Task Scheduler XML.

The task is installed when the Ensure property is set to Present. If the task already exists, and the XML of the current task doesn't match the XML passed in, the task is deleted, and a new task is created in its place. The XML comparison is pretty dumb: it compares the XML document(s) as a giant string, not element by element. This means if your XML doesn't order elements in the same way as schtasks.exe /query /xml, then your task will always be deleted and re-created. This may or may not be a problem for you.

Carbon_ScheduledTask is new in Carbon 2.0.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Name String

The name of the scheduled task to return. Wildcards supported. This must be the full task name, i.e. the task's path/location and its name.

true false
TaskXml String

Install the task from this XML.

false false
TaskCredential PSCredential

The principal the task should run as. Use Principal parameter to run as a built-in security principal. Required if Interactive or NoPassword switches are used.

false false
Ensure String

If Present, the service is installed/updated. If Absent, the service is removed.

false false Present

EXAMPLE 1

Demonstrates how to install a new or update an existing scheduled task that runs as a built-in user. The user's SID should be declared in the task XML file.

Carbon_ScheduledTask InstallScheduledTask
{
    Name = 'ClearApplicationCache';
    TaskXml = (Get-Content -Path $clearApplicationCacheTaskPath.xml -Raw);
}

EXAMPLE 2

Demonstrates how to install a new or update an existing scheduled task that runs as a custom user.

Carbon_ScheduledTask InstallScheduledTask
{
    Name = 'ClearApplicationCache';
    TaskXml = (Get-Content -Path $clearApplicationCacheTaskPath.xml -Raw);
    TaskCredential = (Get-Credential 'runasuser');
}

EXAMPLE 3

Demonstrates how to remove a scheduled task.

Carbon_ScheduledTask InstallScheduledTask
{
    Name = 'ClearApplicationCache';
    Ensure = 'Absent';
}