New-StreamDeckShell.ps1


Description

Purpose

Launches a new PowerShell console window suitable for Stream Deck buttons while running under alternate credentials.

Detailed Description

Wraps the New-Shell command to guarantee a dedicated console window is created even when invoked from hosts that hide child windows (for example, Stream Deck scripts). This function forces the RunAsUser scenario to use a separate cmd.exe process so the interactive shell remains visible.

Back to Top

Usage

Example 1

$credential = Get-Secret -Name 'lukeleigh.admin'

New-StreamDeckShell -Credential $credential

Example 2

$credential = Get-Secret -Name 'lukeleigh.admin'

New-StreamDeckShell -Credential $credential -Shell ‘PowerShell’ -WindowTitle ‘Admin PowerShell’

Back to Top

Notes

No additional notes.

Back to Top


Script

function New-StreamDeckShell {
    <#
    .SYNOPSIS
    Launches a new PowerShell console window suitable for Stream Deck buttons while running under alternate credentials.

    .DESCRIPTION
    Wraps the New-Shell command to guarantee a dedicated console window is created even when invoked from hosts that hide child
    windows (for example, Stream Deck scripts). This function forces the RunAsUser scenario to use a separate cmd.exe process so
    the interactive shell remains visible.

    .PARAMETER Credential
    Credentials used to start the shell session.

    .PARAMETER Shell
    Specifies which shell executable to launch. Valid values are 'pwsh' (PowerShell 7+) and 'PowerShell' (Windows PowerShell).

    .PARAMETER WindowTitle
    Optional console window title applied when the shell is launched.

    .PARAMETER ArgumentList
    Additional arguments that should be passed to the target shell executable.

    .EXAMPLE
    $credential = Get-Secret -Name 'lukeleigh.admin'
    New-StreamDeckShell -Credential $credential

    .EXAMPLE
    $credential = Get-Secret -Name 'lukeleigh.admin'
    New-StreamDeckShell -Credential $credential -Shell 'PowerShell' -WindowTitle 'Admin PowerShell'
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [pscredential]
        $Credential,

        [Parameter(Mandatory = $false)]
        [ValidateSet('pwsh', 'PowerShell')]
        [string]
        $Shell = 'pwsh',

        [Parameter(Mandatory = $false)]
        [string]
        $WindowTitle,

        [Parameter(Mandatory = $false)]
        [string[]]
        $ArgumentList = @()
    )

    $runAsUserMap = @{
        pwsh       = 'pwshRunAsUser'
        PowerShell = 'PowerShellRunAsUser'
    }

    $runAsUser = $runAsUserMap[$Shell]

    $parameters = @{
        RunAsUser      = $runAsUser
        Credentials    = $Credential
        ForceNewWindow = $true
    }

    if ($ArgumentList -and $ArgumentList.Count -gt 0) {
        $parameters['ShellArgumentList'] = $ArgumentList
    }

    if ($PSBoundParameters.ContainsKey('WindowTitle') -and -not [string]::IsNullOrWhiteSpace($WindowTitle)) {
        $parameters['WindowTitle'] = $WindowTitle
    }

    New-Shell @parameters
}

Back to Top

Download

Please feel free to copy parts of the script or if you would like to download the entire script, simply click the download button. You can download the complete repository in a zip file by clicking the Download link in the menu bar on the left hand side of the page.


Report Issues

You can report an issue or contribute to this site on GitHub. Simply click the button below and add any relevant notes. I will attempt to respond to all issues as soon as possible.

Issue


Back to Top