02 / PROCESS CONTROL AND REMOTING · LESSON 06

Put process changes behind ShouldProcess

Write a reusable process-control function that verifies identity and honours WhatIf.

16 min · learn at your pace

The attribute is only the interface

[CmdletBinding(SupportsShouldProcess)] adds WhatIf and Confirm parameters to your advanced function. It does not automatically protect a file write or a nested command. The mutation must sit inside if ($PSCmdlet.ShouldProcess(...)).

Give ShouldProcess a meaningful target and action. Here the target is a computer/PID pair, and the action is stopping the reviewed simulated process. Under WhatIf, ShouldProcess returns false. No mutation should occur.

Re-check the reviewed instance

Accept ExpectedStartTime from an earlier review. Find a single running process on the requested computer and compare its StartTime with that value. Reject a missing entry or changed identity before acting. Also reject protected entries and entries whose CanStop flag is false.

Checking first narrows a real-world race; it does not make a subsequent OS operation atomic. The fixture state changes synchronously and cannot reproduce all races. Learn the rule here, then design the production collector and action boundary for the actual system.

One owner for confirmation

The wrapper owns the decision. After its ShouldProcess call permits the change, call Stop-LabProcess with confirmation suppressed to avoid a second prompt. The automated checks exercise WhatIf, a valid change, a changed start time, a denied process, and a protected process. Your function should define behaviour without executing a demonstration at load time.

Go deeper

Read the official reference.

Try an example.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
Get-LabProcess app01 | Where-Object Id -EQ 410 | Select-Object Id,StartTime,Protected,CanStop
YOUR TURN

Put it into practice.

Define Stop-ReviewedProcess(ComputerName, Id, ExpectedStartTime) with SupportsShouldProcess. Throw when the running process is missing, the start time differs, it is protected, or CanStop is false. Only stop the chosen simulated process when ShouldProcess permits it. WhatIf must preserve state.

See an explained solution
One way to solve it.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
function Stop-ReviewedProcess {
    [CmdletBinding(SupportsShouldProcess)]
    param([string]$ComputerName,[int]$Id,[string]$ExpectedStartTime)
    $process=@(Get-LabProcess $ComputerName | Where-Object Id -EQ $Id)
    if($process.Count -ne 1) { throw 'Process no longer running' }
    if($process[0].StartTime -ne $ExpectedStartTime) { throw 'Process identity changed' }
    if($process[0].Protected -or -not $process[0].CanStop) { throw 'Process is not eligible' }
    if($PSCmdlet.ShouldProcess("$ComputerName/$Id",'Stop reviewed simulated process')) {
        Stop-LabProcess $ComputerName -Id $Id -Confirm:$false
    }
}

Validation protects the reviewed identity. ShouldProcess gates the actual mutation, so WhatIf is a behavioural guarantee rather than just an accepted parameter.