0.6 Finding Your Way Around

Introduction

No one remembers every PowerShell command, parameter and property, not even the people who wrote them, and no one needs to. PowerShell describes itself: four commands answer almost every question about what exists, what a command does, what an object holds and what a short name means.

Analysts who use them work faster than those who search the web, and their answers are right for the version in front of them.

A search engine answers for whatever version the author of the page was using, on whatever platform, with whatever modules. The session answers for exactly what is installed and loaded now. For a course whose evidence spans Windows PowerShell 5.1, PowerShell 7 and several modules, that difference is not academic: the same command can have different parameters in different places.

The four are Get-Command, Get-Help, Get-Member and Get-Alias. Each answers one question, and together they cover the four things you need to know about anything in PowerShell: whether it exists, how to use it, what it gives you, and what a short name hides.

This lesson uses each on the case's evidence and on the commands this course relies on, and shows the most common mistake they prevent: guessing a property name, getting no results and no error, and believing the empty answer.

They are also the commands to use when this course is not in front of you. Every later module introduces new cmdlets, and each lesson explains them, but the habit that lasts is being able to meet an unfamiliar command or object on a real case and work out how to use it in a few minutes, without leaving the console.

By the end of the lesson you can read a command's help and install full help, write help for your own functions, find commands by verb, noun or part of a name, read a command's syntax and parameter sets, list an object's properties and methods, expand aliases, and use strict mode to turn a misspelled property into an error instead of a silent empty result.

The evidence is NE-SHARMA-LT's process export from Lesson 0.1, explored as if for the first time. Everything runs live in this course's PowerShell 7.6.

Get-Help shows a command's documentation, the first thing to read about any command you have not used before. On a fresh PowerShell 7 installation, it shows less than you might expect:

PS C:\Evidence> Get-Help Get-Process
NAME
    Get-Process
    
SYNTAX
    Get-Process [[-Name] <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]
    
    Get-Process [[-Name] <string[]>] -IncludeUserName [<CommonParameters>]
    
    Get-Process -Id <int[]> [-Module] [-FileVersionInfo] [<CommonParameters>]
    
    Get-Process -Id <int[]> -IncludeUserName [<CommonParameters>]
    
    Get-Process -InputObject <Process[]> [-Module] [-FileVersionInfo] [<CommonParameters>]
    
    Get-Process -InputObject <Process[]> -IncludeUserName [<CommonParameters>]
    

ALIASES
    gps
    

REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only partial help.
        -- To download and install Help files for the module that includes this cmdlet, use Update-Help.
        -- To view the Help topic for this cmdlet online, type: "Get-Help Get-Process -Online" or
           go to https://go.microsoft.com/fwlink/?LinkID=2096814.

The name, the syntax, the alias gps, and a remark: Get-Help cannot find the help files and is showing only partial help. PowerShell 7 does not ship its full help text; it generates what it can from the command itself and points to two ways to get the rest, Update-Help and the -Online switch.

Shipping help separately keeps PowerShell small and lets Microsoft correct the documentation without releasing a new version of the shell, at the cost of a step every new installation needs.

Even partial help is useful. It is generated from the command's own definition, so it can never be out of date or describe parameters the installed version lacks.

The syntax lines show every way the command can be called, which Section 4 reads in detail, and the alias line explains a short name you may have seen in a script. For a quick check of what parameters exist, partial help is enough.

Get-Help also takes a parameter's name, Get-Help Get-Process -Parameter Name, to explain just one parameter, and -Examples to show only the worked examples, which are often the fastest route from not knowing a command to using it correctly. Both work best once full help is installed.

Update-Help downloads the full help for the modules installed, run once and then occasionally to refresh it, after which Get-Help shows descriptions, every parameter's explanation and worked examples, offline. Get-Help -Online opens the same page on Microsoft Learn in a browser.

The about_ topics, such as about_Command_Precedence behind Lesson 0.5, arrive with Update-Help too. Update-Help needs an internet connection and, for modules installed for all users, an elevated session; on an isolated analysis machine, Save-Help on a connected machine and Update-Help -SourcePath on the isolated one does the same job from a folder.

Your own functions get full help without downloading anything, from a comment block at the top, as Lesson 11.3 teaches in depth. A function that lists user-owned processes whose parent is missing from the export, with help, then asked for its example and one parameter's description, then run:

