Error-Handling.psm1

# Taken from here: https://gallery.technet.microsoft.com/scriptcenter/A-PowerShell-Assert-5e8670e2
# Credit to imfrancisd
function Assert-True 
{ 
<# 
.Synopsis 
Assert that a value is the Boolean value $true. 
.Description 
This function throws an error if any of the following conditions are met: 
    *the value being asserted is $null 
    *the value being asserted is not of type System.Boolean 
    *the value being asserted is not $true 
.Example 
Assert-True ($a -eq $b) 
Throws an error if the expression ($a -eq $b) does not evaluate to $true. 
.Example 
Assert-True ($a -eq $b) -Verbose 
Throws an error if the expression ($a -eq $b) does not evaluate to $true. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
Assert-True ($a -eq $b) -Debug 
Throws an error if the expression ($a -eq $b) does not evaluate to $true. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Boolean 
System.Object 
.Outputs 
None 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
Assert-True ($a -is [System.Int32]) 
Assert-True ($b -is [System.Int32]) 
Assert-True ($a -eq $b) 
#> 
    [CmdletBinding()] 
    Param( 
        #The value to assert. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$false, Position=0)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $Value 
    ) 
 
    $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
        $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
    } 
    if (-not $PSBoundParameters.ContainsKey('Debug')) { 
        $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
    } 
 
    $fail = -not (($Value -is [System.Boolean]) -and $Value) 
 
    if ($VerbosePreference -or $fail) { 
        $message = 'Assertion {0}: {1}, file {2}, line {3}' -f @( 
            $(if ($fail) {'failed'} else {'passed'}), 
            $MyInvocation.Line.Trim(), 
            $MyInvocation.ScriptName, 
            $MyInvocation.ScriptLineNumber 
        ) 
 
        Write-Verbose -Message $message 
 
        if ($fail) { 
            Write-Debug -Message $message 
            throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
        } 
    } 
} 
 
function Assert-False 
{ 
<# 
.Synopsis 
Assert that a value is the Boolean value $false. 
.Description 
This function throws an error if any of the following conditions are met: 
    *the value being asserted is $null 
    *the value being asserted is not of type System.Boolean 
    *the value being asserted is not $false 
.Example 
Assert-False ($a -eq $b) 
Throws an error if the expression ($a -eq $b) does not evaluate to $false. 
.Example 
Assert-False ($a -eq $b) -Verbose 
Throws an error if the expression ($a -eq $b) does not evaluate to $false. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
Assert-False ($a -eq $b) -Debug 
Throws an error if the expression ($a -eq $b) does not evaluate to $false. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Boolean 
System.Object 
.Outputs 
None 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
Assert-False ($null -eq $a) 
Assert-False ($null -eq $b) 
Assert-False ($a -eq $b) 
#> 
    [CmdletBinding()] 
    Param( 
        #The value to assert. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$false, Position=0)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $Value 
    ) 
 
    $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
        $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
    } 
    if (-not $PSBoundParameters.ContainsKey('Debug')) { 
        $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
    } 
 
    $fail = -not (($Value -is [System.Boolean]) -and (-not $Value)) 
 
    if ($VerbosePreference -or $fail) { 
        $message = 'Assertion {0}: {1}, file {2}, line {3}' -f @( 
            $(if ($fail) {'failed'} else {'passed'}), 
            $MyInvocation.Line.Trim(), 
            $MyInvocation.ScriptName, 
            $MyInvocation.ScriptLineNumber 
        ) 
 
        Write-Verbose -Message $message 
 
        if ($fail) { 
            Write-Debug -Message $message 
            throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
        } 
    } 
} 
 
function Assert-Null 
{ 
<# 
.Synopsis 
Assert that a value is $null. 
.Description 
This function throws an error if any of the following conditions are met: 
    *the value being asserted is not $null 
.Example 
Assert-Null $a 
Throws an error if $a does not evaluate to $null. 
.Example 
Assert-Null $a -Verbose 
Throws an error if $a does not evaluate to $null. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
Assert-Null $a -Debug 
Throws an error if $a does not evaluate to $null. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Object 
.Outputs 
None 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
Assert-Null $a 
Assert-Null $b 
Assert-Null $c 
#> 
    [CmdletBinding()] 
    Param( 
        #The value to assert. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$false, Position=0)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $Value 
    ) 
 
    $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
        $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
    } 
    if (-not $PSBoundParameters.ContainsKey('Debug')) { 
        $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
    } 
 
    $fail = $null -ne $Value 
 
    if ($VerbosePreference -or $fail) { 
        $message = 'Assertion {0}: {1}, file {2}, line {3}' -f @( 
            $(if ($fail) {'failed'} else {'passed'}), 
            $MyInvocation.Line.Trim(), 
            $MyInvocation.ScriptName, 
            $MyInvocation.ScriptLineNumber 
        ) 
 
        Write-Verbose -Message $message 
 
        if ($fail) { 
            Write-Debug -Message $message 
            throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
        } 
    } 
} 
 
