Turn "It Works on Ten Users" into "It Runs the Whole Enterprise in the Maintenance Window" — Evidence-Based PowerShell Performance

Before optimizing, define the target.

Examples:

• Complete within a 30-minute maintenance window
• Process 10,000 records in under 15 minutes
• Reduce API calls by 80 percent
• Prevent scheduled-task overlap
• Keep peak memory below 1 GB
• Process 100 servers concurrently without exceeding approved limits
• Reduce average per-object processing time
• Produce the same output in less time
• Improve performance without increasing failure rates

Without a measurable goal, it is difficult to determine whether an optimization is worthwhile.

$results = @()
$computerNames = Get-Content '.\computers.txt'
foreach ($computerName in $computerNames) {
    $operatingSystem = Get-CimInstance `
        -ClassName Win32_OperatingSystem `
        -ComputerName $computerName
    $computerSystem = Get-CimInstance `
        -ClassName Win32_ComputerSystem `
        -ComputerName $computerName
    $results += [pscustomobject]@{
        ComputerName = $computerName
        OS           = $operatingSystem.Caption
        MemoryGB     = [math]::Round(
            $computerSystem.TotalPhysicalMemory / 1GB,
            2
        )
    }
    Write-Host "Processed $computerName"
}
$results | Export-Csv '.\inventory.csv' -NoTypeInformation

Likely bottlenecks include:

1. Two remote CIM calls per computer.
2. Sequential processing of all computers.
3. Repeated array rebuilding through $results +=.
4. Console output for every computer.
5. No connection timeout or failure isolation.
6. No distinction between DNS, authentication, and remote-management failures.
7. No measurement of per-computer duration.
8. The full collection is retained before export.

The highest-impact opportunity is likely reducing or parallelizing remote calls. Array construction is also inefficient but may be small compared with network latency.

Parallel processing should be bounded to avoid overwhelming:

• The host
• WinRM
• Remote servers
• Network links
• Authentication systems

[CmdletBinding()]
param(
    [Parameter()]
    [ValidateScript({
        Test-Path -LiteralPath $_ -PathType Leaf
    })]
    [string]$ComputerListPath = '.\computers.txt',
    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$OutputPath = '.\inventory.csv'
)
$scriptStart = Get-Date
$computerNames = Get-Content -LiteralPath $ComputerListPath
$results = foreach ($computerName in $computerNames) {
    $computerStart = Get-Date
    try {
        $operatingSystem = Get-CimInstance `
            -ClassName Win32_OperatingSystem `
            -ComputerName $computerName `
            -ErrorAction Stop
        $computerSystem = Get-CimInstance `
            -ClassName Win32_ComputerSystem `
            -ComputerName $computerName `
            -ErrorAction Stop
        [pscustomobject]@{
            ComputerName = $computerName
            OS           = $operatingSystem.Caption
            MemoryGB     = [math]::Round(
                $computerSystem.TotalPhysicalMemory / 1GB,
                2
            )
            Status       = 'Succeeded'
            ErrorMessage = $null
            DurationMs   = [math]::Round(
                ((Get-Date) - $computerStart).TotalMilliseconds
            )
        }
    }
    catch {
        [pscustomobject]@{
            ComputerName = $computerName
            OS           = $null
            MemoryGB     = $null
            Status       = 'Failed'
            ErrorMessage = $_.Exception.Message
            DurationMs   = [math]::Round(
                ((Get-Date) - $computerStart).TotalMilliseconds
            )
        }
    }
}
$results |
    Export-Csv `
        -LiteralPath $OutputPath `
        -NoTypeInformation `
        -Encoding utf8
$duration = (Get-Date) - $scriptStart
Write-Verbose (
    "Processed $($computerNames.Count) computers in " +
    "$([math]::Round($duration.TotalSeconds, 2)) seconds.")

This version removes array rebuilding and reduces console-output overhead, but remote processing remains sequential.

[CmdletBinding()]
param(
    [Parameter()]
    [ValidateScript({
        Test-Path -LiteralPath $_ -PathType Leaf
    })]
    [string]$ComputerListPath = '.\computers.txt',
    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$OutputPath = '.\inventory.csv',
    [Parameter()]
    [ValidateRange(1, 50)]
    [int]$ThrottleLimit = 10
)
$scriptStart = Get-Date
$computerNames = Get-Content -LiteralPath $ComputerListPath
$results = $computerNames |
    ForEach-Object -Parallel {
        $computerName = $_
        $computerStart = Get-Date
        try {
            $cimSession = New-CimSession `
                -ComputerName $computerName `
                -ErrorAction Stop
            try {
                $operatingSystem = Get-CimInstance `
                    -CimSession $cimSession `
                    -ClassName Win32_OperatingSystem `
                    -ErrorAction Stop
                $computerSystem = Get-CimInstance `
                    -CimSession $cimSession `
                    -ClassName Win32_ComputerSystem `
                    -ErrorAction Stop
                [pscustomobject]@{
                    ComputerName = $computerName
                    OS           = $operatingSystem.Caption
                    MemoryGB     = [math]::Round(
                        $computerSystem.TotalPhysicalMemory / 1GB,
                        2
                    )
                    Status       = 'Succeeded'
                    ErrorMessage = $null
                    DurationMs   = [math]::Round(
                        ((Get-Date) - $computerStart).TotalMilliseconds
                    )
                }
            }
            finally {
                if ($cimSession) {
                    Remove-CimSession -CimSession $cimSession
                }
            }
        }
        catch {
            [pscustomobject]@{
                ComputerName = $computerName
                OS           = $null
                MemoryGB     = $null
                Status       = 'Failed'
                ErrorMessage = $_.Exception.Message
                DurationMs   = [math]::Round(
                    ((Get-Date) - $computerStart).TotalMilliseconds
                )
            }
        }
    } -ThrottleLimit $ThrottleLimit
$results |
    Sort-Object -Property ComputerName |
    Export-Csv `
        -LiteralPath $OutputPath `
        -NoTypeInformation `
        -Encoding utf8
