Commands › Exchange Online

New-AppRetentionComplianceRule

Exchange Online ExchangeOnlineManagement New-*

For more information, see Security & Compliance PowerShell. Use the New-AppRetentionComplianceRule to create app retention compliance rules.

Quick start script

# New-AppRetentionComplianceRule — 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-AppRetentionComplianceRule
$before | Format-List

# 3. Make the change (dry run first)
New-AppRetentionComplianceRule -Name <String> -Policy <PolicyIdParameter> -WhatIf
New-AppRetentionComplianceRule -Name <String> -Policy <PolicyIdParameter>

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

Syntax — 2 parameter sets

Default

New-AppRetentionComplianceRule [-Name] <String> -Policy <PolicyIdParameter>
 [-Comment <String>]
 [-Confirm]
 [-ContentMatchQuery <String>]
 [-ExcludedItemClasses <MultiValuedProperty>]
 [-ExpirationDateOption <String>]
 [-RetentionComplianceAction <String>]
 [-RetentionDuration <Unlimited>]
 [-RetentionDurationDisplayHint <HoldDurationHint>]
 [-WhatIf]
 [<CommonParameters>]

ComplianceTag

New-AppRetentionComplianceRule -Policy <PolicyIdParameter>
 [-Confirm]
 [-ContentContainsSensitiveInformation <PswsHashtable[]>]
 [-ContentMatchQuery <String>]
 [-ExpirationDateOption <String>]
 [-MachineLearningModelIDs <MultiValuedProperty>]
 [-RetentionComplianceAction <String>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (13)

Parameter	Type	Required	What it controls
-Name	String	yes	The Name parameter specifies a unique name for the app retention compliance rule. The maximum length is 64 characters. If the value contains spaces, enclose the value in quotation marks (").
-Policy	PolicyIdParameter	yes	The Policy parameter specifies the app retention compliance policy that contains the app retention compliance policy rule. You can use any value that uniquely identifies the policy. For example:
-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.
-ContentContainsSensitiveInformation	PswsHashtable[]		The ContentContainsSensitiveInformation parameter specifies a condition for the rule that's based on a sensitive information type match in content. The rule is applied to content that contains the specified sensitive...
-ContentMatchQuery	String		The ContentMatchQuery parameter specifies a content search filter.
-ExcludedItemClasses	MultiValuedProperty		The ExcludedItemClasses parameter specifies the types of messages to exclude from the rule. You can use this parameter only to exclude items from a hold policy, which excludes the specified item class from being...
-ExpirationDateOption	String		The ExpirationDateOption parameter specifies whether the expiration date is calculated from the content creation date or last modification date. Valid values are:
-MachineLearningModelIDs	MultiValuedProperty		{{ Fill MachineLearningModelIDs Description }}
-RetentionComplianceAction	String		The RetentionComplianceAction parameter specifies the retention action for the rule. Valid values are:
-RetentionDuration	Unlimited		The RetentionDuration parameter specifies the hold duration for the retention rule. Valid values are:
-RetentionDurationDisplayHint	HoldDurationHint		The RetentionDurationDisplayHint parameter specifies the units that are used to display the retention duration in the Microsoft Purview compliance portal. Valid values are Days, Months or Years.
-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.