Private/ActiveDirectory/Invoke-ADOperationWithRetry.ps1

function Invoke-ADOperationWithRetry {
    <#
    .SYNOPSIS
        Executes Active Directory operations with retry logic and security logging
 
    .DESCRIPTION
        Orchestrates AD operations by combining retry mechanisms with proper security
        audit logging. Provides enterprise-grade reliability for AD interactions.
 
    .PARAMETER ScriptBlock
        The AD operation to execute
 
    .PARAMETER MaxRetries
        Total attempts, the first included, for a failure that looks transient (1-11, default 3).
        A caller holding a retry count passes that count plus one.
 
    .PARAMETER OperationName
        Descriptive name for the operation
 
    .PARAMETER ObjectContext
        Additional context about the AD object being accessed
 
    .EXAMPLE
        PS> Invoke-ADOperationWithRetry -ScriptBlock { Get-ADUser 'testuser' } -OperationName 'Get User'
 
        DESCRIPTION: Executes AD user lookup with retry and audit logging
        OUTPUT: AD user object with full audit trail
        USE CASE: Production AD operations requiring reliability and auditing
 
    .NOTES
        Author: Jeffrey Stuhr
        Blog: https://www.techbyjeff.net
        LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/
 
        TROUBLESHOOTING:
        - For operation failures: .\Troubleshooting\Performance\Performance-Tuning.md
    #>


    [CmdletBinding()]
    [OutputType('ADOperationResult')]
    param(
        [Parameter(Mandatory)]
        [scriptblock]$ScriptBlock,

        [Parameter()]
        # Attempts, the first included: a caller's 10 retries is 11 attempts
        [ValidateRange(1, 11)]
        [int]$MaxRetries = 3,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]$OperationName = 'AD Operation',

        [Parameter()]
        [string]$ObjectContext = 'Unknown',

        [Parameter()]
        [string]$CorrelationId = [System.Guid]::NewGuid().ToString()
    )

    begin {
        Write-Verbose "Starting AD operation with retry: $OperationName"

        # Build security context
        $securityContext = @{
            ObjectContext = $ObjectContext
            MaxRetries = $MaxRetries
            ADAccessType = 'Sensitive'
            OperationType = 'SingleOperation'
        }
    }

    process {
        # Log operation attempt
        Write-ADOperationSecurityLog -OperationName $OperationName -Outcome 'Attempt' -SecurityContext $securityContext -CorrelationId $CorrelationId

        try {
            # Execute with retry logic
            $result = Invoke-OperationWithRetry -ScriptBlock $ScriptBlock -MaxRetries $MaxRetries -OperationName $OperationName -CorrelationId $CorrelationId

            # Log successful operation
            $successContext = $securityContext.Clone()
            $successContext['ResultType'] = if ($result) { $result.GetType().Name } else { 'NoResult' }

            Write-ADOperationSecurityLog -OperationName $OperationName -Outcome 'Success' -SecurityContext $successContext -CorrelationId $CorrelationId

            return $result
        }
        catch {
            # Log failed operation
            $failureContext = $securityContext.Clone()
            $failureContext['ErrorMessage'] = $_.Exception.Message
            $failureContext['FailureCategory'] = 'OperationFailed'

            Write-ADOperationSecurityLog -OperationName $OperationName -Outcome 'Failure' -SecurityContext $failureContext -CorrelationId $CorrelationId

            throw
        }
    }
}