function Assert-NotNull 
{ 
<# 
.Synopsis 
Assert that a value is not $null. 
.Description 
This function throws an error if any of the following conditions are met: 
    *the value being asserted is $null 
.Example 
Assert-NotNull $a 
Throws an error if $a evaluates to $null. 
.Example 
Assert-NotNull $a -Verbose 
Throws an error if $a evaluates to $null. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
Assert-NotNull $a -Debug 
Throws an error if $a evaluates to $null. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Object 
.Outputs 
None 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
Assert-NotNull $a 
Assert-NotNull $b 
Assert-NotNull $c 
#> 
    [CmdletBinding()] 
    Param( 
        #The value to assert. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$false, Position=0)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $Value 
    ) 
 
    $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
        $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
    } 
    if (-not $PSBoundParameters.ContainsKey('Debug')) { 
        $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
    } 
 
    $fail = $null -eq $Value 
 
    if ($VerbosePreference -or $fail) { 
        $message = 'Assertion {0}: {1}, file {2}, line {3}' -f @( 
            $(if ($fail) {'failed'} else {'passed'}), 
            $MyInvocation.Line.Trim(), 
            $MyInvocation.ScriptName, 
            $MyInvocation.ScriptLineNumber 
        ) 
 
        Write-Verbose -Message $message 
 
        if ($fail) { 
            Write-Debug -Message $message 
            throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
        } 
    } 
} 
 
function Assert-PipelineEmpty 
{ 
<# 
.Synopsis 
Assert that the pipeline does not contain any objects. 
.Description 
This function is useful for asserting that a function does not output any objects. 
 
This function throws an error if any of the following conditions are met: 
    *the current pipeline contains an object 
.Example 
Get-ChildItem 'aFileThatDoesNotExist*' | Assert-PipelineEmpty 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' returns an object. 
.Example 
Get-ChildItem 'aFileThatDoesNotExist*' | Assert-PipelineEmpty -Verbose 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' returns an object. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
Get-ChildItem 'aFileThatDoesNotExist*' | Assert-PipelineEmpty -Debug 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' returns an object. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Object 
.Outputs 
None 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
myFunc1 | Assert-PipelineEmpty 
myFunc2 | Assert-PipelineEmpty 
myFunc3 | Assert-PipelineEmpty 
#> 
    [CmdletBinding()] 
    Param( 
        #The object from the pipeline. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $InputObject 
    ) 
 
    Begin 
    { 
        $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
        if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
            $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
        } 
        if (-not $PSBoundParameters.ContainsKey('Debug')) { 
            $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
        } 
 
        if ($PSBoundParameters.ContainsKey('InputObject')) { 
            throw New-Object -TypeName 'System.ArgumentException' -ArgumentList @( 
                'Assert-PipelineEmpty must take its input from the pipeline.', 
                'InputObject' 
            ) 
        } 
    } 
 
    Process 
    { 
        #fail immediately 
        #do not wait for all pipeline objects 
 
        $message = 'Assertion failed: {0}, file {1}, line {2}' -f @( 
            $MyInvocation.Line.Trim(), 
            $MyInvocation.ScriptName, 
            $MyInvocation.ScriptLineNumber 
        ) 
 
        Write-Verbose -Message $message 
        Write-Debug -Message $message 
        throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
    } 
 
    End 
    { 
        if ($VerbosePreference) { 
            $message = 'Assertion passed: {0}, file {1}, line {2}' -f @( 
                $MyInvocation.Line.Trim(), 
                $MyInvocation.ScriptName, 
                $MyInvocation.ScriptLineNumber 
            ) 
 
            Write-Verbose -Message $message 
        } 
    } 
} 
 
