Commands › Exchange Online

Set-HoldCompliancePolicy

Exchange Online ExchangeOnlineManagement Set-*

For more information, see Security & Compliance PowerShell. Use the Set-HoldCompliancePolicy cmdlet to modify existing preservation policies in the Microsoft Purview compliance portal. **Note**: The Set-HoldCompliancePolicy cmdlet is replaced by the Set-RetentionCompliancePolicy cmdlet. If you have scripts that use Set-HoldCompliancePolicy, update them to use Set-RetentionCompliancePolicy.

Quick start script

# Set-HoldCompliancePolicy — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-HoldCompliancePolicy
$before | Format-List

# 3. Make the change (dry run first)
Set-HoldCompliancePolicy -Identity <PolicyIdParameter> -RetryDistribution <SwitchParameter> -WhatIf
Set-HoldCompliancePolicy -Identity <PolicyIdParameter> -RetryDistribution <SwitchParameter>

# 4. Verify and diff
$after = Get-HoldCompliancePolicy
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 2 parameter sets

RetryDistribution

Set-HoldCompliancePolicy [-Identity] <PolicyIdParameter>
 [-RetryDistribution]
 [-Confirm]
 [-WhatIf]
 [<CommonParameters>]

Identity

Set-HoldCompliancePolicy [-Identity] <PolicyIdParameter>
 [-AddExchangeLocation <MultiValuedProperty>]
 [-AddPublicFolderLocation <MultiValuedProperty>]
 [-AddSharePointLocation <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-Enabled <Boolean>]
 [-Force]
 [-RemoveExchangeLocation <MultiValuedProperty>]
 [-RemovePublicFolderLocation <MultiValuedProperty>]
 [-RemoveSharePointLocation <MultiValuedProperty>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (13)

Parameter	Type	Required	What it controls
-Identity	PolicyIdParameter	yes	The Identity parameter specifies the preservation policy that you want to modify. You can use any value that uniquely identifies the policy. For example:
-RetryDistribution	SwitchParameter	yes	The RetryDistribution switch specifies whether to redistribute the policy to all Exchange Online and SharePoint locations. You don't need to specify a value with this switch.
-AddExchangeLocation	MultiValuedProperty		The AddExchangeLocation parameter specifies the mailboxes to add to the list of included mailboxes. Valid values are:
-AddPublicFolderLocation	MultiValuedProperty		The AddPublicFolderLocation parameter specifies that you want to add all public folders to the preservation policy. You use the value All for this parameter.
-AddSharePointLocation	MultiValuedProperty		The AddSharePointLocation parameter specifies the SharePoint sites to add to the list of included sites when you aren't using the value All for the SharePointLocation parameter. You identify the site by its URL value.
-Comment	String		The Comment parameter specifies an optional comment. If you specify a value that contains spaces, enclose the value in quotation marks ("), for example: "This is an admin note".
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-Enabled	Boolean		The Enabled parameter specifies whether the policy is enabled. Valid values are:
-Force	SwitchParameter		The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
-RemoveExchangeLocation	MultiValuedProperty		The RemoveExchangeLocation parameter specifies the existing mailboxes to remove from the policy. Valid values are:
-RemovePublicFolderLocation	MultiValuedProperty		The RemovePublicFolderLocation parameter specifies that you want to remove all public folders from the preservation policy. You use the value All for this parameter.
-RemoveSharePointLocation	MultiValuedProperty		The RemoveSharePointLocation parameter specifies the SharePoint sites to remove from the list of included sites when you aren't using the value All for the SharePointLocation parameter. You identify the site by its URL value.
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.