Public/Search-MailboxExtendedProperty.ps1

function Search-MailboxExtendedProperty {
    <#
    .SYNOPSIS
    Searches mailbox items for explicitly defined MAPI extended properties.

    .DESCRIPTION
    Traverses visible folders and uses EWS to retrieve only the requested item fields and supplied extended-property definitions. Identity can be inferred from Get-MailboxExtendedProperty output. If no definitions are supplied, Store mappings are loaded. Property-name wildcards are expanded against Store mappings. EWS still requires a known PropertyType; Store mappings without a type are reported, not guessed.

    .PARAMETER Identity
    Optional mailbox SMTP address, alias, GUID, or another identifier resolvable by Get-Mailbox. If omitted, it is inferred from input property objects.

    .PARAMETER MailboxExtendedProperty
    Optional named-property definitions from Get-MailboxExtendedProperty, or a property-name wildcard. Typed definitions are required for EWS value searches.

    .PARAMETER Folder
    Optional folder path or display name to search within the traversed hierarchy.

    .PARAMETER IncludeSubfolders
    Include recursively nested folders. Enabled by default; specify $false to search only top-level folders.

    .PARAMETER Archive
    Include the archive mailbox hierarchy.

    .PARAMETER PageSize
    Number of items requested per EWS page.

    .PARAMETER ResultSize
    Maximum total matches returned. Omit for no client-side result limit.

    .PARAMETER SearchDumpster
    Include the recoverable-items hierarchy.

    .PARAMETER IncludeAssociatedItems
    Search associated items in addition to ordinary items.

    .EXAMPLE
    $properties | Search-MailboxExtendedProperty -Identity user@contoso.com

    .EXAMPLE
    Search-MailboxExtendedProperty -Identity user@contoso.com -MailboxExtendedProperty $definition -PageSize 100
    #>

    [CmdletBinding()]
    param(
        [Alias('MailboxIdentity', 'PrimarySmtpAddress')]
        [string]$Identity,

        [Parameter(ValueFromPipeline = $true)]
        [Alias('PropertyDefinition')]
        [psobject[]]$MailboxExtendedProperty,

        [string]$Folder,

        [bool]$IncludeSubfolders = $true,

        [switch]$Archive,

        [ValidateRange(1, 1000)]
        [int]$PageSize = 100,

        [ValidateRange(1, 2147483647)]
        [int]$ResultSize,

        [switch]$SearchDumpster,

        [switch]$IncludeAssociatedItems,

        [ValidateRange(0, 10)]
        [int]$RetryCount,

        [ValidateRange(1, 600)]
        [int]$RequestTimeoutSeconds,

        [string]$EwsUrl,

        [string]$EwsManagedApiPath,

        [System.Management.Automation.PSCredential]$Credential,

        [switch]$UseDefaultCredentials,

        [string]$ExchangeVersion,

        [switch]$TraceEnabled,

        [string]$TraceFilePath,

        [switch]$Impersonate,

        [switch]$TrustAll
    )

    begin {
        $definitions = New-Object 'System.Collections.Generic.List[object]'
        $identityCandidates = New-Object 'System.Collections.Generic.List[string]'
        $searchTimestamp = [DateTime]::UtcNow.ToString('o', [Globalization.CultureInfo]::InvariantCulture)
        $matchCount = 0
        $seenMatches = New-Object 'System.Collections.Generic.HashSet[string]' ([StringComparer]::OrdinalIgnoreCase)
        if (-not $PSBoundParameters.ContainsKey('RetryCount')) {
            $RetryCount = if ($script:ConnectionOptions -and $script:ConnectionOptions.PSObject.Properties['RetryCount']) { [int]$script:ConnectionOptions.RetryCount } else { 3 }
        }
    }

    process {
        foreach ($definition in @($MailboxExtendedProperty)) {
            if ($null -ne $definition) {
                $definitions.Add($definition)
                $primaryAddressProperty = $definition.PSObject.Properties['PrimarySmtpAddress']
                $mailboxIdentityProperty = $definition.PSObject.Properties['MailboxIdentity']
                $candidateIdentity = if ($primaryAddressProperty -and $primaryAddressProperty.Value) {
                    [string]$primaryAddressProperty.Value
                }
                elseif ($mailboxIdentityProperty -and $mailboxIdentityProperty.Value) {
                    [string]$mailboxIdentityProperty.Value
                }
                else {
                    $null
                }
                if ($candidateIdentity -and -not $identityCandidates.Contains($candidateIdentity)) {
                    $identityCandidates.Add($candidateIdentity)
                }
            }
        }
    }

    end {
        $targetIdentity = $Identity
        if (-not $targetIdentity -and $identityCandidates.Count -gt 0) {
            $uniqueIdentityCandidates = @($identityCandidates | Select-Object -Unique)
            if ($uniqueIdentityCandidates.Count -gt 1) {
                throw "Input contains multiple mailbox identities: $($uniqueIdentityCandidates -join ', '). Search one mailbox at a time or specify Identity."
            }
            $targetIdentity = $uniqueIdentityCandidates[0]
        }
        if (-not $targetIdentity) {
            Write-Warning 'Identity is missing. Supply Identity or pipe Get-MailboxExtendedProperty results that include MailboxIdentity or PrimarySmtpAddress.'
            return
        }

        if ($definitions.Count -eq 0) {
            $definitions.AddRange(@(Get-MailboxExtendedProperty -Identity $targetIdentity))
        }
        if ($definitions.Count -eq 0) {
            Write-Warning 'No named-property definitions were provided or returned by Get-MailboxExtendedProperty.'
            return
        }

        $exactDefinitions = New-Object 'System.Collections.Generic.List[object]'
        $wildcardDefinitions = New-Object 'System.Collections.Generic.List[object]'
        foreach ($definition in $definitions) {
            if ($definition -is [string]) {
                if ([System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters($definition)) {
                    $wildcardDefinitions.Add([pscustomobject]@{ Pattern = [string]$definition; PropertySetId = $null; PropertyType = $null; EwsMapiPropertyType = $null })
                }
                else {
                    Write-Warning "Property name '$definition' is not a definition object. Pipe Get-MailboxExtendedProperty output or provide a typed definition."
                }
                continue
            }

            $propertyNameProperty = $definition.PSObject.Properties['PropertyName']
            $propertyName = if ($propertyNameProperty) { [string]$propertyNameProperty.Value } else { $null }
            if ($propertyName -and [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters($propertyName)) {
                $setIdProperty = $definition.PSObject.Properties['PropertySetId']
                if (-not $setIdProperty) { $setIdProperty = $definition.PSObject.Properties['PropertyNamespace'] }
                $typeProperty = $definition.PSObject.Properties['PropertyType']
                $ewsTypeProperty = $definition.PSObject.Properties['EwsMapiPropertyType']
                $wildcardDefinitions.Add([pscustomobject]@{
                        Pattern             = $propertyName
                        PropertySetId       = if ($setIdProperty) { [string]$setIdProperty.Value } else { $null }
                        PropertyType        = if ($typeProperty) { [string]$typeProperty.Value } else { $null }
                        EwsMapiPropertyType = if ($ewsTypeProperty) { [string]$ewsTypeProperty.Value } else { $null }
                    })
            }
            else {
                $exactDefinitions.Add($definition)
            }
        }

        if ($wildcardDefinitions.Count -gt 0) {
            $storeDefinitions = @(Get-MailboxExtendedProperty -Identity $targetIdentity)
            foreach ($wildcardDefinition in $wildcardDefinitions) {
                $wildcardCandidates = @($storeDefinitions | Where-Object {
                        $_.PropertyName -and $_.PropertyName -like $wildcardDefinition.Pattern -and
                        (-not $wildcardDefinition.PropertySetId -or $_.PropertySetId -eq $wildcardDefinition.PropertySetId)
                    })
                foreach ($candidateDefinition in $wildcardCandidates) {
                    $expandedDefinition = [ordered]@{}
                    foreach ($property in $candidateDefinition.PSObject.Properties) {
                        $expandedDefinition[$property.Name] = $property.Value
                    }
                    if ($wildcardDefinition.PropertyType) {
                        $expandedDefinition['PropertyType'] = $wildcardDefinition.PropertyType
                    }
                    if ($wildcardDefinition.EwsMapiPropertyType) {
                        $expandedDefinition['EwsMapiPropertyType'] = $wildcardDefinition.EwsMapiPropertyType
                    }
                    $expandedObject = [pscustomobject]$expandedDefinition
                    if ($wildcardDefinition.PropertyType) {
                        $exactDefinitions.Add((ConvertTo-NormalizedNamedProperty -Definition $expandedObject -DiscoverySource 'Store'))
                    }
                    else {
                        if ($candidateDefinition.PSObject.TypeNames -contains 'ExchangeNamedProperties.NamedPropertyDefinition') {
                            $expandedObject.PSObject.TypeNames.Insert(0, 'ExchangeNamedProperties.NamedPropertyDefinition')
                        }
                        $exactDefinitions.Add($expandedObject)
                    }
                }
                if ($wildcardCandidates.Count -eq 0) {
                    Write-Warning "Wildcard '$($wildcardDefinition.Pattern)' matched no Store property names for the target mailbox."
                }
            }
        }

        $typedDefinitions = New-Object 'System.Collections.Generic.List[object]'
        $untypedDefinitions = New-Object 'System.Collections.Generic.List[object]'
        foreach ($definition in $exactDefinitions) {
            $normalized = if ($definition.PSObject.TypeNames -contains 'ExchangeNamedProperties.NamedPropertyDefinition') {
                $definition
            }
            else {
                ConvertTo-NormalizedNamedProperty -Definition $definition
            }
            $propertyTypeProperty = $normalized.PSObject.Properties['PropertyType']
            if (-not $propertyTypeProperty -or [string]::IsNullOrWhiteSpace([string]$propertyTypeProperty.Value)) {
                $untypedDefinitions.Add($normalized)
                continue
            }
            $typedDefinitions.Add([pscustomobject]@{ Normalized = $normalized; EwsDefinition = $null })
        }

        if ($untypedDefinitions.Count -gt 0) {
            Write-Warning "Skipped $($untypedDefinitions.Count) named-property definition(s) without PropertyType. Store inventory does not identify value types; supply Get-MailboxExtendedProperty results enriched with a verified PropertyType before EWS searching."
        }
        if ($typedDefinitions.Count -eq 0) {
            foreach ($untypedDefinition in $untypedDefinitions) {
                [pscustomobject]@{
                    PSTypeName         = 'ExchangeNamedProperties.SearchError'
                    MailboxIdentity    = $targetIdentity
                    PrimarySmtpAddress = $targetIdentity
                    PropertySetId      = $untypedDefinition.PropertySetId
                    PropertyId         = if ($untypedDefinition.PSObject.Properties['PropertyId']) { $untypedDefinition.PropertyId } elseif ($untypedDefinition.PSObject.Properties['PropDispId']) { $untypedDefinition.PropDispId } else { $null }
                    PropertyName       = $untypedDefinition.PropertyName
                    PropertyType       = if ($untypedDefinition.PSObject.Properties['PropertyType']) { $untypedDefinition.PropertyType } else { $null }
                    FolderPath         = $null
                    ErrorCode          = 'PropertyTypeRequired'
                    ErrorMessage       = 'This Store definition has no PropertyType. EWS cannot retrieve its item values without a verified type.'
                    SearchTimestamp    = $searchTimestamp
                }
            }
            return
        }

        $connectionArguments = @{ Identity = $targetIdentity }
        foreach ($connectionParameter in @('EwsUrl', 'EwsManagedApiPath', 'Credential', 'ExchangeVersion', 'RequestTimeoutSeconds', 'TraceFilePath')) {
            if ($PSBoundParameters.ContainsKey($connectionParameter)) {
                $connectionArguments[$connectionParameter] = $PSBoundParameters[$connectionParameter]
            }
        }
        foreach ($switchParameter in @('UseDefaultCredentials', 'TraceEnabled', 'Impersonate', 'TrustAll')) {
            if ($PSBoundParameters.ContainsKey($switchParameter)) {
                $connectionArguments[$switchParameter] = $PSBoundParameters[$switchParameter]
            }
        }

        $mailbox = Resolve-MailboxIdentity -Identity $targetIdentity
        foreach ($untypedDefinition in $untypedDefinitions) {
            [pscustomobject]@{
                PSTypeName         = 'ExchangeNamedProperties.SearchError'
                MailboxIdentity    = $mailbox.Identity
                PrimarySmtpAddress = $mailbox.PrimarySmtpAddress
                PropertySetId      = $untypedDefinition.PropertySetId
                PropertyId         = if ($untypedDefinition.PSObject.Properties['PropertyId']) { $untypedDefinition.PropertyId } elseif ($untypedDefinition.PSObject.Properties['PropDispId']) { $untypedDefinition.PropDispId } else { $null }
                PropertyName       = $untypedDefinition.PropertyName
                PropertyType       = if ($untypedDefinition.PSObject.Properties['PropertyType']) { $untypedDefinition.PropertyType } else { $null }
                FolderPath         = $null
                ErrorCode          = 'PropertyTypeRequired'
                ErrorMessage       = 'This Store definition has no PropertyType. EWS cannot retrieve its item values without a verified type.'
                SearchTimestamp    = $searchTimestamp
            }
        }
        $service = Get-EwsService @connectionArguments

        foreach ($definitionEntry in $typedDefinitions) {
            $definitionEntry.EwsDefinition = ConvertTo-EwsExtendedPropertyDefinition -Definition $definitionEntry.Normalized
        }

        try {
            $folders = @(Get-EwsFolderHierarchy -Service $service -PrimarySmtpAddress $mailbox.PrimarySmtpAddress -PageSize ([Math]::Min($PageSize, 100)) -IncludeSubfolders:$IncludeSubfolders -IncludeArchive:$Archive -SearchDumpster:$SearchDumpster -RetryCount $RetryCount)
        }
        catch {
            [pscustomobject]@{
                PSTypeName         = 'ExchangeNamedProperties.SearchError'
                MailboxIdentity    = $mailbox.Identity
                PrimarySmtpAddress = $mailbox.PrimarySmtpAddress
                FolderPath         = $null
                ErrorCode          = $_.Exception.GetType().Name
                ErrorMessage       = $_.Exception.Message
                SearchTimestamp    = $searchTimestamp
            }
            return
        }

        $totalFolders = $folders.Count
        $folderIndex = 0
        foreach ($folderEntry in $folders) {
            $folderIndex++
            if ($folderEntry.PSTypeNames -contains 'ExchangeNamedProperties.SearchError') {
                Add-Member -InputObject $folderEntry -MemberType NoteProperty -Name MailboxIdentity -Value $mailbox.Identity -Force
                Add-Member -InputObject $folderEntry -MemberType NoteProperty -Name PrimarySmtpAddress -Value $mailbox.PrimarySmtpAddress -Force
                Add-Member -InputObject $folderEntry -MemberType NoteProperty -Name SearchTimestamp -Value $searchTimestamp -Force
                $folderEntry
                continue
            }
            if ($Folder -and $folderEntry.FolderPath -notlike $Folder -and $folderEntry.Folder.DisplayName -ne $Folder) {
                continue
            }

            Write-Progress -Activity 'Searching mailbox extended properties' -Status $folderEntry.FolderPath -PercentComplete $(if ($totalFolders -gt 0) { [int](100 * $folderIndex / $totalFolders) } else { 100 })
            $propertySet = New-Object -TypeName Microsoft.Exchange.WebServices.Data.PropertySet -ArgumentList ([Microsoft.Exchange.WebServices.Data.BasePropertySet]::IdOnly)
            foreach ($itemProperty in @(
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::Subject,
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::ItemClass,
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeCreated,
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::LastModifiedTime,
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::ParentFolderId,
                    [Microsoft.Exchange.WebServices.Data.EmailMessageSchema]::DateTimeReceived,
                    [Microsoft.Exchange.WebServices.Data.EmailMessageSchema]::InternetMessageId
                )) {
                $propertySet.Add($itemProperty)
            }
            foreach ($definitionEntry in $typedDefinitions) {
                $propertySet.Add($definitionEntry.EwsDefinition)
            }

            $traversals = @([Microsoft.Exchange.WebServices.Data.ItemTraversal]::Shallow)
            if ($IncludeAssociatedItems) {
                $traversals += [Microsoft.Exchange.WebServices.Data.ItemTraversal]::Associated
            }

            foreach ($traversal in $traversals) {
                $offset = 0
                $mailSearchFilter = New-Object -TypeName 'Microsoft.Exchange.WebServices.Data.SearchFilter+ContainsSubstring' -ArgumentList @(
                    [Microsoft.Exchange.WebServices.Data.ItemSchema]::ItemClass,
                    'IPM.Note',
                    [Microsoft.Exchange.WebServices.Data.ContainmentMode]::Prefixed,
                    [Microsoft.Exchange.WebServices.Data.ComparisonMode]::IgnoreCase
                )
                do {
                    if ($ResultSize -and $matchCount -ge $ResultSize) {
                        break
                    }

                    $itemView = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ItemView -ArgumentList @($PageSize, $offset)
                    $itemView.PropertySet = $propertySet
                    $itemView.Traversal = $traversal
                    $itemView.OrderBy.Add([Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeCreated, [Microsoft.Exchange.WebServices.Data.SortDirection]::Ascending)

                    try {
                        $itemPage = Invoke-EwsRequestWithRetry -RetryCount $RetryCount -ScriptBlock {
                            Write-Output -NoEnumerate ($service.FindItems($folderEntry.FolderId, $mailSearchFilter, $itemView))
                        }
                    }
                    catch {
                        [pscustomobject]@{
                            PSTypeName         = 'ExchangeNamedProperties.SearchError'
                            MailboxIdentity    = $mailbox.Identity
                            PrimarySmtpAddress = $mailbox.PrimarySmtpAddress
                            FolderPath         = $folderEntry.FolderPath
                            ErrorCode          = $_.Exception.GetType().Name
                            ErrorMessage       = $_.Exception.Message
                            SearchTimestamp    = $searchTimestamp
                        }
                        break
                    }

                    foreach ($item in $itemPage.Items) {
                        if ($ResultSize -and $matchCount -ge $ResultSize) {
                            break
                        }
                        foreach ($definitionEntry in $typedDefinitions) {
                            if ($ResultSize -and $matchCount -ge $ResultSize) {
                                break
                            }
                            $propertyValue = $null
                            if (-not $item.TryGetProperty($definitionEntry.EwsDefinition, [ref]$propertyValue)) {
                                continue
                            }

                            $matchKey = '{0}|{1}|{2}' -f $item.Id.UniqueId, $definitionEntry.Normalized.Identity, $traversal
                            if (-not $seenMatches.Add($matchKey)) {
                                continue
                            }

                            $entryId = $null
                            $propertyTagProperty = $definitionEntry.Normalized.PSObject.Properties['PropertyTag']
                            if ($propertyTagProperty -and $null -ne $propertyTagProperty.Value -and [uint32]$propertyTagProperty.Value -eq [uint32]0x0FFF0102) {
                                $entryId = ConvertFrom-EwsExtendedProperty -Value $propertyValue
                            }

                            [pscustomobject]@{
                                PSTypeName         = 'ExchangeNamedProperties.SearchResult'
                                MailboxIdentity    = $mailbox.Identity
                                PrimarySmtpAddress = $mailbox.PrimarySmtpAddress
                                ItemId             = $item.Id.UniqueId
                                ChangeKey          = $item.Id.ChangeKey
                                EntryId            = $entryId
                                ParentFolderId     = if ($item.ParentFolderId) { $item.ParentFolderId.UniqueId } else { $null }
                                FolderPath         = $folderEntry.FolderPath
                                ItemClass          = $item.ItemClass
                                Subject            = $item.Subject
                                InternetMessageId  = $item.InternetMessageId
                                DateTimeReceived   = if ($item.DateTimeReceived) { $item.DateTimeReceived.ToUniversalTime().ToString('o', [Globalization.CultureInfo]::InvariantCulture) } else { $null }
                                DateTimeCreated    = if ($item.DateTimeCreated) { $item.DateTimeCreated.ToUniversalTime().ToString('o', [Globalization.CultureInfo]::InvariantCulture) } else { $null }
                                LastModifiedTime   = if ($item.LastModifiedTime) { $item.LastModifiedTime.ToUniversalTime().ToString('o', [Globalization.CultureInfo]::InvariantCulture) } else { $null }
                                PropertySetId      = $definitionEntry.Normalized.PropertySetId
                                PropertyId         = if ($definitionEntry.Normalized.PSObject.Properties['PropertyId']) { $definitionEntry.Normalized.PropertyId } elseif ($definitionEntry.Normalized.PSObject.Properties['PropDispId']) { $definitionEntry.Normalized.PropDispId } else { $null }
                                PropertyName       = $definitionEntry.Normalized.PropertyName
                                PropertyType       = $definitionEntry.Normalized.PropertyType
                                PropertyValue      = ConvertFrom-EwsExtendedProperty -Value $propertyValue
                                HasProperty        = $true
                                SearchTimestamp    = $searchTimestamp
                            }
                            $matchCount++
                            if ($ResultSize -and $matchCount -ge $ResultSize) {
                                break
                            }
                        }
                    }

                    $offset += $itemPage.Items.Count
                    $moreItems = $itemPage.MoreAvailable
                } while ($moreItems -and $itemPage.Items.Count -gt 0 -and (-not $ResultSize -or $matchCount -lt $ResultSize))
            }
        }
        Write-Progress -Activity 'Searching mailbox extended properties' -Completed
    }
}