PS C:\Evidence> function Get-UserOrphan {
>>     <#
>>     .SYNOPSIS
>>     Lists user-owned processes whose parent is not in the same export.
>>     .PARAMETER Path
>>     A process export written with ConvertTo-Json.
>>     .EXAMPLE
>>     Get-UserOrphan -Path ./procs/proc-sharma.json
>>     #>
>>     param([Parameter(Mandatory)][string]$Path)
>>     $all = Get-Content $Path -Raw | ConvertFrom-Json
>>     $all | Where-Object { $_.Owner -notlike '*SYSTEM' -and $_.ParentProcessId -notin $all.ProcessId -and $_.Name -ne 'System Idle Process' }
>> }
PS C:\Evidence> Get-Help Get-UserOrphan -Examples
NAME
    Get-UserOrphan
    
SYNOPSIS
    Lists user-owned processes whose parent is not in the same export.
    
    
    -------------------------- EXAMPLE 1 --------------------------
    
    PS > Get-UserOrphan -Path ./procs/proc-sharma.json
    
    
    
    
    
    
PS C:\Evidence> (Get-Help Get-UserOrphan -Parameter Path).description.Text
A process export written with ConvertTo-Json.
PS C:\Evidence> Get-UserOrphan -Path ./procs/proc-sharma.json | Format-Table ProcessId, Name, ParentProcessId
ProcessId Name         ParentProcessId
--------- ----         ---------------
     3608 explorer.exe            3584
     7488 rundll32.exe            7316

Get-Help showed the example exactly as it was written, and the parameter's description. It found them because the comment block sits directly inside the function, using keywords such as .SYNOPSIS, .PARAMETER and .EXAMPLE that Get-Help recognizes; misspell a keyword and that part of the help silently disappears, which Lesson 11.3's help tests catch.

The function itself found two user-owned processes whose parent is not in the export: explorer.exe, whose parent exits by design once the user's session is set up, and rundll32 7488, whose parent was the PowerShell process that Word started.

The help you write is the help your colleagues read. A function shared without it forces everyone to read its code to learn what it does; a function with a synopsis, a parameter description and one example explains itself through the same Get-Help they use for Microsoft's commands.

Notice how the function used its own name for the idea: Get-UserOrphan, a Verb-Noun name built from an approved verb and a noun saying what it returns. Anyone who meets it in a script can guess its purpose, run Get-Help on it, and be right about what it does without reading the code, which is the whole point of naming and documenting tools well.

Lesson 0.5 used Get-Command to identify a name. Pointed at a name that does not exist, it fails with the same not-recognized message as running it would, which makes it a safe way to test a command from an unfamiliar script without running anything. It is just as useful to search for commands you do not know yet. By a wildcard, by verb and by noun:

PS C:\Evidence> (Get-Command *Json*).Name -join ', '
ConvertFrom-Json, ConvertTo-Json, Test-Json
PS C:\Evidence> (Get-Command -Verb ConvertTo).Name -join ', '
ConvertTo-CliXml, ConvertTo-Csv, ConvertTo-Html, ConvertTo-Json, ConvertTo-SecureString, ConvertTo-Xml
PS C:\Evidence> (Get-Command -Noun Process).Name -join ', '
Debug-Process, Get-Process, Start-Process, Stop-Process, Switch-Process, Wait-Process

Json found the three commands with Json in their names. On Windows the same search finds the same three, because they are part of PowerShell itself rather than of the operating system; searches for Windows features, such as WinEvent or ScheduledTask, find nothing on Linux, which is itself an answer. -Verb ConvertTo listed every conversion to another format, from CLI XML to a secure string. -Noun Process listed every command that acts on processes. The three lists together took one line each and no prior knowledge of any command in them. Each search starts from what you want to do or what you want to act on, which is usually what you know. Wildcards work on any part of a name: Defender or Mp finds Defender's commands on Windows, Event finds the event log commands, and Secret finds the vault commands of Module 10, each a quick way into an unfamiliar area.

Because the names follow Verb-Noun, these searches work across modules you have never seen. Searching by noun is often the better first move, since the thing you want to act on, a process, a service, an event, a user, is usually clearer in your mind than the verb a module's author chose for the action.

A newly installed module's commands appear in the same searches, and -Module restricts a search to one, as Lesson 11.6 did with the toolkit. When you think a command ought to exist, Get-Command will tell you in a second whether it does.

Get-Command can also search by parameter: Get-Command -ParameterName ComputerName lists every command that can reach another machine directly, a useful question when planning a collection. And -CommandType Cmdlet or Function narrows a search to one kind, which keeps native programs on the path out of the results.

The syntax lines describe exactly how a command can be called. Get-Process has six forms, its parameter sets:

PS C:\Evidence> Get-Command Get-Process -Syntax
Get-Process [[-Name] <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]

Get-Process [[-Name] <string[]>] -IncludeUserName [<CommonParameters>]

Get-Process -Id <int[]> [-Module] [-FileVersionInfo] [<CommonParameters>]

Get-Process -Id <int[]> -IncludeUserName [<CommonParameters>]

