How do you list all the objects and values within a PowerShell object, investigate an object or explore its structure? There must be a simple way. I used to use ConvertTo-JSON. This is fine up to a point but what if you just wish to search for strings or look for objects with a cartain name or value? What if you need their path so you can reference them? It isn’t plain-sailing. In the ISE, the intellisense will help you a lot but I want more and I want to do it in script rather than the IDE
Let’s start with a silly example just to get in the mood. Imagine we have a hashtable that tells us our servers and users.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
$ServersAndUsers = @{'Shem' = @{ 'version' = '2017'; 'Location' = 'Server room'; 'Users'=@('Fred','Jane','Mo') }; 'Ham' = @{ 'version' = '2019'; 'Location' = 'Floor two rack'; 'Downtime'=$null 'Users'=@('Fred','Jane',@{'TheDevopsTeam'=@('Joe','Tracy','Arthur')},'Phil','Tony') }; 'Japeth' = @{ 'version' = '2008'; 'Location' = 'basement rack'; 'Users'=@('Karen','Wyonna','Henry') } } |
If we just pipe it to Format-Table we get this, which is a good start, but those values are more tantalising than helpful
|
1 2 3 4 5 |
Name Value ---- ----- Ham {Users, Downtime, version, Location} Japeth {Users, version, Location} Shem {Users, version, Location} |
Getting the names of the base members isn’t that helpful. After all, we can also get the names of the servers through Get-Member
|
1 |
[PSCustomObject]$ServersAndUsers | Get-Member -MemberType NoteProperty|Select Name |
|
1 2 3 4 5 6 |
PS C:\Users\Phil> [PSCustomObject]$ServersAndUsers | Get-Member -MemberType NoteProperty|Select Name Name ---- Ham Japeth Shem |
… Or, knowing it is a hashtable, use …
|
1 |
$ServersAndUsers.keys |
|
1 2 3 4 |
PS C:\Users\Phil> $ServersAndUsers.keys Ham Japeth Shem |
If we can assume that it is a hashtable, we can get name and value as we did with Format-Table
|
1 2 3 4 |
$ServersAndUsers | Foreach-Object -ov obj{ $_ } | Foreach{ $_.Keys } | Foreach{ [pscustomobject]@{ 'Path' = $_; 'Value' = $obj.($_) } } |
|
1 2 3 4 5 |
Path Value ---- ----- Ham {Users, Downtime, version, Location} Japeth {Users, version, Location} Shem {Users, version, Location} |
Well. That’s progress of a sort in that we have something we can work on, but of course, not every object will be a hashtable. but we can elaborate it to list more types of object by turning a hashtable into a pscustomobject (Beware: the order of properties isn’t preserved). We’ll output a PSCustomObject as well so that we can output the results or do filters on them.
|
1 2 3 4 5 |
[pscustomObject]$ServersAndUsers | Foreach-Object -ov obj { $_ } | gm -MemberType NoteProperty | Foreach{ [pscustomobject]@{ 'Path' = "$.$($_.Name)"; 'Value' = $obj.($_.Name) } } |
We changed that hashtable into a PSCustomPbject so we could iterate through the names using the Noteproperties. We get those noteproperties via the Get-Member (gm) cmdlet. We added a $ Reference to represent whatever name you used for the variable that referred to your object.
the problem here is that this trick only works for a pscustomObject or something we can change into it, such as a hashtable or ordered dictionary. For other objects, we use the property members rather than the NoteProperty members.
You can see that we need recursion because all the values are themselves objects of some description. Most data is more than a simple hashtable or pscustomObject.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
function Display-Object ($TheObject, $Parent = '$') { $MemberType = 'Property' #assume this for the time being $ObjType = $TheObject.GetType().Name; if ($ObjType -in 'Hashtable', 'OrderedDictionary') { $TheObject = [pscustomObject]$TheObject; $ObjType = 'PSCustomObject'; } if ($ObjType -eq 'PSCustomObject') { $MemberType = 'NoteProperty' } $TheObject | gm -MemberType $MemberType | Foreach{ Try { $child = $TheObject.($_.Name); } Catch { $Child = $null } # avoid crashing on write-only objects if ($child -eq $null -or #is the current child a value or a null? $child.GetType().BaseType.Name -eq 'ValueType' -or $child.GetType().Name -in @('String', 'Object[]')) {#output the value of this as a ps object [pscustomobject]@{ 'Path' = "$Parent.$($_.Name)"; 'Value' = $Child; } } else #not a value but an object of some sort { Display-Object -TheObject $child -Parent "$Parent.$($_.Name)" } } } |
|
1 |
Display-Object $ServersAndUsers |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
Path Value ---- ----- $.Ham.Downtime $.Ham.Location Floor two rack $.Ham.Users {Fred, Jane, System.Collections.Hashtable, Phil...} $.Ham.version 2019 $.Japeth.Location basement rack $.Japeth.Users {Karen, Wyonna, Henry} $.Japeth.version 2008 $.Shem.Location Server room $.Shem.Users {Fred, Jane, Mo} $.Shem.version 2017 |
The problem here is that it doesn’t yet handle arrays that well. We also need to allow the function to avoid a list of one or more names and allow it to work with a range of objects such as XML objects. It is also wise to copy ConvertTo-JSON in the way that it specifies the allowable depth. As a final touch, we allow it to keep its cool when presented with write-only values.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 |
<# .SYNOPSIS Displays an object's values and the 'dot' paths to them .DESCRIPTION A detailed description of the Display-Object function. .PARAMETER TheObject The object that you wish to display .PARAMETER depth the depth of recursion (keep it low!) .PARAMETER Avoid an array of names of pbjects or arrays you wish to avoid. .PARAMETER Parent For internal use, but you can specify the name of the variable .PARAMETER CurrentDepth For internal use .NOTES Additional information about the function. #> function Display-Object { [CmdletBinding()] param ( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] $TheObject, [int]$depth = 5, [Object[]]$Avoid = @('#comment'), [string]$Parent = '$', [int]$CurrentDepth = 0 ) if (($CurrentDepth -ge $Depth) -or ($TheObject -eq $Null)) { return; } #prevent runaway recursion $ObjectTypeName = $TheObject.GetType().Name #find out what type it is if ($ObjectTypeName -in 'HashTable', 'OrderedDictionary') { #If you can, force it to be a PSCustomObject $TheObject = [pscustomObject]$TheObject; $ObjectTypeName = 'PSCustomObject' }#first do objects that cannot be treated as an array. if ($TheObject.Count -le 1 -and $ObjectTypeName -ne 'object[]') #not something that behaves like an array { # figure out where you get the names from if ($ObjectTypeName -in @('PSCustomObject')) # Name-Value pair properties created by Powershell { $MemberType = 'NoteProperty' } else { $MemberType = 'Property' } #now go through the names $TheObject | gm -MemberType $MemberType | where { $_.Name -notin $Avoid } | Foreach{ Try { $child = $TheObject.($_.Name); } Catch { $Child = $null } # avoid crashing on write-only objects $brackets=''; if ($_.Name -like '*.*'){$brackets="'"} if ($child -eq $null -or #is the current child a value or a null? $child.GetType().BaseType.Name -eq 'ValueType' -or $child.GetType().Name -in @('String', 'String[]')) { [pscustomobject]@{ 'Path' = "$Parent.$brackets$($_.Name)$brackets"; 'Value' = $Child; } } elseif (($CurrentDepth + 1) -eq $Depth) { [pscustomobject]@{ 'Path' = "$Parent.$brackets$($_.Name)$brackets"; 'Value' = $Child; } } else #not a value but an object of some sort { Display-Object -TheObject $child -depth $Depth -Avoid $Avoid ` -Parent "$Parent.$brackets$($_.Name)$brackets" ` -CurrentDepth ($currentDepth + 1) } } } else #it is an array { if ($TheObject.Count -gt 0) {0..($TheObject.Count - 1) | Foreach{ $child = $TheObject[$_]; if (($child -eq $null) -or #is the current child a value or a null? ($child.GetType().BaseType.Name -eq 'ValueType') -or ($child.GetType().Name -in @('String', 'String[]'))) #if so display it { [pscustomobject]@{ 'Path' = "$Parent[$_]"; 'Value' = "$($child)"; } } elseif (($CurrentDepth + 1) -eq $Depth) { [pscustomobject]@{ 'Path' = "$Parent[$_]"; 'Value' = "$($child)"; } } else #not a value but an object of some sort so do a recursive call { Display-Object -TheObject $child -depth $Depth -Avoid $Avoid -parent "$Parent[$_]" ` -CurrentDepth ($currentDepth + 1) } } } else {[pscustomobject]@{ 'Path' = "$Parent"; 'Value' = $Null }} } } |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
Path Value ---- ----- $.Ham.Downtime $.Ham.Location Floor two rack $.Ham.Users[0] Fred $.Ham.Users[1] Jane $.Ham.Users[2].TheDevopsTeam[0] Joe $.Ham.Users[2].TheDevopsTeam[1] Tracy $.Ham.Users[2].TheDevopsTeam[2] Arthur $.Ham.Users[3] Phil $.Ham.Users[4] Tony $.Ham.version 2019 $.Japeth.Location basement rack $.Japeth.Users[0] Karen $.Japeth.Users[1] Wyonna $.Japeth.Users[2] Henry $.Japeth.version 2008 $.Shem.Location Server room $.Shem.Users[0] Fred $.Shem.Users[1] Jane $.Shem.Users[2] Mo $.Shem.version 2017 |
Naturally, one can tinker with the values you return. Some people will want a ‘name/index’ column. I’ve kept it simple. I like to know the path because that tells me the structure and it provides the correct dot syntax to get the value from the object.
|
1 |
$ServersAndUsers.Shem.Location |
|
1 2 3 |
Path Value ---- ----- $.Ham.Users[4] Tony |
You just substitute the name of the variable representing the objects for the $ symbol in the path.
You can filter what comes back. What server does Tony use?
|
1 |
Display-Object $ServersAndUsers | where {$_.Value -like '*Tony*' } |
|
1 2 3 |
Path Value ---- ----- $.Ham.Users[4] Tony |
What are the server locations?
|
1 |
Display-Object $ServersAndUsers | where {$_.Path -like '*location*' } |
|
1 2 3 4 5 |
Path Value ---- ----- $.Ham.Location Floor two rack $.Japeth.Location basement rack $.Shem.Location Server room |
Let’s try a text file..
|
1 2 3 4 5 6 7 8 9 |
@' Here lies John Bunn who was killed by a gun his name wasn't bun but Wood 'Wood' wouldn't rhyme with gun but 'Bunn' would Anon '@>"$env:Temp\Secondpoem.txt" Display-Object (Get-Content "$env:Temp\Secondpoem.txt") |
|
1 2 3 4 5 6 7 8 |
Path Value ---- ----- $[0] Here lies John Bunn $[1] who was killed by a gun $[2] his name wasn't bun but Wood $[3] 'Wood' wouldn't rhyme with gun but 'Bunn' would $[4] $[5] Anon |
We can display other, meatier, objects such as the PowerShell process
|
1 |
Display-Object (get-process pwsh) -depth 2 |
(too much to display in a Blog!)
What if you just wanted to look at an object in the depths of a large object?
|
1 |
Display-Object (get-process pwsh).MainModule -depth 2 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
Path Value ---- ----- $.BaseAddress 140697139347456 $.Container $.EntryPointAddress 140697139412848 $.FileName C:\Program Files\PowerShell\7\pwsh.exe $.FileVersionInfo.Comments PowerShell on Windows top-level project $.FileVersionInfo.CompanyName Microsoft Corporation $.FileVersionInfo.FileBuildPart 3 $.FileVersionInfo.FileDescription pwsh $.FileVersionInfo.FileMajorPart 7 $.FileVersionInfo.FileMinorPart 1 $.FileVersionInfo.FileName C:\Program Files\PowerShell\7\pwsh.exe $.FileVersionInfo.FilePrivatePart 0 $.FileVersionInfo.FileVersion 7.1.3.0 $.FileVersionInfo.InternalName pwsh.dll $.FileVersionInfo.IsDebug False $.FileVersionInfo.IsPatched False $.FileVersionInfo.IsPreRelease False $.FileVersionInfo.IsPrivateBuild False $.FileVersionInfo.IsSpecialBuild False $.FileVersionInfo.Language Language Neutral $.FileVersionInfo.LegalCopyright (c) Microsoft Corporation. $.FileVersionInfo.LegalTrademarks $.FileVersionInfo.OriginalFilename pwsh.dll $.FileVersionInfo.PrivateBuild $.FileVersionInfo.ProductBuildPart 3 $.FileVersionInfo.ProductMajorPart 7 $.FileVersionInfo.ProductMinorPart 1 $.FileVersionInfo.ProductName PowerShell $.FileVersionInfo.ProductPrivatePart 0 $.FileVersionInfo.ProductVersion 7.1.3 SHA: 33ce13a0df94183fde13a07ddee0722a017a8d1d $.FileVersionInfo.SpecialBuild $.ModuleMemorySize 290816 $.ModuleName pwsh.exe $.Site |
Once you can ‘walk’ through an object and search them some possibilities open up. You can slice and dice them; You can convert objects to markup or find out if they’ve changed and how. If you are in a DevOps Windows environment, you’re likely to have all sorts of objects that are delivered to you by cmdlets that monitor the servers. It is useful to be able to investigate them and quickly learn how to pull out just the data you need. Hopefully, I’ll be able to show some of these in this series of Blog posts.
This function saved me a great deal of time when trying to get the result of a regex match into a rational format, so I have a certain affection for it.
I’ve added the source to a collection of PowerShell utilities on my github repositories. I’ve done a couple of fixes since this was first published. Let me know of any good ideas for enhancements!
Load comments