Stop-Function -Continue without an enclosing loop escapes the command and corrupts the caller

[andreasjordan]

Summary

Stop-Function -Continue executes PowerShell's continue. When no loop encloses the call site inside the command's own body, that flow control does not stop at the function boundary: it unwinds into the caller and consumes an iteration of whatever loop the caller happens to be running in. A user restoring or querying in a foreach over instances silently skips elements when a command hits its error path; under Pester it corrupts the test runner itself, which surfaced for years as the undiagnosable Cannot bind argument to parameter 'ErrorRecord' because it is null crash documented above the skipped StopAt tests.

Two demonstrations, both lab-measured:

• Restore-DbaDatabase - Stop escaping the caller and resurrect the StopAt tests #10636 fixed two end-block sites in Restore-DbaDatabase; before the fix, a plain script calling the command lost its own control flow mid-try (a marker line after the call was never reached while the finally still ran).
• Get-DbaDatabase - Stop eating the caller loop on invalid parameter combination #10637 fixed the begin-block validation in Get-DbaDatabase: a foreach over three elements completed zero iterations against the unfixed command, because the escaped continue consumed one per call.

The escape bites only the non-EnableException path for -Continue (with EnableException, Stop-Function throws first). -SilentlyContinue executes continue in both modes, so it can escape even under EnableException.

Inventory

An AST sweep over all 1,591 -Continue/-SilentlyContinue sites in public/ and private/functions/ (walking each call's parents for a loop or switch, which also catches continue) found 91 sites with no enclosing loop: 31 in begin blocks, 23 in process, 25 in end, and 12 inside nested helper functions where the continue binds dynamically at the helper's caller and needs per-call-site triage.

Top-level sites per file: Get-DbaRandomizedValue (10), Invoke-DbaPfRelog (10), Set-DbaLogin (6), New-DbaLogShippingPrimarySecondary (5), New-DbaLogShippingSecondaryDatabase (4), New-DbaLogShippingSecondaryPrimary (4), New-DbaAvailabilityGroup (4), Import-DbaSpConfigure (4); two each in Test-DbaLastBackup, Get-DbaRandomizedDataset, New-DbaDbDataGeneratorConfig, Add-DbaReplArticle, New-DbaReplSubscription, Convert-DbaMaskingValue, Import-DbaBinaryFile; one each in Invoke-DbaDbLogShipping, Invoke-DbaDbDecryptObject, Set-DbaAgentOperator, Invoke-DbaDbDataGenerator, New-DbaAzAccessToken, Get-DbaRandomizedType, Stop-DbaExternalProcess, Get-DbaDbObjectTrigger, Get-DbaBackupInformation, Export-DbaDacPackage, Expand-DbaDbLogFile, Copy-DbaDatabase, New-DbaLogShippingPrimaryDatabase, Get-LoginPasswordHash, Get-DbaHelp, Get-DbaWaitResource, Convert-DbaIndexToTable. Nested helpers: export-cert (3), Get-MountPointFromDefaultPath (2), Invoke-ProjectDeployment (2), New-SqlTable (2), Get-JobHistory, Get-MountPointFromPath, New-SqlTableWithInferredSchema. One scriptblock-boundary oddity: Import-DbaPfDataCollectorSetTemplate.

Plan

Work through the list one command per PR (fix = stop-and-return, mirroring #10636/#10637, each with a loop-counter regression test proven red on the unfixed command), families batched only where they share one mechanism. Nested-helper sites get call-site triage first, since a helper called from its command's loop is caught there and may be intentional.

Created by Claude and reviewed by Andreas Jordan.

[andreasjordan]

Triage: the 12 nested-helper sites and the scriptblock oddity — all dynamically caught

AST-verified (walked every call site's parents up to the function definition): each of these nested helpers is only ever called from inside a loop of its parent command, so the continue unwinds out of the helper and is caught by that loop — it skips the current item and never escapes the command. Same situation as the nine relog scriptblock sites in Invoke-DbaPfRelog, so these 13 sites are resolved as intentional/dynamically caught, no behavior fix needed:

• Backup-DbaDbCertificate / export-cert (lines 191, 210, 282) — single call site at line 307, inside foreach ($cert in $InputObject).
• Measure-DbaDiskSpaceRequirement / Get-MountPointFromPath:164, Get-MountPointFromDefaultPath:195, 210 — all three call sites (283, 307, 333) sit inside the per-file output loops.
• Get-DbaAgentJobHistory / Get-JobHistory:330 — call sites 341, 355, 358, each inside an instance/job foreach.
• Copy-DbaSsisCatalog / Invoke-ProjectDeployment (182, 185) — call sites 536 and 561, both inside folder/project loops within the destination-instance loop.
• Import-DbaCsv / New-SqlTable:675 and New-SqlTableWithInferredSchema:722, Import-DbaParquet / New-SqlTable:567 — called from inside the per-file loops; the continue skips the current file as intended.
• Import-DbaPfDataCollectorSetTemplate:315 (the scriptblock-boundary oddity) — the site lives in a local $scriptBlock invoked via Invoke-Command at 321/326, both inside the computer/file loops, so the continue is caught there.

Two adjacent defects surfaced during the triage — not this defect class, noting them here so they get folded into future PRs on those commands rather than lost:

• Measure-DbaDiskSpaceRequirement 195–197 and 210–212 have dead code after the -Continue: the $cacheDP.Add($SqlInstance, '?') / return '?' lines can never run in either mode (without EnableException the continue fires first; with it Stop-Function throws first). The "cache the failure as ?" design therefore never engages at these two sites: every affected row re-attempts the connection and the row is skipped instead of being emitted with ?. The command also misses the Test-FunctionInterrupt guard in its process block, so one PR can cover both.
• Backup-DbaDbCertificate:197 calls Stop-Function in stop mode with neither -Continue nor a following return, so a failed Test-DbaPath falls through into the export attempt.

Ledger: 73 of 91 sites resolved (60 before, 13 here). Remaining 18: the nine public singles (Copy-DbaDatabase:777, Expand-DbaDbLogFile:689, Export-DbaDacPackage:168, Get-DbaBackupInformation:352, Get-DbaDbObjectTrigger:119, Get-DbaWaitResource:114, Invoke-DbaDbDecryptObject:214, New-DbaAzAccessToken:257, Stop-DbaExternalProcess:98), the three privates (Convert-DbaIndexToTable:18, Get-DbaHelp:236, Get-LoginPasswordHash:71), and the six Set-DbaLogin sites waiting for #10537.

This triage was created by Claude and reviewed by Andreas Jordan.