dsccommunity / dsccommunity/SqlServerDsc

CONTRIBUTING: Update information around `$PSCmdlet.ThrowTerminatingError`

Open
#2,045 0 comments 1 reaction 1 assignee View on GitHub

Nobody has claimed this yet.

documentation in progress
Dominant language
PowerShell
Stars
385
Forks
224
PR merge metrics
No merged PRs in 30d

Description

The documentation should be updated according to this: https://github.com/dsccommunity/SqlServerDsc/pull/1966#issuecomment-1703776151

Also reference: https://stackoverflow.com/questions/49204918/difference-between-throw-and-pscmdlet-throwterminatingerror

https://github.com/dsccommunity/SqlServerDsc/blob/3c3092976409645d74f58707331f66ffe1967127/CONTRIBUTING.md?plain=1#L368-L379

I caught this today where I call a public command (or function) from a another public command. Example below.

function Get-Something
{
    [CmdletBinding()]
    param ()

    $PSCmdlet.ThrowTerminatingError(
        [System.Management.Automation.ErrorRecord]::new(
            'Error message',
            'CODE',
            [System.Management.Automation.ErrorCategory]::InvalidOperation,
            'MyObject'
        )
    )

    "Get-Something exiting" # CORRECT: Does not hit this
}

function Start-Something
{
    [CmdletBinding()]
    param ()

    Get-Something -Name $null -ErrorAction 'Stop'

    "Started" # BUG: This line is executed even though Get-Something throw an exception
}

# This hits the bug in Start-Something
Start-Something

# The user must add -ErrorAction 'Stop' to Start-Something to avoid the bug which is not intuitive
Start-Something -ErrorAction 'Stop'

Similar but using Write-Error (non-terminating error):

function Get-Something
{
    [CmdletBinding()]
    param ()

    Write-Error -Message 'Error message' -Category InvalidOperation -TargetObject 'MyObject' -ErrorId 'CODE'

    "Get-Something exiting" # CORRECT: Does not hit this
}

function Start-Something
{
    [CmdletBinding()]
    param ()

    Get-Something -Name $null -ErrorAction 'Stop'

    "Started" # CORRECT: Does not hit this
}

# This works as expected, stops after the exception in Get-Something
Start-Something

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.