function Assert-PipelineCount 
{ 
<# 
.Synopsis 
Assert the number of objects in the pipeline. 
.Description 
This function is useful for asserting that a function outputs the correct number of objects. 
 
See the -Equals, -Minimum, and -Maximum parameters for more details. 
 
Note: 
This function will output all pipeline objects it receives until an error is thrown, or until there are no more objects left in the pipeline. 
.Example 
$a = Get-ChildItem 'a*' | Assert-PipelineCount 1 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' does not return exactly one object. 
.Example 
$a = Get-ChildItem 'a*' | Assert-PipelineCount -Maximum 10 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' returns more than ten object. 
.Example 
$a = Get-ChildItem 'a*' | Assert-PipelineCount -Minimum 5 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' returns less than five object. 
.Example 
$a = Get-ChildItem 'a*' | Assert-PipelineCount 1 -Verbose 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' does not return exactly one object. 
The -Verbose switch will output the result of the assertion to the Verbose stream. 
.Example 
$a = Get-ChildItem 'a*' | Assert-PipelineCount 1 -Debug 
Throws an error if Get-ChildItem 'aFileThatDoesNotExist' does not return exactly one object. 
The -Debug switch gives you a chance to investigate a failing assertion before an error is thrown. 
.Inputs 
System.Object 
.Outputs 
System.Object 
.Notes 
An example of how this function might be used in a unit test. 
 
#display passing assertions 
$VerbosePreference = [System.Management.Automation.ActionPreference]::Continue 
 
#display debug prompt on failing assertions 
$DebugPreference = [System.Management.Automation.ActionPreference]::Inquire 
 
$a = myFunc1 | Assert-PipelineCount 1 
$b = myFunc2 | Assert-PipelineCount -Minimum 1 
$c = myFunc3 | Assert-PipelineCount -Maximum 1 
#> 
    [CmdletBinding(DefaultParameterSetName='Equals')] 
    Param( 
        #The object from the pipeline. 
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)] 
        [AllowNull()] 
        [AllowEmptyCollection()] 
        [System.Object] 
        $InputObject, 
 
        #The function will throw an error if the number of objects in the pipeline is not equal to the number specified by this parameter. 
        [Parameter(Mandatory=$true, ParameterSetName='Equals', Position=0)] 
        [System.UInt64] 
        $Equals, 
 
        #The function will throw an error if the number of objects in the pipeline is less than the number specified by this parameter. 
        [Parameter(Mandatory=$true, ParameterSetName='Minimum')] 
        [System.UInt64] 
        $Minimum, 
 
        #The function will throw an error if the number of objects in the pipeline is more than the number specified by this parameter. 
        [Parameter(Mandatory=$true, ParameterSetName='Maximum')] 
        [System.UInt64] 
        $Maximum 
    ) 
 
    Begin 
    { 
        $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop 
        if (-not $PSBoundParameters.ContainsKey('Verbose')) { 
            $VerbosePreference = $PSCmdlet.GetVariableValue('VerbosePreference') -as [System.Management.Automation.ActionPreference] 
        } 
        if (-not $PSBoundParameters.ContainsKey('Debug')) { 
            $DebugPreference = $PSCmdlet.GetVariableValue('DebugPreference') -as [System.Management.Automation.ActionPreference] 
        } 
 
        if ($PSBoundParameters.ContainsKey('InputObject')) { 
            throw New-Object -TypeName 'System.ArgumentException' -ArgumentList @( 
                'Assert-PipelineCount must take its input from the pipeline.', 
                'InputObject' 
            ) 
        } 
 
        [System.UInt64]$inputCount = 0 
 
        if ($PSCmdlet.ParameterSetName -eq 'Equals') { 
            $failEarly  = {$inputCount -gt $Equals} 
            $failAssert = {$inputCount -ne $Equals} 
        } elseif ($PSCmdlet.ParameterSetName -eq 'Maximum') { 
            $failEarly  = {$inputCount -gt $Maximum} 
            $failAssert = $failEarly 
        } else { 
            $failEarly  = {$false} 
            $failAssert = {$inputCount -lt $Minimum} 
        } 
    } 
 
    Process 
    { 
        $inputCount++ 
 
        if ((& $failEarly)) { 
            #fail immediately 
            #do not wait for all pipeline objects 
 
            $message = 'Assertion failed: {0}, file {1}, line {2}' -f @( 
                $MyInvocation.Line.Trim(), 
                $MyInvocation.ScriptName, 
                $MyInvocation.ScriptLineNumber 
            ) 
 
            Write-Verbose -Message $message 
            Write-Debug -Message $message 
            throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
        } 
 
        ,$InputObject 
    } 
 
    End 
    { 
        $fail = & $failAssert 
 
        if ($VerbosePreference -or $fail) { 
            $message = 'Assertion {0}: {1}, file {2}, line {3}' -f @( 
                $(if ($fail) {'failed'} else {'passed'}), 
                $MyInvocation.Line.Trim(), 
                $MyInvocation.ScriptName, 
                $MyInvocation.ScriptLineNumber 
            ) 
 
            Write-Verbose -Message $message 
 
            if ($fail) { 
                Write-Debug -Message $message 
                throw New-Object -TypeName 'System.Exception' -ArgumentList @($message) 
            } 
        } 
    } 
}