Note
Access to this page requires authorization. You can try signing in or .
Access to this page requires authorization. You can try .
New-CMTaskSequenceDeployment
- Module:
- ConfigurationManager Module
Create a task sequence deployment.
Syntax
SearchByValueMandatory (Default)
New-CMTaskSequenceDeployment
[-InputObject] <IResultObject>
[-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>]
[-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>]
SearchPackageByIdMandatory
New-CMTaskSequenceDeployment
[-TaskSequencePackageId] <String>
[-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>]
[-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 $DeployExpireTime
Parameters
-AlertDateTime
If you enable a deployment alert, use this parameter to specify a time for the alert.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-AllowFallback
Allow clients to use distribution points from the default site boundary group.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-AllowSharedContent
Allow clients to use distribution points from a neighbor boundary group.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | AllowUseRemoteDistributionPoint |
Parameter sets
-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.
Parameter properties
| Type: | MakeAvailableToType |
| Default value: | None |
| Accepted values: | Clients, ClientsMediaAndPxe, MediaAndPxe, MediaAndPxeHidden |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | MakeAvailableTo |
Parameter sets
-AvailableDateTime
Specify when this deployment is available.
Use -DeadlineDateTime to specify when the deployment expires, and -Schedule to specify the deployment assignment, or deadline.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Collection
Specify a collection object as the target for this task sequence deployment. To get this object, use the Get-CMCollection cmdlet.
Parameter properties
| Type: | IResultObject |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-CollectionId
Specify a collection ID as the target for this task sequence deployment.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-CollectionName
Specify a collection name as the target for this task sequence deployment.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | True |
| DontShow: | False |
Parameter sets
-Comment
Specify an optional comment for the task sequence deployment.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
-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.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | DeploymentExpireDateTime |
Parameter sets
-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.
Parameter properties
| Type: | DeploymentOptionType |
| Default value: | None |
| Accepted values: | DownloadContentLocallyWhenNeededByRunningTaskSequence, DownloadAllContentLocallyBeforeStartingTaskSequence, RunFromDistributionPoint |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-DeployPurpose
Specify whether this deployment is available for users to install, or it's required to install at the deadline.
Parameter properties
| Type: | DeployPurposeType |
| Default value: | None |
| Accepted values: | Available, Required |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-DisableWildcardHandling
This parameter treats wildcard characters as literal character values. You can't combine it with ForceWildcardHandling.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-DistributeCollectionName
The site distributes content to the distribution point groups that are associated with this collection name.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-DistributionPointGroupName
The site distributes content to this distribution point group.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-DistributionPointName
The site distributes content to this distribution point.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-ForceWildcardHandling
This parameter processes wildcard characters and may lead to unexpected behavior (not recommended). You can't combine it with DisableWildcardHandling.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-InputObject
Specifies a task sequence object to deploy. To get a task sequence object, use the Get-CMTaskSequence cmdlet.
Parameter properties
| Type: | IResultObject |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | TaskSequence |
Parameter sets
-InternetOption
Allow the task sequence to run for clients on the internet.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | RerunBehaviorType |
| Default value: | None |
| Accepted values: | NeverRerunDeployedProgram, AlwaysRerunProgram, RerunIfFailedPreviousAttempt, RerunIfSucceededOnPreviousAttempt |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-RunFromSoftwareCenter
Allow users to run the program independently of assignments.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | AllowUsersRunIndependently |
Parameter sets
-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.
Parameter properties
| Type: | IResultObject[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-ScheduleEvent
Specifies an array of events that determine when the task sequence deployment runs.
Parameter properties
| Type: | ScheduleEventType[] |
| Default value: | None |
| Accepted values: | AsSoonAsPossible, LogOn, LogOff |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-ShowTaskSequenceProgress
Indicates whether to show a process dialog for a task sequence.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-SoftwareInstallation
When the installation deadline is reached, set this parameter to $true to allow the task sequence to install outside the maintenance window.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-SystemRestart
When the installation deadline is reached, set this parameter to $true to allow system restart if necessary outside the maintenance window.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-TaskSequencePackageId
Specify the ID of the task sequence to deploy.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | PackageId, TaskSequenceId |
Parameter sets
-UseMeteredNetwork
Indicates whether to allow clients on a metered internet connection to download content after the installation deadline, which might incur additional costs.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet doesn't run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
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.
Related Links
Feedback
Was this page helpful?