04 / SHIP DEPENDABLE FLEET TOOLS · LESSON 14

Plan and apply simulated remote maintenance

Combine reviewed process identity, per-host failures, and WhatIf in a fleet maintenance command.

20 min · learn at your pace

Bring the contracts together

A maintenance request contains ComputerName, Id, and ExpectedStartTime. Collect the current process through Invoke-LabCommand, verify the reviewed instance, then decide whether to apply the action. Keep every request in the result, even when its host is offline.

The lab injects a Computer context before your ArgumentList values. Use param($Computer,$ProcessId) in each script block. One block retrieves the process; the second performs the simulated stop after ShouldProcess permits it. There is no actual remote connection or isolated remote session.

Preview is a result worth recording

Under WhatIf, an eligible request returns Planned and makes no change. An approved eligible request returns Stopped. An inaccessible computer, missing or reused process, protected entry, or denied action returns Failed with a diagnostic.

Keep try/catch inside the loop so a failure on offline01 does not prevent a later request for db01. Return one result for each input row in its original order. An empty request should produce no records.

Review is still a snapshot

This exercise checks StartTime immediately before the action decision, but real operating systems can change between collection and mutation. Production code needs a strategy for those races, appropriate privileges, and trustworthy audit storage. Here all changes affect the virtual fleet only. Check recreates the original state; Run and saved workspaces retain successful simulated changes for inspection.

Go deeper

Read the official reference.

Try an example.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
Get-Content '/home/user/maintenance.json' -Raw | ConvertFrom-Json -DateKind String
YOUR TURN

Put it into practice.

Define Invoke-FleetMaintenance(Request object[]) with SupportsShouldProcess. For each request, verify the running process and ExpectedStartTime, Protected=false, and CanStop=true. Use simulated remoting for collection and stopping. Emit ComputerName, Id, Status, Detail for every request: Planned when WhatIf suppresses an eligible change, Stopped after a change, Failed with a diagnostic on an error. Continue after failures.

See an explained solution
One way to solve it.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
function Invoke-FleetMaintenance {
    [CmdletBinding(SupportsShouldProcess)]
    param([object[]]$Request)
    foreach($item in $Request) {
        try {
            $process=@(Invoke-LabCommand $item.ComputerName -ArgumentList $item.Id -ScriptBlock {
                param($Computer,$ProcessId)
                Get-LabProcess $Computer.ComputerName | Where-Object Id -EQ $ProcessId
            })
            if($process.Count -ne 1 -or $process[0].StartTime -ne $item.ExpectedStartTime) { throw 'Process identity changed or missing' }
            if($process[0].Protected -or -not $process[0].CanStop) { throw 'Process is not eligible' }
            $status='Planned'; $detail='Reviewed; no change applied'
            if($PSCmdlet.ShouldProcess("$($item.ComputerName)/$($item.Id)",'Stop simulated process')) {
                Invoke-LabCommand $item.ComputerName -ArgumentList $item.Id -ScriptBlock {
                    param($Computer,$ProcessId)
                    Stop-LabProcess $Computer.ComputerName -Id $ProcessId -Confirm:$false
                }
                $status='Stopped'; $detail='Simulated process stopped'
            }
        } catch { $status='Failed'; $detail=$_.Exception.Message }
        [pscustomobject]@{ComputerName=$item.ComputerName;Id=$item.Id;Status=$status;Detail=$detail}
    }
}

Every request has an outcome and every mutation is gated. A failed computer stays visible without preventing later requests from being processed.