internal/Test-ElevationRequirement.ps1

#ValidationTags#Messaging,FlowControl,Pipeline,CodeStyle#

function Test-ElevationRequirement {
    <#
        .SYNOPSIS
            Command that tests, whether the process runs elevated and has to run as such.
         
        .DESCRIPTION
            Command that tests, whether the process runs elevated and has to run as such.
            Some commands require to be run elevated, when executed against localhost, but not when run against a remote computer.
            This command handles that test and manages the reaction to it.
         
        .PARAMETER ComputerName
            The computer that is being targeted by the calling command.
            This most be a localhost variety, for it to be able to fail.
         
        .PARAMETER Continue
            When using the native capability to terminate on fail, this will call continue in non-silent mode.
         
        .PARAMETER ContinueLabel
            When using the native capability to terminate on fail, and using a continue mode, the continue will continue with this label.
         
        .PARAMETER SilentlyContinue
            When using the native capability to terminate on fail, this will call continue in silent mode.
         
        .PARAMETER NoStop
            Does not call stop-function when the test fails, rather only returns $false instead
     
        .PARAMETER Silent
            Replaces user friendly yellow warnings with bloody red exceptions of doom!
            Use this if you want the function to throw terminating errors you want to catch.
         
        .EXAMPLE
            $null = Test-ElevationRequirement -ComputerName $instance -Continue
     
            This will test whether the currently processed instance is localhost and the process is running elevated.
            If it should have elevation but is not running with elevation:
            - In silent mode it will termiante with an exception
            - In default mode, it will continue with the next instance
     
        .EXAMPLE
            if (-not ( Test-ElevationRequirement -ComputerName $instance -NoStop)) {
                # Do whatever
            }
     
            This will test whether the currently processed instance is localhost and the process is running elevated.
            If it isn't running elevated but should be, the overall condition will be met and the if-block is executed.
    #>

    [CmdletBinding(DefaultParameterSetName = 'Stop')]
    Param (
        [DbaInstanceParameter]
        $ComputerName,
        
        [Parameter(ParameterSetName = 'Stop')]
        [switch]
        $Continue,
        
        [Parameter(ParameterSetName = 'Stop')]
        [string]
        $ContinueLabel,
        
        [Parameter(ParameterSetName = 'Stop')]
        [switch]
        $SilentlyContinue,
        
        [Parameter(ParameterSetName = 'NoStop')]
        [switch]
        $NoStop,
        
        [bool]
        $Silent = $Silent
    )
    
    $isElevated = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
    $testResult = $true
    if ($ComputerName.IsLocalHost -and (-not $isElevated)) { $testResult = $false }
    
    if ($PSCmdlet.ParameterSetName -like "NoStop") {
        return $testResult
    }
    elseif ($PSCmdlet.ParameterSetName -like "Stop") {
        if ($testResult) { return $testResult }
        
        $splatStopFunction = @{
            Message = "Console not elevated, but elevation is required to perform all actions within this command"
        }
        
        if (Test-Bound "Continue") { $splatStopFunction["Continue"] = $Continue }
        if (Test-Bound "ContinueLabel") { $splatStopFunction["ContinueLabel"] = $ContinueLabel }
        if (Test-Bound "SilentlyContinue") { $splatStopFunction["SilentlyContinue"] = $SilentlyContinue }
        
        . Stop-Function @splatStopFunction -FunctionName (Get-PSCallStack)[1].Command
        return $testResult
    }
}