New-CMTaskSequenceDeployment
Create a task sequence deployment.
Syntax
New-CMTaskSequenceDeployment
[-AlertDateTime <DateTime>]
[-AllowFallback <Boolean>]
[-AllowSharedContent <Boolean>]
[-Availability <MakeAvailableToType>]
[-DeadlineDateTime <DateTime>]
[-DeploymentOption <DeploymentOptionType>]
[-DeployPurpose <DeployPurposeType>]
[-InputObject] <IResultObject>
[-InternetOption <Boolean>]
[-PercentFailure <Int32>]
[-PercentSuccess <Int32>]
[-RerunBehavior <RerunBehaviorType>]
[-RunFromSoftwareCenter <Boolean>]
[-Schedule <IResultObject[]>]
[-ScheduleEvent <ScheduleEventType[]>]
[-ShowTaskSequenceProgress <Boolean>]
[-SoftwareInstallation <Boolean>]
[-SystemRestart <Boolean>]
[-UseUtcForAvailableSchedule <Boolean>]
[-UseUtcForExpireSchedule <Boolean>]
[-DistributeCollectionName <String>]
[-DistributeContent]
[-DistributionPointGroupName <String>]
[-DistributionPointName <String>]
[-AvailableDateTime <DateTime>]
[-Comment <String>]
[-PersistOnWriteFilterDevice <Boolean>]
[-SendWakeupPacket <Boolean>]
[-UseMeteredNetwork <Boolean>]
[-Collection <IResultObject>]
[-CollectionId <String>]
[-CollectionName <String>]
[-DisableWildcardHandling]
[-ForceWildcardHandling]
[-WhatIf]
[-Confirm]
[<CommonParameters>] New-CMTaskSequenceDeployment
[-AlertDateTime <DateTime>]
[-AllowFallback <Boolean>]
[-AllowSharedContent <Boolean>]
[-Availability <MakeAvailableToType>]
[-DeadlineDateTime <DateTime>]
[-DeploymentOption <DeploymentOptionType>]
[-DeployPurpose <DeployPurposeType>]
[-InternetOption <Boolean>]
[-PercentFailure <Int32>]
[-PercentSuccess <Int32>]
[-RerunBehavior <RerunBehaviorType>]
[-RunFromSoftwareCenter <Boolean>]
[-Schedule <IResultObject[]>]
[-ScheduleEvent <ScheduleEventType[]>]
[-ShowTaskSequenceProgress <Boolean>]
[-SoftwareInstallation <Boolean>]
[-SystemRestart <Boolean>]
[-TaskSequencePackageId] <String>
[-UseUtcForAvailableSchedule <Boolean>]
[-UseUtcForExpireSchedule <Boolean>]
[-DistributeCollectionName <String>]
[-DistributeContent]
[-DistributionPointGroupName <String>]
[-DistributionPointName <String>]
[-AvailableDateTime <DateTime>]
[-Comment <String>]
[-PersistOnWriteFilterDevice <Boolean>]
[-SendWakeupPacket <Boolean>]
[-UseMeteredNetwork <Boolean>]
[-Collection <IResultObject>]
[-CollectionId <String>]
[-CollectionName <String>]
[-DisableWildcardHandling]
[-ForceWildcardHandling]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Description
The New-CMTaskSequenceDeployment cmdlet creates a task sequence deployment. A task sequence deployment assigns a task sequence to a collection of computers.
Note
Run Configuration Manager cmdlets from the Configuration Manager site drive, for example PS XYZ:\>. For more information, see getting started.
Examples
Example 1: Deploy a task sequence with many common parameters
This example does the following actions:
- Use the Get-CMTaskSequence cmdlet to get the task sequence object to deploy, and saves it in the $DeployTS variable
- Define the collection as the target of the deployment in the variable $DeployCollection
- Define the deployment available time at 8:00 PM on November 25, 2025, in the variable $DeployAvailableTime
- Define the deployment expiration time at 8:00 PM on January 25, 2026, in the variable $DeployExpireTime
- Define the deployment deadline at 8:00 PM on December 25, 2025, in the variable $ScheduleDateTime
- Use the New-CMSchedule cmdlet to create a schedule object for the deadline with a daily recurring schedule.
- Deploy the task sequence
$DeployTS = Get-CMTaskSequence -TaskSequencePackageId 'PS104823'
$DeployCollection = 'PS11B7C4'
$DeployAvailableTime = [datetime]::ParseExact("20251125-200000", "yyyyMMdd-HHmmss", $null)
$DeployExpireTime = [datetime]::ParseExact("20260125-200000", "yyyyMMdd-HHmmss", $null)
$ScheduleDateTime = [datetime]::ParseExact("20251225-200000", "yyyyMMdd-HHmmss", $null)
$DeploySchedule = New-CMSchedule -DurationInterval Days -RecurInterval Days -RecurCount 1 -DurationCount 0 -Start $ScheduleDateTime
New-CMTaskSequenceDeployment -InputObject $DeployTS -DeployPurpose Required -AvailableDateTime $DeployAvailableTime -Availability Clients -RerunBehavior AlwaysRerunProgram -Schedule $DeploySchedule -CollectionId $DeployCollection -ShowTaskSequenceProgress $true -DeploymentOption DownloadAllContentLocallyBeforeStartingTaskSequence -RunFromSoftwareCenter $true -DeadlineDateTime $DeployExpireTimeParameters
-AlertDateTime
If you enable a deployment alert, use this parameter to specify a time for the alert.
| Type: | DateTime |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AllowFallback
Allow clients to use distribution points from the default site boundary group.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AllowSharedContent
Allow clients to use distribution points from a neighbor boundary group.
| Type: | Boolean |
| Aliases: | AllowUseRemoteDistributionPoint |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Availability
Specify whether to make this task sequence available to Configuration Manager clients, and whether it's available to run when you deploy an OS by using boot media, prestaged media, or PXE.
| Type: | MakeAvailableToType |
| Aliases: | MakeAvailableTo |
| Accepted values: | Clients, ClientsMediaAndPxe, MediaAndPxe, MediaAndPxeHidden |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AvailableDateTime
Specify when this deployment is available.
Use -DeadlineDateTime to specify when the deployment expires, and -Schedule to specify the deployment assignment, or deadline.
| Type: | DateTime |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Collection
Specify a collection object as the target for this task sequence deployment. To get this object, use the Get-CMCollection cmdlet.
| Type: | IResultObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CollectionId
Specify a collection ID as the target for this task sequence deployment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CollectionName
Specify a collection name as the target for this task sequence deployment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-Comment
Specify an optional comment for the task sequence deployment.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DeadlineDateTime
Use this parameter to specify when the deployment expires.
Use -AvailableDateTime to specify when the deployment is available, and -Schedule to specify the deployment assignment, or deadline.
| Type: | DateTime |
| Aliases: | DeploymentExpireDateTime |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DeploymentOption
Specify how clients interact with the distribution points to get content for the task sequence. Not all options are available in specific scenarios. For more information, see Deploy a task sequence - Deployment options.
| Type: | DeploymentOptionType |
| Accepted values: | DownloadContentLocallyWhenNeededByRunningTaskSequence, DownloadAllContentLocallyBeforeStartingTaskSequence, RunFromDistributionPoint |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DeployPurpose
Specify whether this deployment is available for users to install, or it's required to install at the deadline.
| Type: | DeployPurposeType |
| Accepted values: | Available, Required |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisableWildcardHandling
This parameter treats wildcard characters as literal character values. You can't combine it with ForceWildcardHandling.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DistributeCollectionName
The site distributes content to the distribution point groups that are associated with this collection name.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DistributeContent
Add this parameter to distribute the task sequence content when you create this deployment. Clients can't install the task sequence until you distribute content to distribution points that the clients can access.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DistributionPointGroupName
The site distributes content to this distribution point group.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DistributionPointName
The site distributes content to this distribution point.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ForceWildcardHandling
This parameter processes wildcard characters and may lead to unexpected behavior (not recommended). You can't combine it with DisableWildcardHandling.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Specifies a task sequence object to deploy. To get a task sequence object, use the Get-CMTaskSequence cmdlet.
| Type: | IResultObject |
| Aliases: | TaskSequence |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-InternetOption
Allow the task sequence to run for clients on the internet.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PercentFailure
If you create an alert for failed deployments, the site generates an alert when the percentage of failed deployments is higher than this number.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PercentSuccess
If you create an alert for successful deployments, the site generates an alert when the percentage of successful deployments is lower than this number.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PersistOnWriteFilterDevice
Configure how the client handles the write filter on Windows Embedded devices.
$true: Commit changes at the deadline or during a maintenance window. A restart is required.$false: Apply content on the overlay and commit later.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RerunBehavior
Specify whether the task sequence reruns on a computer if it previously ran before the scheduled mandatory time. By default, the task sequence always reruns.
| Type: | RerunBehaviorType |
| Accepted values: | NeverRerunDeployedProgram, AlwaysRerunProgram, RerunIfFailedPreviousAttempt, RerunIfSucceededOnPreviousAttempt |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RunFromSoftwareCenter
Allow users to run the program independently of assignments.
| Type: | Boolean |
| Aliases: | AllowUsersRunIndependently |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Schedule
Use this parameter to specify the deployment assignment, or deadline.
Use -AvailableDateTime to specify when the deployment is available, and -DeadlineDateTime to specify when the deployment expires.
Specify an array of schedule objects. A schedule object defines the mandatory assignment schedule for a deployment. To create a schedule object, use the New-CMSchedule cmdlet.
| Type: | IResultObject[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ScheduleEvent
Specifies an array of events that determine when the task sequence deployment runs.
| Type: | ScheduleEventType[] |
| Accepted values: | AsSoonAsPossible, LogOn, LogOff |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SendWakeupPacket
Indicates whether to send a wake-up packet to computers before the deployment begins. If this value is $True, Configuration Manager wakes a computer from sleep. If this value is $False, it doesn't wake computers from sleep. For computers to wake, first configure Wake On LAN.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ShowTaskSequenceProgress
Indicates whether to show a process dialog for a task sequence.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SoftwareInstallation
When the installation deadline is reached, set this parameter to $true to allow the task sequence to install outside the maintenance window.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SystemRestart
When the installation deadline is reached, set this parameter to $true to allow system restart if necessary outside the maintenance window.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TaskSequencePackageId
Specify the ID of the task sequence to deploy.
| Type: | String |
| Aliases: | PackageId, TaskSequenceId |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseMeteredNetwork
Indicates whether to allow clients on a metered internet connection to download content after the installation deadline, which might incur additional costs.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseUtcForAvailableSchedule
Indicates whether client computers use UTC time to determine the availability of a program. UTC time makes the task sequence available at the same time for all computers.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseUtcForExpireSchedule
Indicates whether client computers use UTC time to determine the expiration of a program. UTC time makes the task sequence available at the same time for all computers.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet doesn't run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
Microsoft.ConfigurationManagement.ManagementProvider.IResultObject
Outputs
IResultObject
Notes
Make sure to use the schedule parameters appropriately:
-AvailableDateTime: Specify when this deployment is available.
-DeadlineDateTime: Specify when the deployment expires.
-Schedule: Specify the deployment assignment, or deadline.