Show-One

background

I sometimes find myself needing to examine individual powershell objects from a collection in detail. Most recently this was the case while working on automating the provisioning of resource mailboxes for a client. I was building out the process and validation logic that we were going to use and needed to examine the ‘intermediate’ objects being produced by the process prior to their use to generate the real objects in Exchange Online.

Here’s the quick function that I came up with to let me output each object to Format-List, one at a time, so that I wouldn’t have to try to scroll up and down in my console to do the examination, and with optional Clear-Screen between each output.

code

function Show-One
{
    [cmdletbinding()]
    param
    (
        [parameter(ValueFromPipeline)]
        [psobject[]]$PSObject
        ,
        [switch]$ClearHost
    )
    process
    {
        foreach ($o in $PSObject)
        {
            if ($true -eq $quit)
            {
                break
            }
            if ($true -eq $Clearhost) {Clear-Host}
            $o | Format-List -Property * -Force
            if ($(Read-Host -Prompt "Show next object (any key), or quit (q)?") -eq 'q')
            {
                $quit = $true
            }
        }
    }
}

usage examples

example 1 - Pipeline input usage

Get-AzureADDomain | Show-One
# with -ClearHost
Get-AzureADDomain | Show-One -clearhost

see the note below about canceling pipelines.

example 2 - Parameter input usage

$AADDomains = Get-AzureADDomain
Show-One -Psobject $AzureADDomains

output example

ongoing usage

I added this function to my ‘profile’ module on github in the UtilityFunctions.ps1 file.

stopping a pipeline

While writing this function what I really wanted to do was cancel the processing of the pipeline in the process block if the user entered ‘q’ at the read-host prompt instead of using the workaround that I implemented with the $quit variable. However, that’s not (easily) possible without implementing some complex functions. PowerShell does have this functionality in the Select-Object cmdlet via the -first parameter. But the ability to stop a pipeline is not exposed as a cmdlet or public method. Help upvote the issue on github.