$duration = (Get-Date) - $scriptStart
[pscustomobject]@{
    ComputerCount = $computerNames.Count
    SuccessCount  = @(
        $results |
            Where-Object Status -eq 'Succeeded'
    ).Count
    FailureCount  = @(
        $results |
            Where-Object Status -eq 'Failed'
    ).Count
    DurationSec   = [math]::Round($duration.TotalSeconds, 2)
    ThrottleLimit = $ThrottleLimit
}

Parallel output order is not guaranteed. The example sorts results before export to provide deterministic output.

The optimal throttle limit must be measured in the target environment.

function Measure-ScriptPerformance {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [scriptblock]$Operation,
        [Parameter()]
        [ValidateRange(1, 100)]
        [int]$Iterations = 5,
        [Parameter()]
        [ValidateRange(0, 10)]
        [int]$WarmupIterations = 1
    )
    for ($warmup = 1; $warmup -le $WarmupIterations; $warmup++) {
        & $Operation | Out-Null
    }
    $measurements = for ($iteration = 1; $iteration -le $Iterations; $iteration++) {
        [GC]::Collect()
        [GC]::WaitForPendingFinalizers()
        $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
        & $Operation | Out-Null
        $stopwatch.Stop()
        [pscustomobject]@{
            Iteration  = $iteration
            DurationMs = $stopwatch.Elapsed.TotalMilliseconds
        }
    }
    $sortedDurations = @(
        $measurements.DurationMs |
            Sort-Object
    )
    $middleIndex = [math]::Floor($sortedDurations.Count / 2)
    $median = if ($sortedDurations.Count % 2 -eq 0) {
        (
            $sortedDurations[$middleIndex - 1] +
            $sortedDurations[$middleIndex]
        ) / 2
    }
    else {
        $sortedDurations[$middleIndex]
    }
    [pscustomobject]@{
        Iterations = $Iterations
        AverageMs  = (
            $measurements |
                Measure-Object -Property DurationMs -Average
        ).Average
        MedianMs   = $median
        MinimumMs  = (
            $measurements |
                Measure-Object -Property DurationMs -Minimum
        ).Minimum
        MaximumMs  = (
            $measurements |
                Measure-Object -Property DurationMs -Maximum
        ).Maximum
        Results    = $measurements
    }
}

