Skip to main content

Key Rollover and Labeling Guide

Key Rollover and Labeling Guide

Strategies for applying DKE labels when automatic labeling is not available

Applies to:
File MigrationPowerShell LabelingAIP ScannerSharePoint

The DKE Labeling Challenge​

Warning
Automatic labeling in SharePoint does not work with DKE-protected labels.

This means files must be labeled manually or via alternative methods before migration, to ensure Microsoft 365 cannot read the contents.

Potential Solutions​

1

Manual Labeling

Via the Purview Label Client

2

AIP Scanner

Automated on-premises labeling

3

PowerShell

Script-based file labeling

1. Manual Labeling​

Involves selecting individual files or folders in File Explorer and applying the appropriate label.

Caution

Downside: Limited logging in case of errors, and files must be checked one-by-one — very time-consuming and unsuitable for large migrations.

2. AIP Scanner​

A tool installed on-premises to apply labels automatically to files on file shares or SharePoint On-Premises, based on defined policies.

Advantages

Great for larger environments or where labeling needs to be extended to on-premises setups.

Disadvantage

For small local drives, the implementation overhead may be too high.

3. PowerShell-Based Labeling​

Due to the limitations of the above methods, PowerShell can be used to label files programmatically.

Prerequisites

  • A client with PowerShell and the Purview Label Client installed
  • An app registration in Entra ID (formerly Azure Active Directory)
Caution
Limitations:
  • MSG files (Outlook messages) cannot be labeled via PowerShell
  • Password-protected or certificate-signed PDFs can't be labeled either (limitation of the label system itself)

The PowerShell Challenge​

Using standard PowerShell commands as per Microsoft documentation may lead to PowerShell freezing or running indefinitely.

Warning

Testing has proven that the above is not sufficient and additional work is required to reliably label files using a retry mechanism and job-based processing.

Reliable PowerShell Labeling Script​

The following script provides a robust solution with retry logic and job-based execution:

Get-ChildItem -Path \\Finance\Projects\ -Recurse -File | ForEach-Object {
    try {
        $maxRetries = 3
        $retryCount = 0
        $setSuccess = $false

        while (-not $setSuccess -and $retryCount -lt $maxRetries) {
            $retryCount++

            $jobsetlabel = Start-Job -ScriptBlock {
                param ($fileName, $DKELabelId)
                Set-FileLabel -FileName $fileName -LabelId $DKELabelId
                [GC]::Collect()
                [GC]::WaitForPendingFinalizers()
                return $true
            } -ArgumentList $_.FullName, "d9f23ae3-4321-4321-4321-f515f824c57b"

            $finishedsetlabel = $jobsetlabel | Wait-Job -Timeout 10 | Receive-Job

            if ($finishedsetlabel) {
                $setSuccess = $true
                Write-Host "Label set successfully for $($_.FullName) on attempt $retryCount." -ForegroundColor Green
            }
        }
    }
    catch {
        Write-Host "Failed to set label after $maxRetries attempts for $($_.FullName)." -ForegroundColor Red
    }
}

Script Features​

FeatureDescription
Retry mechanismTries up to 3 times per file
Job-based executionEach file is labeled in a separate job to avoid resource issues
Memory cleanupUses [GC]::Collect() and WaitForPendingFinalizers() after each job
Timeout controlPrevents hanging by using Wait-Job -Timeout 10
Tip

With this approach, you can successfully label all relevant files without PowerShell freezing or running indefinitely.

Pre-Migration Audit Script​

To ensure all files were correctly labeled before migration, write a script that reads the label of each file and logs the results to a CSV. This allows for manual review and adjustments where needed.

See Also