Get-Process -InputObject <Process[]> [-Module] [-FileVersionInfo] [<CommonParameters>]

Get-Process -InputObject <Process[]> -IncludeUserName [<CommonParameters>]
PS C:\Evidence> (Get-Command Get-Process).ParameterSets.Name -join ', '
Name, NameWithUserName, Id, IdWithUserName, InputObject, InputObjectWithUserName

Each line of the syntax is one parameter set: a combination of parameters that can be used together in a single call. The set names, Name, NameWithUserName and the rest, are what PowerShell uses internally to decide which set a call matches, and they appear in error messages when a call matches none.

Get-Process can select processes by name, by ID or by passing process objects in, each with or without -IncludeUserName. Parameters from different sets cannot be mixed, which is why Get-Process -Name x -Id 4 is refused.

The error PowerShell gives, that the parameter set cannot be resolved, is one of the most common a newcomer sees, and the syntax lines explain it every time: the two parameters you used never appear on the same line.

The brackets carry the rest of the meaning. They take a minute to learn and then read at a glance. Square brackets around a parameter mean it is optional. A parameter without them is required in that parameter set, and PowerShell asks for it if it is missing.

Square brackets around just its name, as in [[-Name] ], mean the name itself may be left out and the value given by position. Angle brackets give the type: is one or more strings, one or more whole numbers. A parameter with no angle brackets, such as -Module, is a switch: present or absent, with no value.

Reading syntax this way is a small skill that pays off constantly. It is also the quickest way to compare the same command across versions: run -Syntax in Windows PowerShell and in PowerShell 7, and any parameter one has and the other lacks is visible at once.

It tells you whether a parameter takes many values, whether it can be piped, and which parameters conflict, all without reading the full help.

PS> @($p | Where-Object User -like '*SYSTEM').Count

PS> ($p | Get-Member -MemberType NoteProperty).Name
PS> @($p | Where-Object Owner -like '*SYSTEM').Count

PS C:\Evidence> $p = Get-Content ./procs/proc-sharma.json -Raw | ConvertFrom-Json
PS C:\Evidence> ($p | Get-Member -MemberType NoteProperty).Name -join ', '
CommandLine, CreationDate, ExecutablePath, HandleCount, Name, Owner, ParentProcessId, ProcessId, SessionId, WorkingSetSize
PS C:\Evidence> @($p | Where-Object Owner -like '*SYSTEM').Count
16
PS C:\Evidence> ('text' | Get-Member -MemberType Method).Count
52

PS C:\Evidence> Get-Alias iex, iwr, gci, select | Format-Table Name, Definition
Name   Definition
----   ----------
iex    Invoke-Expression
iwr    Invoke-WebRequest
gci    Get-ChildItem
select Select-Object
PS C:\Evidence> (Get-Alias -Definition Get-ChildItem).Name -join ', '
dir, gci
PS C:\Evidence> (Get-Alias).Count
108

PS C:\Evidence> $p = Get-Content ./procs/proc-sharma.json -Raw | ConvertFrom-Json
PS C:\Evidence> Set-StrictMode -Version Latest
PS C:\Evidence> try { $p[1].User } catch { $_.Exception.Message }
The property 'User' cannot be found on this object. Verify that the property exists.
PS C:\Evidence> $p[1].Owner
NT AUTHORITY\SYSTEM
PS C:\Evidence> Set-StrictMode -Off

PS C:\Evidence> $p = Get-Content ./procs/proc-sharma.json -Raw | ConvertFrom-Json
PS C:\Evidence> function Get-UserOrphan {
>>     <#
>>     .SYNOPSIS
>>     Lists user-owned processes whose parent is not in the same export.
>>     .PARAMETER Path
>>     A process export written with ConvertTo-Json.
>>     .EXAMPLE
>>     Get-UserOrphan -Path ./procs/proc-sharma.json
>>     #>
>>     param([Parameter(Mandatory)][string]$Path)
>>     $all = Get-Content $Path -Raw | ConvertFrom-Json
>>     $all | Where-Object { $_.Owner -notlike '*SYSTEM' -and $_.ParentProcessId -notin $all.ProcessId -and $_.Name -ne 'System Idle Process' }
>> }
PS C:\Evidence> @(
>>     (Get-Help Get-UserOrphan).Synopsis -like "Lists user-owned*"
>>     (Get-Alias iex).Definition -eq "Invoke-Expression"
>>     ($p | Get-Member -MemberType NoteProperty).Name -contains "Owner"
>>     @(Get-Command -Noun Process).Count -eq 6
>>     @(Get-UserOrphan -Path ./procs/proc-sharma.json | Where-Object Name -eq "rundll32.exe").Count -eq 1
>> )
True
True
True
True
True