Benchmarks should use representative inputs and comparable environmental conditions.

Nested loops can become expensive.

Weak:

foreach ($user in $users) {
    foreach ($department in $departments) {
        if ($user.DepartmentId -eq $department.Id) {
            # Work
        }
    }
}

Better:

$departmentLookup = @{}
foreach ($department in $departments) {
    $departmentLookup[$department.Id] = $department
}
foreach ($user in $users) {
    $department = $departmentLookup[$user.DepartmentId]
    # Work
}

The lookup uses more memory but can dramatically reduce repeated searches.

Parallelism is most useful when:

• Each item is independent
• Operations are slow
• Work is network-bound or I/O-bound
• The external service allows concurrency
• Output order is not required or can be restored
• Shared state can be avoided

Parallelism may be harmful when:

• Work is already CPU-saturated
• Operations use shared files
• A single remote system is the bottleneck
• APIs enforce strict rate limits
• Operations must occur in order
• Each task requires heavy initialization
• Memory is constrained
• Error recovery depends on sequence

Start conservatively.

For example:

1. Measure sequential execution.
2. Test a throttle of 2.
3. Test 5.
4. Test 10.
5. Observe runtime, errors, memory, and throttling.
6. Stop increasing concurrency when improvement flattens or failure rates rise.

The largest throttle is rarely the best throttle.

Look for:

• Large collections retained unnecessarily
• Duplicate copies of objects
• Full API responses stored when only a few fields are needed
• Large strings constructed repeatedly
• Unclosed streams
• Large job-output buffers
• Parallel tasks returning excessive data
• Repeated serialization
• Variables retained beyond their useful scope

Avoid using manual garbage collection as a general performance solution. It may be useful in controlled benchmarking, but routine forced collection can reduce performance.

Logging can become expensive when a script:

• Opens and closes a file for every object
• Serializes large data structures
• Writes to a network path synchronously
• Produces console output for thousands of objects
• Flushes after every event
• Logs entire request and response bodies

Possible improvements include:

• Configurable verbosity
• Summary-level logging
• Periodic progress updates
• Buffered writes
• Local logging with centralized collection
• Structured but minimal events
• Debug-level per-object details

Audit and security requirements take precedence over minor performance gains.

Updating progress too frequently can slow processing.

Weak:

foreach ($item in $items) {
    Write-Progress -Activity 'Processing' -PercentComplete ...
}

For very large collections, update periodically:

for ($index = 0; $index -lt $items.Count; $index++) {
    $item = $items[$index]
    if ($index % 100 -eq 0) {
        Write-Progress `
            -Activity 'Processing items' `
            -Status "$index of $($items.Count)" `
            -PercentComplete (
                ($index / $items.Count) * 100
            )
    }
    # Process item
}

Performance improvements are valid only if the output remains correct.

Example comparison:

$originalResult = & '.\Original.ps1'
$optimizedResult = & '.\Optimized.ps1'
Compare-Object `
    -ReferenceObject $originalResult `
    -DifferenceObject $optimizedResult `
    -Property Id, Status, Value

Also compare:

• Object types
• Property names
• Property order where relevant
• Record count
• Sorting
• Null handling
• Error behavior
• Side effects

Performance optimization must not weaken security.

Do not improve speed by:

• Caching credentials insecurely
• Reusing tokens beyond approved lifetimes
• Disabling certificate validation
• Removing authorization checks
• Reducing input validation
• Broadening permissions
• Sharing authenticated sessions across unrelated tenants
• Storing sensitive response data unnecessarily
• Bypassing audit logging
• Increasing concurrency beyond security-system capacity

Cached data should be evaluated for:

• Sensitivity
• Freshness
• Access control
• Retention
• Tenant isolation
• Secure disposal

A mature performance review could automatically report:

1. Total execution time
2. Phase timings
3. External-call count
4. Records processed per second
5. Failure rate
6. Retry count
7. Peak memory
8. Concurrency level
9. Output-equivalence result
10. Difference from previous baseline