New-CMPackageDeployment

Module:

ConfigurationManager

Deploy a legacy package to a collection.

Syntax

New-CMPackageDeployment
   [-AllowFallback <Boolean>]
   [-AllowSharedContent <Boolean>]
   [-DeployPurpose <DeployPurposeType>]
   [-FastNetworkOption <FastNetworkOptionType>]
   [-Package] <IResultObject>
   [-PersistOnWriteFilterDevice <Boolean>]
   -ProgramName <String>
   [-RerunBehavior <RerunBehaviorType>]
   [-RunFromSoftwareCenter <Boolean>]
   [-Schedule <IResultObject[]>]
   [-ScheduleEvent <ScheduleEventType>]
   [-SendWakeupPacket <Boolean>]
   [-SlowNetworkOption <SlowNetworkOptionType>]
   [-SoftwareInstallation <Boolean>]
   [-StandardProgram]
   [-SystemRestart <Boolean>]
   [-UseUtcForAvailableSchedule <Boolean>]
   [-UseUtcForExpireSchedule <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-AllowFallback <Boolean>]
   [-AllowSharedContent <Boolean>]
   [-DeployPurpose <DeployPurposeType>]
   [-FastNetworkOption <FastNetworkOptionType>]
   -PackageName <String>
   [-PersistOnWriteFilterDevice <Boolean>]
   -ProgramName <String>
   [-RerunBehavior <RerunBehaviorType>]
   [-RunFromSoftwareCenter <Boolean>]
   [-Schedule <IResultObject[]>]
   [-ScheduleEvent <ScheduleEventType>]
   [-SendWakeupPacket <Boolean>]
   [-SlowNetworkOption <SlowNetworkOptionType>]
   [-SoftwareInstallation <Boolean>]
   [-StandardProgram]
   [-SystemRestart <Boolean>]
   [-UseUtcForAvailableSchedule <Boolean>]
   [-UseUtcForExpireSchedule <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-AllowFallback <Boolean>]
   [-AllowSharedContent <Boolean>]
   [-DeployPurpose <DeployPurposeType>]
   [-FastNetworkOption <FastNetworkOptionType>]
   -PackageId <String>
   [-PersistOnWriteFilterDevice <Boolean>]
   -ProgramName <String>
   [-RerunBehavior <RerunBehaviorType>]
   [-RunFromSoftwareCenter <Boolean>]
   [-Schedule <IResultObject[]>]
   [-ScheduleEvent <ScheduleEventType>]
   [-SendWakeupPacket <Boolean>]
   [-SlowNetworkOption <SlowNetworkOptionType>]
   [-SoftwareInstallation <Boolean>]
   [-StandardProgram]
   [-SystemRestart <Boolean>]
   [-UseUtcForAvailableSchedule <Boolean>]
   [-UseUtcForExpireSchedule <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-AllowFallback <Boolean>]
   [-AllowSharedContent <Boolean>]
   [-DeployPurpose <DeployPurposeType>]
   [-FastNetworkOption <FastNetworkOptionType>]
   [-PersistOnWriteFilterDevice <Boolean>]
   [-Program] <IResultObject>
   [-RerunBehavior <RerunBehaviorType>]
   [-RunFromSoftwareCenter <Boolean>]
   [-Schedule <IResultObject[]>]
   [-ScheduleEvent <ScheduleEventType>]
   [-SendWakeupPacket <Boolean>]
   [-SlowNetworkOption <SlowNetworkOptionType>]
   [-SoftwareInstallation <Boolean>]
   [-StandardProgram]
   [-SystemRestart <Boolean>]
   [-UseUtcForAvailableSchedule <Boolean>]
   [-UseUtcForExpireSchedule <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-DeployPurpose <DeployPurposeType>]
   [-DeviceProgram]
   -PackageName <String>
   -ProgramName <String>
   [-RecurUnit <RecurUnitType>]
   [-RecurValue <Int32>]
   [-Rerun <Boolean>]
   [-UseUtc <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-DeployPurpose <DeployPurposeType>]
   [-DeviceProgram]
   -PackageId <String>
   -ProgramName <String>
   [-RecurUnit <RecurUnitType>]
   [-RecurValue <Int32>]
   [-Rerun <Boolean>]
   [-UseUtc <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-DeployPurpose <DeployPurposeType>]
   [-DeviceProgram]
   [-Package] <IResultObject>
   -ProgramName <String>
   [-RecurUnit <RecurUnitType>]
   [-RecurValue <Int32>]
   [-Rerun <Boolean>]
   [-UseUtc <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-CMPackageDeployment
   [-DeployPurpose <DeployPurposeType>]
   [-DeviceProgram]
   [-Program] <IResultObject>
   [-RecurUnit <RecurUnitType>]
   [-RecurValue <Int32>]
   [-Rerun <Boolean>]
   [-SendWakeupPacket <Boolean>]
   [-UseUtc <Boolean>]
   [-DistributeCollectionName <String>]
   [-DistributeContent]
   [-DistributionPointGroupName <String>]
   [-DistributionPointName <String>]
   [-AvailableDateTime <DateTime>]
   [-Comment <String>]
   [-DeadlineDateTime <DateTime>]
   [-UseMeteredNetwork <Boolean>]
   [-Collection <IResultObject>]
   [-CollectionId <String>]
   [-CollectionName <String>]
   [-DisableWildcardHandling]
   [-ForceWildcardHandling]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

Use this cmdlet to deploy a package to resources in a collection. You can specify the collection by ID, name, or pass an object.

For other deployment settings that you can't configure with this cmdlet, use Set-CMPackageDeployment.

For more information, see Packages and programs in Configuration Manager.

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 package by ID

This command creates a deployment of the package with ID XYZ00001 to the collection with ID XYZ0003F.

$pkgId = "XYZ00001"
$collId = "XYZ0003F"
New-CMPackageDeployment -StandardProgram -PackageId $pkgId -ProgramName "ScanState" -CollectionID $collId -Comment "Use USMT to scan for data" -DeployPurpose Available

Example 2: Deploy a package as required with a deadline

The first command sets a variable for a deadline to 10 days from now at 8:00 PM. The second command creates a schedule object based on that deadline that recurs daily. The third command creates the package deployment with that schedule.

[datetime]$DeadlineTime = (Get-Date -Hour 20 -Minute 0 -Second 0).AddDays(10)

$NewScheduleDeadline = New-CMSchedule -Start $DeadlineTime -Nonrecurring

$pkgId = "XYZ00001"
$progName = "Run"
$collId = "XYZ0003F"

New-CMPackageDeployment -StandardProgram -PackageId $pkgId -ProgramName $progName -DeployPurpose Required -CollectionId $collId -FastNetworkOption DownloadContentFromDistributionPointAndRunLocally -SlowNetworkOption DownloadContentFromDistributionPointAndLocally -RerunBehavior RerunIfFailedPreviousAttempt -Schedule $NewScheduleDeadline

Parameters

-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
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.

To get a DateTime object, use the Get-Date cmdlet.

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 package 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 package 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 package deployment.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	True

-Comment

Specify an optional comment for this package deployment.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

Add this parameter to prompt 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.

To get a DateTime object, use the Get-Date cmdlet.

Type:	DateTime
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

-DeviceProgram

If the program for the package that you're deploying is a device-type program, specify this parameter.

Otherwise, use the StandardProgram parameter. The standard program type is for computers with the Configuration Manager client.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
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 package content when you create this deployment. Clients can't install the package 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

-FastNetworkOption

Specify the behavior when the client uses a distribution point from the current boundary group:

• Run program from distribution point
• Download content from distribution point and run locally

If you don't specify this parameter, it uses DownloadContentFromDistributionPointAndRunLocally by default. This option is more secure, because the client validates the content hash before it runs the program.

Type:	FastNetworkOptionType
Accepted values:	RunProgramFromDistributionPoint, DownloadContentFromDistributionPointAndRunLocally
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

-Package

Specify a package object with the program to deploy. To get this object, use the Get-CMPackage cmdlet.

Type:	IResultObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-PackageId

Specify the ID of the package with the program to deploy. This ID is a standard package ID, for example XYZ007E3.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-PackageName

Specify the name of the package with the program to deploy.

Type:	String
Position:	Named
Default value:	None
Required:	True
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

-Program

Specify a program object to deploy. To get this object, use the Get-CMProgram cmdlet.

Type:	IResultObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-ProgramName

Specify the name of the program in the package to deploy.

Type:	String
Aliases:	StandardProgramName, DeviceProgramName
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-RecurUnit

Specify a unit for a recurring deployment. Use the RecurValue parameter to specify the value for this unit.

Type:	RecurUnitType
Accepted values:	Minutes, Hours, Days
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RecurValue

Specify how often the deployment recurs.

This parameter depends on the unit type specified in the RecurUnit parameter:

• Hours: This value can be between 1 and 23
• Days: Between 1 and 31
• Minutes: Between 1 and 59

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Rerun

Indicate whether the deployment reruns:

• $True: The deployment runs again for clients as specified in the RerunBehavior parameter. This value is the default.
• $False: The deployment doesn't run again.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RerunBehavior

Specify whether the program reruns on a computer.

• NeverRerunDeployedProgram: Doesn't rerun, even if the deployment failed or files changed.
• AlwaysRerunProgram: Rerun as scheduled, even if the deployment succeeded. You can use this value for recurring deployments. This value is the default.
• RerunIfFailedPreviousAttempt: Rerun as scheduled, if the deployment failed on the previous attempt.
• RerunIfSucceededOnPreviousAttempt: Rerun only if the previous attempt succeeded.

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

Specify the event type that determines when the package 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

-SlowNetworkOption

Specify the behavior when the client uses a distribution point from a neighbor boundary group or the default site boundary group:

• Do not run program
• Download content from distribution point and run locally
• Run program from distribution point

If you don't specify this parameter, it uses DoNotRunProgram by default.

Type:	SlowNetworkOptionType
Accepted values:	DoNotRunProgram, DownloadContentFromDistributionPointAndLocally, RunProgramFromDistributionPoint
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 package to install outside the maintenance window.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StandardProgram

Use this parameter for standard program types. This type is for computers with the Configuration Manager client.

If the program for the package that you're deploying is a device-type program, use the DeviceProgram parameter.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
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

-UseMeteredNetwork

Indicates whether to allow clients on a metered internet connection to download content after the installation deadline, which might incur more cost.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseUtc

Indicates whether clients use Coordinated Universal Time (UTC) to determine the availability of a program. UTC time makes the deployment available at the same time for all computers. If you don't specify this parameter, or set it to $false, the client uses its local time.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseUtcForAvailableSchedule

Indicates whether clients use Coordinated Universal Time (UTC) to determine the availability of a program. UTC time makes the deployment available at the same time for all computers. If you don't specify this parameter, or set it to $false, the client uses its local time.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseUtcForExpireSchedule

Indicates whether clients use Coordinated Universal Time (UTC) to determine when a program is expired. UTC time expires the deployment at the same time for all computers. If you don't specify this parameter, or set it to $false, the client uses its local time.

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 isn'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

System.Object

Related Links

• Get-CMPackageDeployment
• Get-CMPackageDeploymentStatus
• Set-CMPackageDeployment
• Remove-CMPackageDeployment
• Get-CMPackage
• Packages and programs in Configuration Manager