Above all else, the design of Windows PowerShell places priority on its use as an efficient and powerful interactive shell. Even its scripting language plays a critical role in this effort, as it too heavily favors interactive use.
What surprises most people when they first launch PowerShell is its similarity to the command prompt that has long existed as part of Windows. Familiar tools continue to run. Familiar commands continue to run. Even familiar hotkeys are the same. Supporting this familiar user interface, though, is a powerful engine that lets you accomplish once cumbersome administrative and scripting tasks with ease.
This chapter introduces PowerShell from the perspective of its interactive shell.
You rely on a lot of effort invested in your current tools. You have traditional executables, Perl scripts, VBScript, and of course, a legacy build system that has organically grown into a tangled mess of batch files. You want to use PowerShell, but you don’t want to give up everything you already have.
To run a program, script, batch file, or other executable command in the system’s path, enter its filename. For these executable types, the extension is optional:
Program.exe arguments ScriptName.ps1 arguments BatchFile.cmd arguments
To run a command that contains a space in its name, enclose
its filename in single-quotes (') and
precede the command with an ampersand (&), known in PowerShell as the
invoke operator:
& 'C:\Program Files\Program\Program.exe' arguments
To run a command in the current directory, place .\ in front of its filename:
.\Program.exe arguments
To run a command with spaces in its name from the current
directory, precede it with both an ampersand and .\:
& '.\Program With Spaces.exe' arguments
In this case, the solution is mainly to use your current tools as you always have. The only difference is that you run them in the PowerShell interactive shell rather than cmd.exe.
The final three tips in the Solution merit special attention. They are the features of PowerShell that many new users stumble on when it comes to running programs. The first is running commands that contain spaces. In cmd.exe, the way to run a command that contains spaces is to surround it with quotes:
"C:\Program Files\Program\Program.exe"
In PowerShell, though, placing text inside quotes is part of a feature that lets you evaluate complex expressions at the prompt, as shown in Example 1-1.
Example 1-1. Evaluating expressions at the PowerShell prompt
PS > 1 + 1 2 PS > 26 * 1.15 29.9 PS > "Hello" + " World" Hello World PS > "Hello World" Hello World PS > "C:\Program Files\Program\Program.exe" C:\Program Files\Program\Program.exe PS >
So, a program name in quotes is no different from any other
string in quotes. It’s just an expression. As shown previously, the
way to run a command in a string is to precede that string with the
invoke operator (&). If the
command you want to run is a batch file that modifies its environment,
see Program: Retain Changes to Environment Variables Set by a Batch
File.
Note
By default, PowerShell’s security policies prevent scripts from running. Once you begin writing or using scripts, though, you should configure this policy to something less restrictive. For information on how to configure your execution policy, see Enable Scripting Through an Execution Policy.
The second command that new users (and seasoned veterans before coffee!) sometimes stumble on is running commands from the current directory. In cmd.exe, the current directory is considered part of the path: the list of directories that Windows searches to find the program name you typed. If you are in the C:\Programs directory, cmd.exe looks in C:\Programs (among other places) for applications to run.
PowerShell, like most Unix shells, requires that you explicitly
state your desire to run a program from the current directory. To do
that, you use the .\Program.exe
syntax, as shown previously. This prevents malicious users on your
system from littering your hard drive with evil programs that have
names similar to (or the same as) commands you might run while
visiting that directory.
To save themselves from having to type the location of commonly used scripts and programs, many users put commonly used utilities along with their PowerShell scripts in a “tools” directory, which they add to their system’s path. If PowerShell can find a script or utility in your system’s path, you do not need to explicitly specify its location.
If you want PowerShell to automatically look in your current
working directory for scripts, you can add a period (.) to your PATH environment variable.
For more information about updating your system path, see Modify the User or System Path.
If you want to capture the output of a command, you can either save the results into a variable, or save the results into a file. To save the results into a variable, see Store Information in Variables. To save the results into a file, see Store the Output of a Command into a File.
To specify arguments to a command, you can again type them
just as you would in other shells. For example, to make a specified
file read-only (two arguments to attrib.exe), simply type:
attrib +R c:\path\to\file.txt
Where many scripters get misled when it comes to command arguments is how to change them within your scripts. For example, how do you get the filename from a PowerShell variable? The answer is to define a variable to hold the argument value, and just use that in the place you used to write the command argument:
$filename = "c:\path\to\other\file.txt" attrib +R $filename
You can use the same technique when you call a PowerShell cmdlet, script, or function:
$filename = "c:\path\to\other\file.txt" Get-Acl -Path $filename
If you see a solution that uses the Invoke-Expression cmdlet to compose command
arguments, it is almost certainly incorrect. The Invoke-Expression cmdlet takes the string
that you give it and treats it like a full PowerShell script. As just
one example of the problems this can cause, consider the following:
filenames are allowed to contain the semicolon (;) character, but when Invoke-Expression sees a semicolon, it
assumes that it is a new line of PowerShell script. For example, try
running this:
$filename = "c:\file.txt; Write-Warning 'This could be bad'" Invoke-Expression "Get-Acl -Path $filename"
Given that these dynamic arguments often come from user input,
using Invoke-Expression to compose
commands can (at best) cause unpredictable script results. Worse, it
could result in damage to your system or a security
vulnerability.
In addition to letting you supply arguments through variables one at a time, PowerShell also lets you supply several of them at once through a technique known as splatting. For more information about splatting, see Dynamically Compose Command Parameters.
To run a PowerShell command, type its name at the command prompt. For example:
PS > Get-Process
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
133 5 11760 7668 46 1112 audiodg
184 5 33248 508 93 1692 avgamsvr
143 7 31852 984 97 1788 avgemcThe Get-Process command is
an example of a native PowerShell command, called a
cmdlet. As compared to traditional commands,
cmdlets provide significant benefits to both administrators and
developers:
They share a common and regular command-line syntax.
They support rich pipeline scenarios (using the output of one command as the input of another).
They produce easily manageable object-based output, rather than error-prone plain-text output.
Because the Get-Process cmdlet
generates rich object-based output, you can use its output for many
process-related tasks.
Every PowerShell command lets you provide input to the command through its parameters. For more information on providing input to commands, see Running Commands.
The Get-Process cmdlet is just
one of the many that PowerShell supports. See Find a Command to Accomplish a Task to learn techniques for finding
additional commands that PowerShell supports.
For more information about working with classes from the .NET Framework, see Work with .NET Objects.
You have a command line that works from cmd.exe, and want to resolve errors that occur from running that command in PowerShell.
Enclose any affected command arguments in single quotes to prevent them from being interpreted by PowerShell, and replace any single quotes in the command with two single quotes.
PS > cmd /c echo '!"#$%&''()*+,-./09:;<=>?@AZ[\]^_`az{|}~'
!"#$%&'()*+,-./09:;<=>?@AZ[\]^_`az{|}~For complicated commands where this does not work, use the
verbatim argument (--%) syntax.
PS > cmd /c echo 'quotes' "and" $variables @{ etc = $true }
quotes and System.Collections.Hashtable
PS > cmd --% /c echo 'quotes' "and" $variables @{ etc = $true }
'quotes' "and" $variables @{ etc = $true }One of PowerShell’s primary goals has always been command consistency. Because of this, cmdlets are very regular in the way that they accept parameters. Native executables write their own parameter parsing, so you never know what to expect when working with them. In addition, PowerShell offers many features that make you more efficient at the command line: command substitution, variable expansion, and more. Since many native executables were written before PowerShell was developed, they may use special characters that conflict with these features.
As an example, the command given in the Solution uses all the special characters available on a typical keyboard. Without the quotes, PowerShell treats some of them as language features, as shown in Table 1-1.
Table 1-1. Sample of special characters
| Special character | Meaning |
|---|---|
| The beginning (or end) of quoted text |
| The beginning of a comment |
| The beginning of a variable |
| Reserved for future use |
| Parentheses used for subexpressions |
| Statement separator |
| Script block |
| Pipeline separator |
| Escape character |
When surrounded by single quotes, PowerShell accepts these characters as written, without the special meaning.
Despite these precautions, you may still sometimes run into a command that doesn’t seem to work when called from PowerShell. For the most part, these can be resolved by reviewing what PowerShell passes to the command and escaping the special characters.
To see exactly what PowerShell passes
to that command, you can view the output of the trace source called
NativeCommandParameterBinder:
PS > Trace-Command NativeCommandParameterBinder {
cmd /c echo '!"#$%&''()*+,-./09:;<=>?@AZ[\]^_`az{|}~'
} -PsHost
DEBUG: NativeCommandParameterBinder Information: 0 : WriteLine
Argument 0: /c
DEBUG: NativeCommandParameterBinder Information: 0 : WriteLine
Argument 1: echo
DEBUG: NativeCommandParameterBinder Information: 0 : WriteLine
Argument 2: !#$%&'()*+,-./09:;<=>?@AZ[\]^_`az{|}~
!"#$%&'()*+,-./09:;<=>?@AZ[\]^_`az{|}~If the command arguments shown in this output don’t match the arguments you expect, they have special meaning to PowerShell and should be escaped.
For a complex enough command that “just used to work,” though,
escaping special characters is tiresome. To escape the whole command
invocation, use the verbatim argument marker (--%) to prevent PowerShell from interpreting
any of the remaining characters on the line. You can place this marker
anywhere in the command’s arguments, letting you benefit from PowerShell
constructs where appropriate. The following example uses a PowerShell
variable for some of the command arguments, but then uses verbatim
arguments for the rest:
PS > $username = "Lee"
PS > cmd /c echo Hello $username with 'quotes' "and" $variables @{ etc = $true }
Hello Lee with quotes and System.Collections.Hashtable
PS > cmd /c echo Hello $username `
--% with 'quotes' "and" $variables @{ etc = $true }
Hello Lee with 'quotes' "and" $variables @{ etc = $true }While in this mode, PowerShell also accepts cmd.exe-style environment variables—as these are frequently used in commands that “just used to work”:
PS > $env:host = "myhost" PS > ping %host% Ping request could not find host %host%. Please check the name and try again. PS > ping --% %host% Pinging myhost [127.0.1.1] with 32 bytes of data: (...)
Add an entry to the PSDefaultParameterValues hashtable.
PS > Get-Process
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
150 13 9692 9612 39 21.43 996 audiodg
1013 84 45572 42716 315 1.67 4596 WWAHost
(...)
PS > $PSDefaultParameterValues["Get-Process:ID"] = $pid
PS > Get-Process
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
584 62 132776 157940 985 13.15 9104 powershell_ise
PS > Get-Process -Id 0
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
0 0 0 20 0 0 IdleIn PowerShell, many commands (cmdlets and advanced functions) have parameters that let you configure their behavior. For a full description of how to provide input to commands, see Running Commands. Sometimes, though, supplying values for those parameters at each invocation becomes awkward or repetitive.
Until PowerShell version 3, it was the responsibility of each
cmdlet author to recognize awkward or repetitive configuration
properties and build support for “preference variables” into the cmdlet
itself. For example, the Send-MailMessage cmdlet looks for the $PSEmailServer variable if you do not supply a
value for its -SmtpServer
parameter.
To make this support more consistent and configurable,
PowerShell version 3 introduces the PSDefaultParameterValues preference variable.
This preference variable is a hashtable. Like all other PowerShell
hashtables, entries come in two parts: the key and the value.
Keys in the PSDefaultParameterValues hashtable must match
the pattern
cmdlet:parameter—that
is, a cmdlet name and parameter name, separated by a colon. Either (or
both) may use wildcards, and spaces between the command name, colon, and
parameter are ignored.
Values for the cmdlet/parameter pairs can be either a simple parameter value (a string, boolean value, integer, etc.) or a script block. Simple parameter values are what you will use most often.
If you need the default value to dynamically change based on what parameter values are provided so far, you can use a script block as the default. When you do so, PowerShell evaluates the script block and uses its result as the default value. If your script block doesn’t return a result, PowerShell doesn’t apply a default value.
When PowerShell invokes your script block, $args[0] contains information about any
parameters bound so far: BoundDefaultParameters, BoundParameters, and BoundPositionalParameters. As one example of
this, consider providing default values to the -Credential parameter based on the computer
being connected to. Here is a function that simply outputs the
credential being used:
function RemoteConnector
{
param(
[Parameter()]
$ComputerName,
[Parameter(Mandatory = $true)]
$Credential)
"Connecting as " + $Credential.UserName
}Now, you can define a credential map:
PS > $credmap = @{}
PS > $credmap["RemoteComputer1"] = Get-Credential
PS > $credmap["RemoteComputer2"] = Get-CredentialThen, create a parameter default for all Credential parameters that looks at the
ComputerName bound parameter:
$PSDefaultParameterValues["*:Credential"] = {
if($args[0].BoundParameters -contains "ComputerName")
{
$cred = $credmap[$PSBoundParameters["ComputerName"]]
if($cred) { $cred }
}
}Here is an example of this in use:
PS > RemoteConnector -ComputerName RemoteComputer1 Connecting as UserForRemoteComputer1 PS > RemoteConnector -ComputerName RemoteComputer2 Connecting as UserForRemoteComputer2 PS > RemoteConnector -ComputerName RemoteComputer3 cmdlet RemoteConnector at command pipeline position 1 Supply values for the following parameters: Credential: (...)
For more information about working with hashtables in PowerShell, see Hashtables (Associative Arrays).
Invoke the command as a Job
to have PowerShell run it in the background:
PS > Start-Job { while($true) { Get-Random; Start-Sleep 5 } } -Name Sleeper
Id Name State HasMoreData Location
-- ---- ----- ----------- --------
1 Sleeper Running True localhost
PS > Receive-Job Sleeper
671032665
1862308704
PS > Stop-Job SleeperPowerShell’s job cmdlets provide a consistent way to create and
interact with background tasks. In the Solution, we use the Start-Job cmdlet to launch a background job on
the local computer. We give it the name of Sleeper, but otherwise we don’t customize much
of its execution environment.
In addition to allowing you to customize the job name, the
Start-Job cmdlet also lets you launch
the job under alternate user credentials or as a 32-bit process (if run
originally from a 64-bit process).
Once you have launched a job, you can use the other Job cmdlets to interact with it:
Get-JobGets all jobs associated with the current session. In addition, the
-Before,-After,-Newest, and-Stateparameters let you filter jobs based on their state or completion time.Wait-JobReceive-JobRetrieves any output the job has generated since the last call to
Receive-Job.Stop-JobStops a job.
Remove-Job
Note
In addition to the Start-Job
cmdlet, you can also use the -AsJob
parameter in many cmdlets to
have them perform their tasks in the background. Two of the most
useful examples are the Invoke-Command cmdlet (when operating
against remote computers) and the set of WMI-related cmdlets.
If your job generates an error, the Receive-Job cmdlet will display it to you when
you receive the results, as shown in Example 1-2. If you want to investigate these
errors further, the object returned by Get-Job exposes them through the Error property.
Example 1-2. Retrieving errors from a Job
PS > Start-Job -Name ErrorJob { Write-Error Error! }
Id Name State HasMoreData Location
-- ---- ----- ----------- --------
1 ErrorJob Running True localhost
PS > Receive-Job ErrorJob
Error!
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteError
Exception
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExc
eption,Microsoft.PowerShell.Commands.WriteErrorCommand
PS > $job = Get-Job ErrorJob
PS > $job | Format-List *
State : Completed
HasMoreData : False
StatusMessage :
Location : localhost
Command : Write-Error Error!
JobStateInfo : Completed
Finished : System.Threading.ManualResetEvent
InstanceId : 801e932c-5580-4c8b-af06-ddd1024840b7
Id : 1
Name : ErrorJob
ChildJobs : {Job2}
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
PS > $job.ChildJobs[0] | Format-List *
State : Completed
StatusMessage :
HasMoreData : False
Location : localhost
Runspace : System.Management.Automation.RemoteRunspace
Command : Write-Error Error!
JobStateInfo : Completed
Finished : System.Threading.ManualResetEvent
InstanceId : 60fa85da-448b-49ff-8116-6eae6c3f5006
Id : 2
Name : Job2
ChildJobs : {}
Output : {}
Error : {Microsoft.PowerShell.Commands.WriteErrorException,Microso
ft.PowerShell.Commands.WriteErrorCommand}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
PS > $job.ChildJobs[0].Error
Error!
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteError
Exception
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExc
eption,Microsoft.PowerShell.Commands.WriteErrorCommand
PS >As this example shows, jobs are sometimes containers for other
jobs, called child jobs. Jobs created through the
Start-Job cmdlet will always be child
jobs attached to a generic container. To access the errors returned by
these jobs, you instead access the errors in its first child job (called
child job number zero).
In addition to long-running jobs that execute under control of the current PowerShell session, you might want to register and control jobs that run on a schedule, or independently of the current PowerShell session. PowerShell has a handful of commands to let you work with scheduled jobs like this; for more information, see Manage Scheduled Tasks on a Computer.
As thrilling as our lives are, some days are reduced to running a command over and over and over. Did the files finish copying yet? Is the build finished? Is the site still up?
Usually, the answer to these questions comes from running a command, looking at its output, and then deciding whether it meets your criteria. And usually this means just waiting for the output to change, waiting for some text to appear, or waiting for some text to disappear.
Fortunately, Example 1-3 automates this tedious process for you.
Example 1-3. Watch-Command.ps1
##############################################################################
##
## Watch-Command
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Watches the result of a command invocation, alerting you when the output
either matches a specified string, lacks a specified string, or has simply
changed.
.EXAMPLE
PS > Watch-Command { Get-Process -Name Notepad | Measure } -UntilChanged
Monitors Notepad processes until you start or stop one.
.EXAMPLE
PS > Watch-Command { Get-Process -Name Notepad | Measure } -Until "Count : 1"
Monitors Notepad processes until there is exactly one open.
.EXAMPLE
PS > Watch-Command {
Get-Process -Name Notepad | Measure } -While 'Count : \d\s*\n'
Monitors Notepad processes while there are between 0 and 9 open
(once number after the colon).
#>
[CmdletBinding(DefaultParameterSetName = "Forever")]
param(
## The script block to invoke while monitoring
[Parameter(Mandatory = $true, Position = 0)]
[ScriptBlock] $ScriptBlock,
## The delay, in seconds, between monitoring attempts
[Parameter()]
[Double] $DelaySeconds = 1,
## Specifies that the alert sound should not be played
[Parameter()]
[Switch] $Quiet,
## Monitoring continues only while the output of the
## command remains the same.
[Parameter(ParameterSetName = "UntilChanged", Mandatory = $false)]
[Switch] $UntilChanged,
## The regular expression to search for. Monitoring continues
## until this expression is found.
[Parameter(ParameterSetName = "Until", Mandatory = $false)]
[String] $Until,
## The regular expression to search for. Monitoring continues
## until this expression is not found.
[Parameter(ParameterSetName = "While", Mandatory = $false)]
[String] $While
)
Set-StrictMode -Version 3
$initialOutput = ""
## Start a continuous loop
while($true)
{
## Run the provided script block
$r = & $ScriptBlock
## Clear the screen and display the results
Clear-Host
$ScriptBlock.ToString().Trim()
""
$textOutput = $r | Out-String
$textOutput
## Remember the initial output, if we haven't
## stored it yet
if(-not $initialOutput)
{
$initialOutput = $textOutput
}
## If we are just looking for any change,
## see if the text has changed.
if($UntilChanged)
{
if($initialOutput -ne $textOutput)
{
break
}
}
## If we need to ensure some text is found,
## break if we didn't find it.
if($While)
{
if($textOutput -notmatch $While)
{
break
}
}
## If we need to wait for some text to be found,
## break if we find it.
if($Until)
{
if($textOutput -match $Until)
{
break
}
}
## Delay
Start-Sleep -Seconds $DelaySeconds
}
## Notify the user
if(-not $Quiet)
{
[Console]::Beep(1000, 1000)
}For more information about running scripts, see Run Programs, Scripts, and Existing Tools.
Use the Register-TemporaryEvent command given in Create a Temporary Event Subscription to register for the event’s StateChanged event:
PS > $job = Start-Job -Name TenSecondSleep { Start-Sleep 10 }
PS > Register-TemporaryEvent $job StateChanged -Action {
[Console]::Beep(100,100)
Write-Host "Job #$($sender.Id) ($($sender.Name)) complete."
}
PS > Job #6 (TenSecondSleep) complete.
PS >When a job completes, it raises a StateChanged event to notify subscribers that
its state has changed. We can use PowerShell’s event handling cmdlets to
register for notifications about this event, but they are not geared
toward this type of one-time event handling. To solve that, we use the
Register-TemporaryEvent command given
in Create a Temporary Event Subscription.
In our example action block in the Solution, we simply emit a beep and write a message saying that the job is complete.
As another option, you can also update your prompt function to highlight jobs that are
complete but still have output you haven’t processed:
$psJobs = @(Get-Job -State Completed | ? { $_.HasMoreData })
if($psJobs.Count -gt 0) {
($psJobs | Out-String).Trim() | Write-Host -Fore Yellow }For more information about events and this type of automatic event handling, see Chapter 32.
You want to customize PowerShell’s interactive experience with a personalized prompt, aliases, and more.
When you want to customize aspects of PowerShell, place those
customizations in your personal profile script. PowerShell provides easy
access to this profile script by storing its location in the $profile variable.
Note
By default, PowerShell’s security policies prevent scripts (including your profile) from running. Once you begin writing scripts, though, you should configure this policy to something less restrictive. For information on how to configure your execution policy, see Enable Scripting Through an Execution Policy.
To create a new profile (and overwrite one if it already exists):
New-Item -type file -force $profile
To edit your profile (in the Integrated Scripting Environment):
ise $profile
Get-ChildItem $profile
Once you create a profile script, you can add a function
called prompt that returns a string.
PowerShell displays the output of this function as your command-line
prompt.
function prompt
{
"PS [$env:COMPUTERNAME] >"
}This example prompt displays your computer name, and looks like
PS [LEE-DESK] >.
You may also find it helpful to add aliases to your profile. Aliases let you refer to common commands by a name that you choose. Personal profile scripts let you automatically define aliases, functions, variables, or any other customizations that you might set interactively from the PowerShell prompt. Aliases are among the most common customizations, as they let you refer to PowerShell commands (and your own scripts) by a name that is easier to type.
Note
If you want to define an alias for a command but also need to modify the parameters to that command, then define a function instead. For more information, see Dynamically Compose Command Parameters.
For example:
Set-Alias new New-Object Set-Alias iexplore 'C:\Program Files\Internet Explorer\iexplore.exe'
Your changes will become effective once you save your profile and restart PowerShell. Alternatively, you can reload your profile immediately by running this command:
. $profile
Functions are also very common customizations, with the most
popular being the prompt
function.
The Solution discusses three techniques to make useful customizations to your PowerShell environment: aliases, functions, and a hand-tailored prompt. You can (and will often) apply these techniques at any time during your PowerShell session, but your profile script is the standard place to put customizations that you want to apply to every session.
Note
To remove an alias or function, use the Remove-Item cmdlet:
Remove-Item function:\MyCustomFunction Remove-Item alias:\new
Although the Prompt function
returns a simple string, you can also use the function for more complex
tasks. For example, many users update their console window title
(by changing the $host.UI.RawUI.WindowTitle variable) or use
the Write-Host cmdlet to output the
prompt in color. If your prompt function handles the screen output
itself, it still needs to return a string (for example, a single space)
to prevent PowerShell from using its default. If you don’t want this
extra space to appear in your prompt, add an extra space at the end of
your Write-Host command and return
the backspace ("`b") character, as shown in Example 1-4.
Example 1-4. An example PowerShell prompt
##############################################################################
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
Set-StrictMode -Version 3
function Prompt
{
$id = 1
$historyItem = Get-History -Count 1
if($historyItem)
{
$id = $historyItem.Id + 1
}
Write-Host -ForegroundColor DarkGray "`n[$(Get-Location)]"
Write-Host -NoNewLine "PS:$id > "
$host.UI.RawUI.WindowTitle = "$(Get-Location)"
"`b"
}In addition to showing the current location, this prompt also shows the ID for that command in your history. This lets you locate and invoke past commands with relative ease:
[C:\] PS:73 >5 * 5 25 [C:\] PS:74 >1 + 1 2 [C:\] PS:75 >Invoke-History 73 5 * 5 25 [C:\] PS:76 >
Although the profile referenced by $profile is the one you will almost always
want to use, PowerShell actually supports four separate profile scripts.
For further details on these scripts (along with other shell
customization options), see Common Customization Points.
Create a PSConsoleHostReadLine function. In that
function, process the user input and return the resulting command. Example 1-5 implements a somewhat ridiculous
Notepad-based user input mechanism:
Example 1-5. A Notepad-based user input mechanism
function PSConsoleHostReadLine
{
$inputFile = Join-Path $env:TEMP PSConsoleHostReadLine
Set-Content $inputFile "PS > "
## Notepad opens. Enter your command in it, save the file,
## and then exit.
notepad $inputFile | Out-Null
$userInput = Get-Content $inputFile
$resultingCommand = $userInput.Replace("PS >", "")
$resultingCommand
}When PowerShell first came on the scene, Unix folks were among the first to notice. They’d enjoyed a powerful shell and a vigorous heritage of automation for years—and “when I’m forced to use Windows, PowerShell rocks” is a phrase we’ve heard many times.
This natural uptake was no mistake. There are many on the team who come from a deep Unix background, and similarities to traditional Unix shells were intentional. When coming from a Unix background, though, we still hear the occasional grumble that tab completion feels weird. Ctrl-R doesn’t invoke history search? Tab cycles through matches, rather than lists them? Abhorrent!
In PowerShell versions 1 or 2, there was nothing you could reasonably do to address this. PowerShell reads its input from the console in what is known as Cooked Mode—where the Windows console subsystem handles all the keypresses, fancy F7 menus, and more. When you press Enter or Tab, PowerShell gets the text of what you have typed so far, but that’s it. There is no way for it to know that you had pressed the (Unix-like) Ctrl-R, Ctrl-A, Ctrl-E, or any other keys.
This issue has been resolved in PowerShell version 3 through the
PSConsoleHostReadLine function. When
you define this method in the PowerShell console host, PowerShell calls
that function instead of the Cooked Mode input functionality. And that’s
it—the rest is up to you. If you’d like to implement a custom input
method, the freedom (and responsibility) is all yours.
Note
A community implementation of a Bash-like PSConsoleHostReadLine function is available
here.
For more information about handling keypresses and other forms of user input, see Chapter 13.
Assign a script block to one or all of
the PreCommandLookupAction, PostCommandLookupAction, or CommandNotFoundAction properties of $executionContext.SessionState.InvokeCommand. Example 1-6 enables easy parent directory
navigation when you type multiple dots.
Example 1-6. Enabling easy parent path navigation through CommandNotFoundAction
$executionContext.SessionState.InvokeCommand.CommandNotFoundAction = {
param($CommandName, $CommandLookupEventArgs)
## If the command is only dots
if($CommandName -match '^\.+$')
{
## Associate a new command that should be invoked instead
$CommandLookupEventArgs.CommandScriptBlock = {
## Count the number of dots, and run "Set-Location .." one
## less time.
for($counter = 0; $counter -lt $CommandName.Length - 1; $counter++)
{
Set-Location ..
}
## We call GetNewClosure() so that the reference to $CommandName can
## be used in the new command.
}.GetNewClosure()
}
}
PS C:\Users\Lee> cd $pshome
PS C:\Windows\System32\WindowsPowerShell\v1.0> ....
PS C:\Windows>When you invoke a command in PowerShell, the engine goes through three distinct phases:
Retrieve the text of the command.
Find the command for that text.
Invoke the command that was found.
In PowerShell version 3, the $executionContext.SessionState.InvokeCommand
property now lets you override any of these stages with script blocks to
intercept any or all of the PreCommandLookupAction, PostCommandLookupAction, or CommandNotFoundAction
stages.
Each script block receives two parameters: the command name, and
an object (CommandLookupEventArgs) to
control the command lookup behavior. If your handler assigns a script block to the CommandScriptBlock property of the CommandLookupEventArgs or assigns a CommandInfo to the Command property of the CommandLookupEventArgs, PowerShell will use that script block or
command, respectively. If your script
block sets the StopSearch property to
true, PowerShell will do no further
command resolution.
PowerShell invokes the PreCommandLookupAction script block when it
knows the name of a command (i.e., Get-Process) but hasn’t yet looked for the
command itself. You can override this action if you want to react
primarily based on the text of the command name or want to preempt
PowerShell’s regular command or alias resolution. For example, Example 1-7 demonstrates a PreCommandLookupAction that looks for commands
with an asterisk before their name. When it sees one, it enables the
-Verbose parameter.
Example 1-7. Customizing the PreCommandLookupAction
$executionContext.SessionState.InvokeCommand.PreCommandLookupAction = {
param($CommandName, $CommandLookupEventArgs)
## If the command name starts with an asterisk, then
## enable its Verbose parameter
if($CommandName -match "\*")
{
## Remove the leading asterisk
$NewCommandName = $CommandName -replace '\*',''
## Create a new script block that invokes the actual command,
## passes along all original arguments, and adds in the -Verbose
## parameter
$CommandLookupEventArgs.CommandScriptBlock = {
& $NewCommandName @args -Verbose
## We call GetNewClosure() so that the reference to $NewCommandName
## can be used in the new command.
}.GetNewClosure()
}
}
PS > dir > 1.txt
PS > dir > 2.txt
PS > del 1.txt
PS > *del 2.txt
VERBOSE: Performing operation "Remove file" on Target "C:\temp\tempfolder\2.txt".After PowerShell executes the PreCommandLookupAction (if one exists and
doesn’t return a command), it goes through its regular command
resolution. If it finds a command, it invokes the script block associated
with the PostCommandLookupAction. You
can override this action if you want to react primarily to a command
that is just about to be invoked. Example 1-8 demonstrates a PostCommandLookupAction that tallies the
commands you use most frequently.
Example 1-8. Customizing the PostCommandLookupAction
$executionContext.SessionState.InvokeCommand.PostCommandLookupAction = {
param($CommandName, $CommandLookupEventArgs)
## Stores a hashtable of the commands we use most frequently
if(-not (Test-Path variable:\CommandCount))
{
$global:CommandCount = @{}
}
## If it was launched by us (rather than as an internal helper
## command), record its invocation.
if($CommandLookupEventArgs.CommandOrigin -eq "Runspace")
{
$commandCount[$CommandName] = 1 + $commandCount[$CommandName]
}
}
PS > Get-Variable commandCount
PS > Get-Process -id $pid
PS > Get-Process -id $pid
PS > $commandCount
Name Value
---- -----
Out-Default 4
Get-Variable 1
prompt 4
Get-Process 2If command resolution is unsuccessful, PowerShell invokes the
CommandNotFoundAction script block if
one exists. At its simplest, you can override this action if you want to
recover from or override PowerShell’s error behavior when it cannot find
a command.
As a more advanced application, the CommandNotFoundAction lets you write
PowerShell extensions that alter their behavior based on the
form of the name, rather than the arguments passed
to it. For example, you might want to automatically launch URLs just by
typing them or navigate around providers just by typing relative path
locations.
The Solution gives an example of implementing this type of
handler. While dynamic relative path navigation is not a built-in
feature of PowerShell, it is possible to get a very reasonable
alternative by intercepting the CommandNotFoundAction. If we see a missing
command that has a pattern we want to handle (a series of dots), we
return a script block that does the appropriate relative path navigation.
You want to accomplish a task in PowerShell but don’t know the command or cmdlet to accomplish that task.
Use the Get-Command cmdlet to search for and
investigate commands.
To get the summary information about a specific command, specify the command name as an argument:
Get-Command CommandNameTo get the detailed information about a specific command,
pipe the output of Get-Command to the
Format-List cmdlet:
Get-Command CommandName | Format-ListTo search for all commands with a name that contains text, surround the text with asterisk characters:
Get-Command *text*To search for all commands that use the Get verb, supply Get to the -Verb parameter:
Get-Command -Verb Get
To search for all commands that act on a service, use Service as the value of the -Noun
parameter:
Get-Command -Noun ServiceOne of the benefits that PowerShell provides administrators
is the consistency of its command names. All PowerShell commands (called
cmdlets) follow a regular
Verb-Noun pattern—for
example, Get-Process, Get-EventLog, and Set-Location. The verbs come from a relatively
small set of standard verbs (as listed in Appendix J) and describe what action the
cmdlet takes. The nouns are specific to the cmdlet and describe what the
cmdlet acts on.
Knowing this philosophy, you can easily learn to work with groups
of cmdlets. If you want to start a service on the local machine, the
standard verb for that is Start. A
good guess would be to first try Start-Service (which in this case would be
correct), but typing Get-Command -Verb
Start would also be an effective way to see what things you
can start. Going the other way, you can see what actions are supported
on services by typing Get-Command -Noun
Service.
When you use the Get-Command
cmdlet, PowerShell returns results from the list of all commands
available on your system. If you’d instead like to search just commands
from modules that you’ve loaded either
explicitly or through autoloading, use the -ListImported
parameter. For more information about PowerShell’s autoloading
of commands, see Extend Your Shell with Additional Commands.
See Get Help on a Command for a way to list all commands along with a brief description of what they do.
The Get-Command cmdlet is one
of the three commands you will use most commonly as you explore Windows
PowerShell. The other two commands are Get-Help and Get-Member.
There is one important point to keep in mind when it comes to
looking for a PowerShell command to accomplish a particular task. Many
times, that PowerShell command does not exist, because the task is best
accomplished the same way it always was—for example, ipconfig.exe to get IP configuration
information, netstat.exe to list
protocol statistics and current TCP/IP network connections, and many
more.
For more information about the Get-Command cmdlet, type Get-Help
Get-Command.
The command that provides help and usage
information about a command is called Get-Help. It supports several different views
of the help information, depending on your needs.
To get the summary of help information for a specific command,
provide the command’s name as an argument to the Get-Help cmdlet. This primarily includes its
synopsis, syntax, and detailed description:
Get-Help CommandNameor:
CommandName -?To get the detailed help information for a specific command,
supply the -Detailed flag to the
Get-Help cmdlet. In addition to the
summary view, this also includes its parameter descriptions and
examples:
Get-Help CommandName -DetailedTo get the full help information for a specific command, supply
the -Full flag to the Get-Help cmdlet. In addition to the detailed
view, this also includes its full parameter descriptions and additional
notes:
Get-Help CommandName -FullTo get only the examples for a specific command, supply the
-Examples flag to the Get-Help cmdlet:
Get-Help CommandName -ExamplesTo retrieve the most up-to-date online version of a
command’s help topic, supply the -Online flag to
the Get-Help cmdlet:
Get-Help CommandName -OnlineTo view a searchable, graphical view of a help topic, use the
-ShowWindow parameter:
Get-Help CommandName -ShowWindowTo find all help topics that contain a given keyword, provide that
keyword as an argument to the Get-Help cmdlet. If the keyword isn’t also the
name of a specific help topic, this returns all help topics that contain
the keyword, including its name, category, and synopsis:
Get-Help KeywordThe Get-Help
cmdlet is the primary way to interact with the help system in
PowerShell. Like the Get-Command
cmdlet, the Get-Help cmdlet supports
wildcards. If you want to list all commands that have help content that
matches a certain pattern (for example, *process*),
you can simply type Get-Help
*process*.
If the pattern matches only a single command, PowerShell displays the help for that command. Although command wildcarding and keyword searching is a helpful way to search PowerShell help, see Program: Search Help for Text for a script that lets you search the help content for a specified pattern.
While there are thousands of pages of custom-written help
content at your disposal, PowerShell by default includes only
information that it can automatically generate from the information
contained in the commands themselves: names, parameters, syntax, and
parameter defaults. You need to update your help content to retrieve the
rest. The first time you run Get-Help
as an administrator on a system, PowerShell offers to download this
updated help content:
PS > Get-Help Get-Process Do you want to run Update-Help? The Update-Help cmdlet downloads the newest Help files for Windows PowerShell modules and installs them on your computer. For more details, see the help topic at http://go.microsoft.com/fwlink/?LinkId=210614. [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"):
Answer Y to this prompt, and
PowerShell automatically downloads and installs the most recent help
content for all modules on your system. For more information on
updatable help, see Update System Help Content.
If you’d like to generate a list of all cmdlets and aliases (along with their brief synopses), run the following command:
Get-Help * -Category Cmdlet | Select-Object Name,Synopsis | Format-Table -Auto
In addition to console-based help, PowerShell also offers online access to its help content. The Solution demonstrates how to quickly access online help content.
The Get-Help cmdlet is one of
the three commands you will use most commonly as you explore Windows
PowerShell. The other two commands are Get-Command and Get-Member.
For more information about the Get-Help cmdlet, type Get-Help
Get-Help.
Run the Update-Help
command. To retrieve help from a local path, use the -SourcePath cmdlet
parameter:
Update-Help
or:
Update-Help -SourcePath \\helpserver\helpOne of PowerShell’s greatest strengths is the
incredible detail of its help content. Counting only the help content
and about_* topics that describe core
functionality, PowerShell’s help includes approximately half a million
words and would span 1,200 pages if printed.
The challenge that every version of PowerShell has been forced to deal with is that this help content is written at the same time as PowerShell itself. Given that its goal is to help the user, the content that’s ready by the time a version of PowerShell releases is a best-effort estimate of what users will need help with.
As users get their hands on PowerShell, they start to have
questions. Some of these are addressed by the help topics, while some of
them aren’t. Sometimes the help is simply incorrect due to a product
change during the release. Before PowerShell version 3, resolving these
issues meant waiting for the next release of Windows or relying solely
on Get-Help’s -Online parameter. To address this, PowerShell
version 3 introduces updatable help.
It’s not only possible to update help, but in fact the Update-Help command is the
only way to get help on your system. Out of the
box, PowerShell provides an experience derived solely from what is built
into the commands themselves: name, syntax, parameters, and default
values.
The first time you run Get-Help as an administrator on a system,
PowerShell offers to download updated help content:
PS > Get-Help Get-Process Do you want to run Update-Help? The Update-Help cmdlet downloads the newest Help files for Windows PowerShell modules and installs them on your computer. For more details, see the help topic at http://go.microsoft.com/fwlink/?LinkId=210614. [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"):
Answer Y to this prompt, and
PowerShell automatically downloads and installs the most recent help
content for all modules on your system.
Note
If you are building a system image and want to prevent this
prompt from ever appearing, set the registry key HKLM:\Software\Microsoft\PowerShell\DisablePromptToUpdateHelp
to 1.
In addition to the prompt-driven experience, you can call the
Update-Help cmdlet directly.
Both experiences look at each module on your system, comparing the
help you have for that module with the latest version online. For in-box
modules, PowerShell uses download.microsoft.com to retrieve updated
help content. Other modules that you download from the Internet can use
the HelpInfoUri module key to support
their own updatable help.
By default, the Update-Help
command retrieves its content from the Internet. If you want to update
help on a machine not connected to the Internet, you can use the -SourcePath
parameter of the Update-Help cmdlet.
This path represents a directory or UNC path where PowerShell
should look for updated help content. To populate this content, first
use the Save-Help cmdlet to download
the files, and then copy them to the source location.
For more information about PowerShell help, see Get Help on a Command.
Both the Get-Command and
Get-Help cmdlets let you search for
command names that match a given pattern. However, when you don’t know
exactly what portions of a command name you are looking for, you will more
often have success searching through the help content
for an answer. On Unix systems, this command is called Apropos.
The Get-Help cmdlet
automatically searches the help database for keyword references when it
can’t find a help topic for the argument you supply. In addition to that,
you might want to extend this even further to search for text
patterns or even help topics that talk
about existing help topics. PowerShell’s help
facilities support a version of wildcarded content searches, but don’t
support full regular expressions.
That doesn’t need to stop us, though, as we can write the functionality ourselves.
To run this program, supply a search string to the Search-Help script (given in Example 1-9). The search string can be either simple text
or a regular expression. The script then displays the name and synopsis of
all help topics that match. To see the help content for that topic, use
the Get-Help cmdlet.
Example 1-9. Search-Help.ps1
##############################################################################
##
## Search-Help
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Search the PowerShell help documentation for a given keyword or regular
expression. For simple keyword searches in PowerShell version two or three,
simply use "Get-Help <keyword>"
.EXAMPLE
PS > Search-Help hashtable
Searches help for the term 'hashtable'
.EXAMPLE
PS > Search-Help "(datetime|ticks)"
Searches help for the term datetime or ticks, using the regular expression
syntax.
#>
param(
## The pattern to search for
[Parameter(Mandatory = $true)]
$Pattern
)
$helpNames = $(Get-Help * | Where-Object { $_.Category -ne "Alias" })
## Go through all of the help topics
foreach($helpTopic in $helpNames)
{
## Get their text content, and
$content = Get-Help -Full $helpTopic.Name | Out-String
if($content -match "(.{0,30}$pattern.{0,30})")
{
$helpTopic | Add-Member NoteProperty Match $matches[0].Trim()
$helpTopic | Select-Object Name,Match
}
}For more information about running scripts, see Run Programs, Scripts, and Existing Tools.
Both Windows and PowerShell offer several ways to launch PowerShell in a specific location:
Explorer’s address bar
PowerShell’s command-line arguments
Community extensions
If you are browsing the filesystem with Windows Explorer,
typing PowerShell into the address
bar launches PowerShell in that location (as shown in Figure 1-1).
Additionally, Windows 8 offers an Open Windows PowerShell option directly from the File menu, as shown in Figure 1-2).
For another way to launch PowerShell from Windows Explorer, several members of the PowerShell community have written power toys and Windows Explorer extensions that provide a “Launch PowerShell Here” option when you right-click on a folder from Windows Explorer. An Internet search for “PowerShell Here” turns up several.
If you aren’t browsing the desired folder with Windows Explorer,
you can use Start→Run (or any other
means of launching an application) to launch PowerShell at a specific
location. For that, use PowerShell’s -NoExit parameter, along with the implied
-Command parameter. In the -Command parameter, call the Set-Location cmdlet to initially move
to your desired location.
PowerShell -NoExit Set-Location 'C:\Program Files'
You want to invoke a PowerShell command or script from a batch file, a logon script, a scheduled task, or any other non-PowerShell application.
To invoke a PowerShell command, use the -Command parameter:
PowerShell -Command Get-Process; Read-Host
To launch a PowerShell script, use the -File parameter:
PowerShell -File 'full path to script' argumentsFor example:
PowerShell -File 'c:\shared scripts\Get-Report.ps1' Hello World
By default, any arguments to
PowerShell.exe get interpreted as commands to run.
PowerShell runs the command as
though you had typed it in the interactive shell, and then exits. You
can customize this behavior by supplying other parameters to
PowerShell.exe, such as -NoExit, -NoProfile, and more.
Note
If you are the author of a program that needs to run PowerShell scripts or commands, PowerShell lets you call these scripts and commands much more easily than calling its command-line interface. For more information about this approach, see Add PowerShell Scripting to Your Own Program.
Since launching a script is so common, PowerShell provides the
-File parameter to eliminate the
complexities that arise from having to invoke a script from the -Command parameter. This technique
lets you invoke a PowerShell script as the target of a logon script,
advanced file association, scheduled task, and more.
Note
When PowerShell detects that its input or output streams have
been redirected, it suppresses any prompts that it might normally
display. If you want to host an interactive PowerShell prompt inside
another application (such as Emacs), use - as the argument for the -File parameter. In PowerShell (as with
traditional Unix shells), this implies “taken from standard
input.”
powershell -File -
If the script is for background automation or a scheduled task, these scripts can sometimes interfere with (or become influenced by) the user’s environment. For these situations, three parameters come in handy:
-NoProfileRuns the command or script without loading user profile scripts. This makes the script launch faster, but it primarily prevents user preferences (e.g., aliases and preference variables) from interfering with the script’s working environment.
-WindowStyleRuns the command or script with the specified window style—most commonly
Hidden. When run with a window style ofHidden, PowerShell hides its main window immediately. For more ways to control the window style from within PowerShell, see Launch a Process.-ExecutionPolicyRuns the command or script with a specified execution policy applied only to this instance of PowerShell. This lets you write PowerShell scripts to manage a system without having to change the system-wide execution policy. For more information about scoped execution policies, see Enable Scripting Through an Execution Policy.
If the arguments to the -Command parameter become complex, special
character handling in the application calling PowerShell (such as
cmd.exe) might interfere with the command you want to send to PowerShell.
For this situation, PowerShell supports an EncodedCommand parameter: a Base64-encoded
representation of the Unicode string you want to run. Example 1-10 demonstrates how
to convert a string containing PowerShell commands to a Base64-encoded
form.
Example 1-10. Converting PowerShell commands into a Base64-encoded form
$commands = '1..10 | % { "PowerShell Rocks" }'
$bytes = [System.Text.Encoding]::Unicode.GetBytes($commands)
$encodedString = [Convert]::ToBase64String($bytes)Once you have the encoded string, you can use it as the value of
the EncodedCommand parameter, as
shown in Example 1-11.
Example 1-11. Launching PowerShell with an encoded command from cmd.exe
Microsoft Windows [Version 6.0.6000] Copyright (c) 2006 Microsoft Corporation. All rights reserved. C:\Users\Lee>PowerShell -EncodedCommand MQAuAC4AMQAwACAAfAAgACUAIAB7ACAAIgBQAG8A dwBlAHIAUwBoAGUAbABsACAAUgBvAGMAawBzACIAIAB9AA== PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks PowerShell Rocks
For more information about running scripts, see Run Programs, Scripts, and Existing Tools.
You want to customize how PowerShell reacts to presses of the Tab key (and additionally, Ctrl-Space in the case of IntelliSense in the Integrated Scripting Environment).
Create a custom function called TabExpansion2. PowerShell invokes this
function when you press Tab, or when it invokes IntelliSense in the
Integrated Scripting Environment.
When you press Tab, PowerShell invokes a
facility known as tab expansion: replacing what
you’ve typed so far with an expanded version of that (if any apply.) For
example, if you type Set-Location C:\
and then press Tab, PowerShell starts cycling through directories under
C:\ for you to navigate into.
The features offered by PowerShell’s built-in tab expansion are quite rich, as shown in Table 1-2.
Table 1-2. Tab expansion features in Windows PowerShell
If you want to extend PowerShell’s tab expansion capabilities,
define a function called TabExpansion2. You can add this to your
PowerShell profile directly, or dot-source it from your profile. Example 1-12 demonstrates an example custom tab
expansion function that extends the functionality already built into
PowerShell.
Example 1-12. A sample implementation of TabExpansion2
##############################################################################
##
## TabExpansion2
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
function TabExpansion2
{
[CmdletBinding(DefaultParameterSetName = 'ScriptInputSet')]
Param(
[Parameter(ParameterSetName = 'ScriptInputSet', Mandatory = $true,
Position = 0)]
[string] $inputScript,
[Parameter(ParameterSetName = 'ScriptInputSet', Mandatory = $true,
Position = 1)]
[int] $cursorColumn,
[Parameter(ParameterSetName = 'AstInputSet', Mandatory = $true,
Position = 0)]
[System.Management.Automation.Language.Ast] $ast,
[Parameter(ParameterSetName = 'AstInputSet', Mandatory = $true,
Position = 1)]
[System.Management.Automation.Language.Token[]] $tokens,
[Parameter(ParameterSetName = 'AstInputSet', Mandatory = $true,
Position = 2)]
[System.Management.Automation.Language.IScriptPosition] $positionOfCursor,
[Parameter(ParameterSetName = 'ScriptInputSet', Position = 2)]
[Parameter(ParameterSetName = 'AstInputSet', Position = 3)]
[Hashtable] $options = $null
)
End
{
## Create a new 'Options' hashtable if one has not been supplied.
## In this hashtable, you can add keys for the following options, using
## $true or $false for their values:
##
## IgnoreHiddenShares - Ignore hidden UNC shares (such as \\COMPUTER\ADMIN$)
## RelativePaths - When expanding filenames and paths, $true forces PowerShell
## to replace paths with relative paths. When $false, forces PowerShell to
## replace them with absolute paths. By default, PowerShell makes this
## decision based on what you had typed so far before invoking tab completion.
## LiteralPaths - Prevents PowerShell from replacing special file characters
## (such as square brackets and back-ticks) with their escaped equivalent.
if(-not $options) { $options = @{} }
## Demonstrate some custom tab expansion completers for parameters.
## This is a hashtable of parameter names (and optionally cmdlet names)
## that we add to the $options hashtable.
##
## When PowerShell evaluates the script block, $args gets the
## following: command name, parameter, word being completed,
## AST of the command being completed, and currently bound arguments.
$options["CustomArgumentCompleters"] = @{
"Get-ChildItem:Filter" = { "*.ps1","*.txt","*.doc" }
"ComputerName" = { "ComputerName1","ComputerName2","ComputerName3" }
}
## Also define a completer for a native executable.
## When PowerShell evaluates the script block, $args gets the
## word being completed, and AST of the command being completed.
$options["NativeArgumentCompleters"] = @{
"attrib" = { "+R","+H","+S" }
}
## Define a "quick completions" list that we'll cycle through
## when the user types '!!' followed by TAB.
$quickCompletions = @(
'Get-Process -Name PowerShell | ? Id -ne $pid | Stop-Process',
'Set-Location $pshome',
('$errors = $error | % { $_.InvocationInfo.Line }; Get-History | ' +
' ? { $_.CommandLine -notin $errors }')
)
## First, check the built-in tab completion results
$result = $null
if ($psCmdlet.ParameterSetName -eq 'ScriptInputSet')
{
$result = [Management.Automation.CommandCompletion]::CompleteInput(
<#inputScript#> $inputScript,
<#cursorColumn#> $cursorColumn,
<#options#> $options)
}
else
{
$result = [Management.Automation.CommandCompletion]::CompleteInput(
<#ast#> $ast,
<#tokens#> $tokens,
<#positionOfCursor#> $positionOfCursor,
<#options#> $options)
}
## If we didn't get a result
if($result.CompletionMatches.Count -eq 0)
{
## If this was done at the command-line or in a remote session,
## create an AST out of the input
if ($psCmdlet.ParameterSetName -eq 'ScriptInputSet')
{
$ast = [System.Management.Automation.Language.Parser]::ParseInput(
$inputScript, [ref]$tokens, [ref]$null)
}
## In this simple example, look at the text being supplied.
## We could do advanced analysis of the AST here if we wanted,
## but in this case just use its text. We use a regular expression
## to check if the text started with two exclamations, and then
## use a match group to retain the rest.
$text = $ast.Extent.Text
if($text -match '^!!(.*)')
{
## Extract the rest of the text from the regular expression
## match group.
$currentCompletionText = $matches[1].Trim()
## Go through each of our quick completions and add them to
## our completion results. The arguments to the completion results
## are the text to be used in tab completion, a potentially shorter
## version to use for display (i.e., IntelliSense in the ISE),
## the type of match, and a potentially more verbose description to
## be used as a tool tip.
$quickCompletions |
Where-Object { $_ -match $currentCompletionText } |
Foreach-Object { $result.CompletionMatches.Add(
(New-Object Management.Automation.CompletionResult $_,$_,"Text",$_) )
}
}
}
return $result
}
}In interactive use, full cmdlet names (such as Get-ChildItem) are cumbersome and slow to type.
Although aliases are much more efficient, it takes a while to discover
them. To learn aliases more easily, you can modify your prompt to remind
you of the shorter version of any aliased commands that you use.
This involves two steps:
Add the program
Get-AliasSuggestion.ps1, shown in Example 1-13, to your tools directory or another directory.Example 1-13. Get-AliasSuggestion.ps1
############################################################################## ## ## Get-AliasSuggestion ## ## From Windows PowerShell Cookbook (O'Reilly) ## by Lee Holmes (http://www.leeholmes.com/guide) ## ############################################################################## <# .SYNOPSIS Get an alias suggestion from the full text of the last command. Intended to be added to your prompt function to help learn aliases for commands. .EXAMPLE PS > Get-AliasSuggestion Remove-ItemProperty Suggestion: An alias for Remove-ItemProperty is rp #> param( ## The full text of the last command $LastCommand ) Set-StrictMode -Version 3 $helpMatches = @() ## Find all of the commands in their last input $tokens = [Management.Automation.PSParser]::Tokenize( $lastCommand, [ref] $null) $commands = $tokens | Where-Object { $_.Type -eq "Command" } ## Go through each command foreach($command in $commands) { ## Get the alias suggestions foreach($alias in Get-Alias -Definition $command.Content) { $helpMatches += "Suggestion: An alias for " + "$($alias.Definition) is $($alias.Name)" } } $helpMatchesAdd the text from Example 1-14 to the
Promptfunction in your profile. If you do not yet have aPromptfunction, see Customize Your Shell, Profile, and Prompt to learn how to add one.Example 1-14. A useful prompt to teach you aliases for common commands
function Prompt { ## Get the last item from the history $historyItem = Get-History -Count 1 ## If there were any history items if($historyItem) { ## Get the training suggestion for that item $suggestions = @(Get-AliasSuggestion $historyItem.CommandLine) ## If there were any suggestions if($suggestions) { ## For each suggestion, write it to the screen foreach($aliasSuggestion in $suggestions) { Write-Host "$aliasSuggestion" } Write-Host "" } } ## Rest of prompt goes here "PS [$env:COMPUTERNAME] >" }
For more information about running scripts, see Run Programs, Scripts, and Existing Tools.
Use the Get-ParameterAlias
script, as shown in Example 1-15, to return
all aliases for parameters used by the previous command in your session
history.
Example 1-15. Get-ParameterAlias.ps1
##############################################################################
##
## Get-ParameterAlias
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Looks in the session history, and returns any aliases that apply to
parameters of commands that were used.
.EXAMPLE
PS > dir -ErrorAction SilentlyContinue
PS > Get-ParameterAlias
An alias for the 'ErrorAction' parameter of 'dir' is ea
#>
Set-StrictMode -Version 3
## Get the last item from their session history
$history = Get-History -Count 1
if(-not $history)
{
return
}
## And extract the actual command line they typed
$lastCommand = $history.CommandLine
## Use the Tokenizer API to determine which portions represent
## commands and parameters to those commands
$tokens = [System.Management.Automation.PsParser]::Tokenize(
$lastCommand, [ref] $null)
$currentCommand = $null
## Now go through each resulting token
foreach($token in $tokens)
{
## If we've found a new command, store that.
if($token.Type -eq "Command")
{
$currentCommand = $token.Content
}
## If we've found a command parameter, start looking for aliases
if(($token.Type -eq "CommandParameter") -and ($currentCommand))
{
## Remove the leading "-" from the parameter
$currentParameter = $token.Content.TrimStart("-")
## Determine all of the parameters for the current command.
(Get-Command $currentCommand).Parameters.GetEnumerator() |
## For parameters that start with the current parameter name,
Where-Object { $_.Key -like "$currentParameter*" } |
## return all of the aliases that apply. We use "starts with"
## because the user might have typed a shortened form of
## the parameter name.
Foreach-Object {
$_.Value.Aliases | Foreach-Object {
"Suggestion: An alias for the '$currentParameter' " +
"parameter of '$currentCommand' is '$_'"
}
}
}
}To make it easy to type command parameters,
PowerShell lets you type only as much of the command parameter as is
required to disambiguate it from other parameters of that command. In
addition to shortening implicitly supported by the shell, cmdlet authors
can also define explicit aliases for their parameters—for example,
CN as a short form for ComputerName.
While helpful, these aliases are difficult to discover.
If you want to see the aliases for a specific command, you can
access its Parameters
collection:
PS > (Get-Command New-TimeSpan).Parameters.Values | Select Name,Aliases
Name Aliases
---- -------
Start {LastWriteTime}
End {}
Days {}
Hours {}
Minutes {}
Seconds {}
Verbose {vb}
Debug {db}
ErrorAction {ea}
WarningAction {wa}
ErrorVariable {ev}
WarningVariable {wv}
OutVariable {ov}
OutBuffer {ob}If you want to learn any aliases for parameters in your previous
command, simply run Get-ParameterAlias.ps1. To make PowerShell do
this automatically, add a call to Get-ParameterAlias.ps1 in your prompt.
This script builds on two main features: PowerShell’s
Tokenizer API, and the rich information returned by
the Get-Command cmdlet. PowerShell’s
Tokenizer API examines its input and returns PowerShell’s interpretation
of the input: commands, parameters, parameter values, operators, and
more. Like the rich output produced by most of PowerShell’s commands, Get-Command returns information about a
command’s parameters, parameter sets, output type (if specified), and
more.
For more information about the Tokenizer API, see Parse and Interpret PowerShell Scripts.
After working in the shell for a while, you want to invoke commands from your history, view your command history, and save your command history.
The shortcuts given in Customize Your Shell, Profile, and Prompt let you manage your history, but PowerShell offers several features to help you work with your console in even more detail.
To get the most recent commands from your session, use the
Get-History cmdlet (or its alias of
h):
Get-History
To rerun a specific command from your session history,
provide its ID to the Invoke-History
cmdlet (or its alias of ihy):
Invoke-History IDTo increase (or limit) the number of commands stored in your
session history, assign a new value to the $MaximumHistoryCount variable:
$MaximumHistoryCount = CountTo save your command history to a file, pipe the output of
Get-History to the Export-CliXml cmdlet:
Get-History | Export-CliXml FilenameTo add a previously saved command history to your current
session history, call the Import-CliXml cmdlet and then pipe that output
to the Add-History cmdlet:
Import-CliXml Filename | Add-HistoryTo clear all commands from your session history, use the
Clear-History cmdlet:
Clear-History
Unlike the console history hotkeys discussed in Customize Your Shell, Profile, and Prompt, the Get-History cmdlet produces rich objects that
represent information about items in your history. Each object contains
that item’s ID, command line, start of execution time, and end of
execution time.
Once you know the ID of a history item (as shown in the output
of Get-History), you can pass it to
Invoke-History to execute that
command again. The example prompt function shown in Customize Your Shell, Profile, and Prompt makes working with prior history items
easy, as the prompt for each command includes the history ID that will
represent it.
Note
You can easily see how long a series of commands took to invoke
by looking at the StartExecutionTime and EndExecutionTime properties. This is a great
way to get a handle on exactly how little time it took to come up with
the commands that just saved you hours of manual work:
PS C:\> Get-History 65,66 | Format-Table * Id CommandLine StartExecutionTime EndExecutionTime -- ----------- ------------------ ---------------- 65 dir 10/13/2012 2:06:05 PM 10/13/2012 2:06:05 PM 66 Start-Sleep -Seconds 45 10/13/2012 2:06:15 PM 10/13/2012 2:07:00 PM
IDs provided by the Get-History
cmdlet differ from the IDs given by the Windows console common history
hotkeys (such as F7), because their history management techniques
differ.
By default, PowerShell stores the last 4,096 entries of your
command history. If you want to raise or lower this amount, set the
$MaximumHistoryCount variable to the
size you desire. To make this change permanent, set the variable in your
PowerShell profile script.
By far, the most useful feature of PowerShell’s command history is for reviewing ad hoc experimentation and capturing it in a script that you can then use over and over. For an overview of that process (and a script that helps to automate it), see Program: Create Scripts from Your Session History.
After interactively experimenting at the command line for a while to solve a multistep task, you’ll often want to keep or share the exact steps you used to eventually solve the problem. The script smiles at you from your history buffer, but it is unfortunately surrounded by many more commands that you don’t want to keep.
Note
For an example of using the Out-GridView cmdlet to do this graphically,
see Program: Interactively Filter Lists of Objects.
To solve this problem, use the Get-History cmdlet to view the recent commands
that you’ve typed. Then, call Copy-History with the IDs of the commands you
want to keep, as shown in Example 1-16.
Example 1-16. Copy-History.ps1
##############################################################################
##
## Copy-History
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Copies selected commands from the history buffer into the clipboard as a script.
.EXAMPLE
PS > Copy-History
Copies the entire contents of the history buffer into the clipboard.
.EXAMPLE
PS > Copy-History -5
Copies the last five commands into the clipboard.
.EXAMPLE
PS > Copy-History 2,5,8,4
Copies commands 2,5,8, and 4.
.EXAMPLE
PS > Copy-History (1..10+5+6)
Copies commands 1 through 10, then 5, then 6, using PowerShell's array
slicing syntax.
#>
param(
## The range of history IDs to copy
[int[]] $Range
)
Set-StrictMode -Version 3
$history = @()
## If they haven't specified a range, assume it's everything
if((-not $range) -or ($range.Count -eq 0))
{
$history = @(Get-History -Count ([Int16]::MaxValue))
}
## If it's a negative number, copy only that many
elseif(($range.Count -eq 1) -and ($range[0] -lt 0))
{
$count = [Math]::Abs($range[0])
$history = (Get-History -Count $count)
}
## Otherwise, go through each history ID in the given range
## and add it to our history list.
else
{
foreach($commandId in $range)
{
if($commandId -eq -1) { $history += Get-History -Count 1 }
else { $history += Get-History -Id $commandId }
}
}
## Finally, export the history to the clipboard.
$history | Foreach-Object { $_.CommandLine } | clip.exeFor more information about running scripts, see Run Programs, Scripts, and Existing Tools.
Use the Invoke-History cmdlet (or its ihy alias) to invoke a specific command by its
ID:
Invoke-History IDTo search through your history for a command containing
text:
PS > #text<Tab>To repopulate your command with the text of a previous command by
its ID:
PS > #ID<Tab>Once you’ve had your shell open for a while, your history buffer quickly fills with useful commands. The history management hotkeys described in Customize Your Shell, Profile, and Prompt show one way to navigate your history, but this type of history navigation works only for command lines you’ve typed in that specific session. If you keep a persistent command history (as shown in Save State Between Sessions), these shortcuts do not apply.
The Invoke-History cmdlet
illustrates the simplest example of working with your command history.
Given a specific history ID (perhaps shown in your prompt function),
calling Invoke-History with that ID
will run that command again. For more information about this technique,
see Customize Your Shell, Profile, and Prompt.
As part of its tab-completion support, PowerShell gives you
easy access to previous commands as well. If you prefix your command
with the # character, tab completion
takes one of two approaches:
- ID completion
If you type a number, tab completion finds the entry in your command history with that ID, and then replaces your command line with the text of that history entry. This is especially useful when you want to slightly modify a previous history entry, since
Invoke-Historyby itself doesn’t support that.- Pattern completion
If you type anything else, tab completion searches for entries in your command history that contain that text. Under the hood, PowerShell uses the
-likeoperator to match your command entries, so you can use all of the wildcard characters supported by that operator. For more information on searching text for patterns, see Search a String for Text or a Pattern.
PowerShell’s tab completion is largely driven by the fully
customizable TabExpansion2 function.
You can easily change this function to include more advanced
functionality, or even just customize specific behaviors to suit your
personal preferences. For more information, see Understand and Customize PowerShell’s Tab Completion.
While PowerShell’s built-in filtering facilities are incredibly
flexible (for example, the Where-Object
cmdlet), they generally operate against specific properties of the
incoming object. If you are searching for text in the object’s formatted
output, or don’t know which property contains the text you are looking
for, simple text-based filtering is sometimes helpful.
To solve this problem, you can pipe the output into the
Out-String cmdlet before passing it to
the Select-String cmdlet:
Get-Service | Out-String -Stream | Select-String audio
Or, using built-in aliases:
Get-Service | oss | sls audio
In script form, Select-TextOutput (shown in Example 1-17) does exactly this, and it lets you
search for a pattern in the visual representation of command
output.
Example 1-17. Select-TextOutput.ps1
##############################################################################
##
## Select-TextOutput
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Searches the textual output of a command for a pattern.
.EXAMPLE
PS > Get-Service | Select-TextOutput audio
Finds all references to "Audio" in the output of Get-Service
#>
param(
## The pattern to search for
$Pattern
)
Set-StrictMode -Version 3
$input | Out-String -Stream | Select-String $patternFor more information about running scripts, see Run Programs, Scripts, and Existing Tools.
The Out-GridView cmdlet is one of the rare
PowerShell cmdlets that displays a graphical user interface. While the
Where-Object and Sort-Object cmdlets are the most common way to
sort and filter lists of items, the Out-GridView cmdlet is very effective at the
style of repeated refinement that sometimes helps you develop complex
queries. Figure 1-3 shows the Out-GridView cmdlet in action.
Out-GridView lets you primarily
filter your command output in two ways: a quick
filter expression and a criteria
filter.
Quick filters are fairly simple. As you type
text in the topmost “Filter” window, Out-GridView filters the list to contain only
items that match that text. If you want to restrict this text filtering
to specific columns, simply provide a column name before your search
string and separate the two with a colon. You can provide multiple
search strings, in which case Out-GridView returns only rows that match all
of the required strings.
Note
Unlike most filtering cmdlets in PowerShell, the quick filters
in the Out-GridView cmdlet do not
support wildcards or regular expressions. For this type of advanced
query, criteria-based filtering can help.
Criteria filters give fine-grained control
over the filtering used by the Out-GridView cmdlet. To apply a criteria
filter, click the “Add criteria” button and select a property to filter
on. Out-GridView adds a row below the
quick filter field and lets you pick one of several operations to apply
to this property:
Less than or equal to
Greater than or equal to
Between
Equals
Does not equal
Contains
Does not contain
In addition to these filtering options, Out-GridView also lets you click and rearrange
the header columns to sort by them.
Once you’ve sliced and diced your command output, you can select
any rows you want to keep and press Ctrl-C to copy them to the
clipboard. Out-GridView copies the
items to the clipboard as tab-separated data, so you can easily paste
the information into a spreadsheet or other file for further
processing.
In addition to supporting clipboard output, the Out-GridView cmdlet supports full-fidelity
object filtering if you use its -PassThru parameter. For an example of this
full-fidelity filtering, see Program: Interactively Filter Lists of Objects.
When working with unfamiliar objects in PowerShell, much of your
time is spent with the Get-Member and
Format-List commands—navigating through
properties, reviewing members, and more.
For ad hoc investigation, a graphical interface is often useful.
To solve this problem, Example 1-18 provides an interactive tree view that you can use to explore and navigate objects. For example, to examine the structure of a script as PowerShell sees it (its abstract syntax tree):
$ps = { Get-Process -ID $pid }.Ast
Show-Object $psFor more information about parsing and analyzing the structure of PowerShell scripts, see Parse and Interpret PowerShell Scripts.
Example 1-18. Show-Object.ps1
#############################################################################
##
## Show-Object
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Provides a graphical interface to let you explore and navigate an object.
.EXAMPLE
PS > $ps = { Get-Process -ID $pid }.Ast
PS > Show-Object $ps
#>
param(
## The object to examine
[Parameter(ValueFromPipeline = $true)]
$InputObject
)
Set-StrictMode -Version 3
Add-Type -Assembly System.Windows.Forms
## Figure out the variable name to use when displaying the
## object navigation syntax. To do this, we look through all
## of the variables for the one with the same object identifier.
$rootVariableName = dir variable:\* -Exclude InputObject,Args |
Where-Object {
$_.Value -and
($_.Value.GetType() -eq $InputObject.GetType()) -and
($_.Value.GetHashCode() -eq $InputObject.GetHashCode())
}
## If we got multiple, pick the first
$rootVariableName = $rootVariableName| % Name | Select -First 1
## If we didn't find one, use a default name
if(-not $rootVariableName)
{
$rootVariableName = "InputObject"
}
## A function to add an object to the display tree
function PopulateNode($node, $object)
{
## If we've been asked to add a NULL object, just return
if(-not $object) { return }
## If the object is a collection, then we need to add multiple
## children to the node
if([System.Management.Automation.LanguagePrimitives]::GetEnumerator($object))
{
## Some very rare collections don't support indexing (i.e.: $foo[0]).
## In this situation, PowerShell returns the parent object back when you
## try to access the [0] property.
$isOnlyEnumerable = $object.GetHashCode() -eq $object[0].GetHashCode()
## Go through all the items
$count = 0
foreach($childObjectValue in $object)
{
## Create the new node to add, with the node text of the item and
## value, along with its type
$newChildNode = New-Object Windows.Forms.TreeNode
$newChildNode.Text = "$($node.Name)[$count] = $childObjectValue : " +
$childObjectValue.GetType()
## Use the node name to keep track of the actual property name
## and syntax to access that property.
## If we can't use the index operator to access children, add
## a special tag that we'll handle specially when displaying
## the node names.
if($isOnlyEnumerable)
{
$newChildNode.Name = "@"
}
$newChildNode.Name += "[$count]"
$null = $node.Nodes.Add($newChildNode)
## If this node has children or properties, add a placeholder
## node underneath so that the node shows a '+' sign to be
## expanded.
AddPlaceholderIfRequired $newChildNode $childObjectValue
$count++
}
}
else
{
## If the item was not a collection, then go through its
## properties
foreach($child in $object.PSObject.Properties)
{
## Figure out the value of the property, along with
## its type.
$childObject = $child.Value
$childObjectType = $null
if($childObject)
{
$childObjectType = $childObject.GetType()
}
## Create the new node to add, with the node text of the item and
## value, along with its type
$childNode = New-Object Windows.Forms.TreeNode
$childNode.Text = $child.Name + " = $childObject : $childObjectType"
$childNode.Name = $child.Name
$null = $node.Nodes.Add($childNode)
## If this node has children or properties, add a placeholder
## node underneath so that the node shows a '+' sign to be
## expanded.
AddPlaceholderIfRequired $childNode $childObject
}
}
}
## A function to add a placeholder if required to a node.
## If there are any properties or children for this object, make a temporary
## node with the text "..." so that the node shows a '+' sign to be
## expanded.
function AddPlaceholderIfRequired($node, $object)
{
if(-not $object) { return }
if([System.Management.Automation.LanguagePrimitives]::GetEnumerator($object) -or
@($object.PSObject.Properties))
{
$null = $node.Nodes.Add( (New-Object Windows.Forms.TreeNode "...") )
}
}
## A function invoked when a node is selected.
function OnAfterSelect
{
param($Sender, $TreeViewEventArgs)
## Determine the selected node
$nodeSelected = $Sender.SelectedNode
## Walk through its parents, creating the virtual
## PowerShell syntax to access this property.
$nodePath = GetPathForNode $nodeSelected
## Now, invoke that PowerShell syntax to retrieve
## the value of the property.
$resultObject = Invoke-Expression $nodePath
$outputPane.Text = $nodePath
## If we got some output, put the object's member
## information in the text box.
if($resultObject)
{
$members = Get-Member -InputObject $resultObject | Out-String
$outputPane.Text += "`n" + $members
}
}
## A function invoked when the user is about to expand a node
function OnBeforeExpand
{
param($Sender, $TreeViewCancelEventArgs)
## Determine the selected node
$selectedNode = $TreeViewCancelEventArgs.Node
## If it has a child node that is the placeholder, clear
## the placeholder node.
if($selectedNode.FirstNode -and
($selectedNode.FirstNode.Text -eq "..."))
{
$selectedNode.Nodes.Clear()
}
else
{
return
}
## Walk through its parents, creating the virtual
## PowerShell syntax to access this property.
$nodePath = GetPathForNode $selectedNode
## Now, invoke that PowerShell syntax to retrieve
## the value of the property.
Invoke-Expression "`$resultObject = $nodePath"
## And populate the node with the result object.
PopulateNode $selectedNode $resultObject
}
## A function to handle keypresses on the form.
## In this case, we capture ^C to copy the path of
## the object property that we're currently viewing.
function OnKeyPress
{
param($Sender, $KeyPressEventArgs)
## [Char] 3 = Control-C
if($KeyPressEventArgs.KeyChar -eq 3)
{
$KeyPressEventArgs.Handled = $true
## Get the object path, and set it on the clipboard
$node = $Sender.SelectedNode
$nodePath = GetPathForNode $node
[System.Windows.Forms.Clipboard]::SetText($nodePath)
$form.Close()
}
}
## A function to walk through the parents of a node,
## creating virtual PowerShell syntax to access this property.
function GetPathForNode
{
param($Node)
$nodeElements = @()
## Go through all the parents, adding them so that
## $nodeElements is in order.
while($Node)
{
$nodeElements = ,$Node + $nodeElements
$Node = $Node.Parent
}
## Now go through the node elements
$nodePath = ""
foreach($Node in $nodeElements)
{
$nodeName = $Node.Name
## If it was a node that PowerShell is able to enumerate
## (but not index), wrap it in the array cast operator.
if($nodeName.StartsWith('@'))
{
$nodeName = $nodeName.Substring(1)
$nodePath = "@(" + $nodePath + ")"
}
elseif($nodeName.StartsWith('['))
{
## If it's a child index, we don't need to
## add the dot for property access
}
elseif($nodePath)
{
## Otherwise, we're accessing a property. Add a dot.
$nodePath += "."
}
## Append the node name to the path
$nodePath += $nodeName
}
## And return the result
$nodePath
}
## Create the TreeView, which will hold our object navigation
## area.
$treeView = New-Object Windows.Forms.TreeView
$treeView.Dock = "Top"
$treeView.Height = 500
$treeView.PathSeparator = "."
$treeView.Add_AfterSelect( { OnAfterSelect @args } )
$treeView.Add_BeforeExpand( { OnBeforeExpand @args } )
$treeView.Add_KeyPress( { OnKeyPress @args } )
## Create the output pane, which will hold our object
## member information.
$outputPane = New-Object System.Windows.Forms.TextBox
$outputPane.Multiline = $true
$outputPane.ScrollBars = "Vertical"
$outputPane.Font = "Consolas"
$outputPane.Dock = "Top"
$outputPane.Height = 300
## Create the root node, which represents the object
## we are trying to show.
$root = New-Object Windows.Forms.TreeNode
$root.Text = "$InputObject : " + $InputObject.GetType()
$root.Name = '$' + $rootVariableName
$root.Expand()
$null = $treeView.Nodes.Add($root)
## And populate the initial information into the tree
## view.
PopulateNode $root $InputObject
## Finally, create the main form and show it.
$form = New-Object Windows.Forms.Form
$form.Text = "Browsing " + $root.Text
$form.Width = 1000
$form.Height = 800
$form.Controls.Add($outputPane)
$form.Controls.Add($treeView)
$null = $form.ShowDialog()
$form.Dispose()For more information about running scripts, see Run Programs, Scripts, and Existing Tools.
To redirect the output of a command into a file, use either
the Out-File cmdlet or one of the
redirection operators.
Out-File:
Get-ChildItem | Out-File unicodeFile.txt Get-Contentfilename.cs | Out-File -Encoding ASCIIfile.txtGet-ChildItem | Out-File -Width 120 unicodeFile.cs
Get-ChildItem >files.txtGet-ChildItem 2>errors.txtGet-ChildItemn>otherStreams.txt
The Out-File
cmdlet and redirection operators share a lot in common. For the most
part, you can use either. The redirection operators are unique because
they give the greatest amount of control over redirecting individual
streams. The Out-File cmdlet is
unique primarily because it lets you easily configure the formatting
width and encoding.
Note
If you want to save the objects from a command into a file (rather than the text-based representation that you see on screen), see Easily Import and Export Your Structured Data.
The default formatting width and the default output encoding are two aspects of output redirection that can sometimes cause difficulty.
The default formatting width sometimes causes problems because
redirecting PowerShell-formatted
output into a file is designed to mimic what you see on the screen. If
your screen is 80 characters wide, the file will be 80 characters wide
as well. Examples of PowerShell-formatted output include directory
listings (that are implicitly formatted as a table) as well as any
commands that you explicitly format using one of the Format-* set of
cmdlets. If this causes problems, you can customize the width
of the file with the -Width parameter
on the Out-File cmdlet.
The default output encoding sometimes causes unexpected results
because PowerShell creates all files using the UTF-16 Unicode encoding
by default. This allows PowerShell to fully support the entire range of
international characters, cmdlets, and output. Although this is a great
improvement on traditional shells, it may cause an unwanted surprise
when running large search-and-replace operations on ASCII source code
files, for example. To force PowerShell to send its output to a file in
the ASCII encoding, use the -Encoding
parameter on the Out-File
cmdlet.
For more information about the Out-File cmdlet, type Get-Help Out-File. For a full list of
supported redirection operators, see Capturing Output.
You want to redirect the output of a pipeline into a file but add the information to the end of that file.
To redirect the output of a command into a
file, use either the -Append
parameter of the Out-File cmdlet or
one of the appending redirection operators described in Capturing Output. Both support options to append text to
the end of a file.
Out-File:
Get-ChildItem | Out-File -Append files.txtGet-ChildItem >> files.txtThe Out-File
cmdlet and redirection operators share a lot in common. For the most
part, you can use either. See the discussion in Store the Output of a Command into a File for a more detailed comparison of the two
approaches, including reasons that you would pick one over the
other.
To record a transcript of your shell session, run the
command Start-Transcript. It has an
optional -Path parameter that
defaults to a filename based on the current system time. By default,
PowerShell places this file in the My
Documents directory. To stop recording the transcript of your
shell system, run the command Stop-Transcript.
Although the Get-History cmdlet is helpful, it does not
record the output produced during your PowerShell session. To accomplish
that, use the Start-Transcript
cmdlet. In addition to the Path
parameter described previously, the Start-Transcript cmdlet also supports
parameters that let you control how PowerShell interacts with the output
file.
If the module is part of the standard PowerShell module path, simply run the command you want.
Invoke-NewCommand
If it is not, use the Import-Module command to import third-party
commands into your PowerShell session.
To import a module from a specific directory:
Import-Module c:\path\to\moduleTo import a module from a specific file (module, script, or assembly):
Import-Module c:\path\to\module\file.extPowerShell supports two sets of commands that
enable additional cmdlets and providers: *-Module and *-PsSnapin. Snapins were the packages for extensions in version 1 of
PowerShell, and are rarely used. Snapins supported only compiled
extensions and had onerous installation requirements.
Version 2 of PowerShell introduced modules that support everything that snapins support (and more) without the associated installation pain. That said, PowerShell version 2 also required that you remember which modules contained which commands and manually load those modules before using them. Windows 8 and Windows Server 2012 include thousands of commands in over 50 modules—quickly making reliance on one’s memory an unsustainable approach.
PowerShell version 3 significantly improves the situation by
autoloading modules for you. Internally, it maintains a mapping of
command names to the module that contains them. Simply start using a
command (which the Get-Command cmdlet
can help you discover), and PowerShell loads the appropriate module
automatically. If you wish to customize this autoloading behavior,
you can use the $PSModuleAutoLoadingPreference preference
variable.
When PowerShell imports a module with a given name, it searches through every directory listed in the PSModulePath environment variable, looking for
the first module that contains the subdirectories that match the name
you specify. Inside those directories, it looks for the module (*.psd1, *.psm1, and *.dll) with the same name and loads it.
Note
When autoloading modules, PowerShell prefers modules in the
system’s module directory over those in your personal module path.
This prevents user modules from accidentally overriding core
functionality. If you want a module to override core functionality,
you can still use the Import-Module
cmdlet to load the module explicitly.
When you install a module on your own system, the most common
place to put it is in the WindowsPowerShell\Modules directory in your
My Documents
directory. To have PowerShell look in another directory for modules, add
it to your personal PSModulePath
environment variable, just as you would add a Tools directory to your personal path.
For more information about managing system paths, see Modify the User or System Path.
If you want to load a module from a directory not in PSModulePath, you can provide the entire
directory name and module name to the Import-Module command. For example, for a
module named Test, use Import-Module
c:\path\to\Testc:\temp\path\to for a module
(*.psd1, *.psm1, or
*.dll) named Test and loads it.
If you know the specific module file you want to load, you can also specify the full path to that module.
If you want to find additional commands, there are several useful resources available.
- PowerShell Community Extensions
Located here, the PowerShell Community Extensions project contains a curated collection of useful and powerful commands. It has been written by a handful of volunteers, many of them Microsoft MVPs.
- The Technet Script Center Gallery
Located here, the TechNet Script Center Gallery offers a well-indexed and well-organized collection of PowerShell scripts.
- PoshCode
Located here, PoshCode contains thousands of scripts and script snippets—of both high and low quality.
You want to use the commands from a PowerShell-based product that launches a customized version of the PowerShell console, but in a regular PowerShell session.
Launch the customized version of the PowerShell console, and
then use the Get-Module
and Get-PsSnapin commands to see what
additional modules and/or snapins it loaded.
As described in Extend Your Shell with Additional Commands, PowerShell modules and snapins are the two ways that third parties can distribute and add additional PowerShell commands. Products that provide customized versions of the PowerShell console do this by calling PowerShell.exe with one of three parameters:
Regardless of which one it used, you can examine the resulting set of loaded extensions to see which ones you can import into your other PowerShell sessions.
The Get-PsSnapin command
returns all snapins loaded in the current session. It always returns
the set of core PowerShell snapins, but it will also return any
additional snapins loaded by the customized environment. For
example, if the name of a snapin you recognize is
Product.Feature.Commands, you can load that
into future PowerShell sessions by typing Add-PsSnapin
Product.Feature.Commands. To
automate this, add the command into your PowerShell profile.
If you are uncertain of which snapin to load, you can also use
the Get-Command command to discover
which snapin defines a specific command:
PS > Get-Command Get-Counter | Select PsSnapin PSSnapIn -------- Microsoft.PowerShell.Diagnostics
Like the Get-PsSnapin
command, the Get-Module command
returns all modules loaded in the current session. It returns any
modules you’ve added so far into that session, but it will also return
any additional modules loaded by the customized environment. For
example, if the name of a module you recognize is
ProductModule, you can load that into
future PowerShell sessions by typing Import-Module
ProductModule. To automate this,
add the command into your PowerShell profile.
If you are uncertain of which module to load, you can also use
the Get-Command command to discover
which module defines a specific command:
PS > Get-Command Start-BitsTransfer | Select Module Module ------ BitsTransfer
Subscribe to the PowerShell.Exiting engine event to have
PowerShell invoke a script or script block that saves any state you
need.
To have PowerShell save your command history, place a call
to Enable-HistoryPersistence in your profile, as in Example 1-19.
Example 1-19. Enable-HistoryPersistence.ps1
##############################################################################
##
## Enable-HistoryPersistence
##
## From Windows PowerShell Cookbook (O'Reilly)
## by Lee Holmes (http://www.leeholmes.com/guide)
##
##############################################################################
<#
.SYNOPSIS
Reloads any previously saved command history, and registers for the
PowerShell.Exiting engine event to save new history when the shell
exits.
#>
Set-StrictMode -Version 3
## Load our previous history
$GLOBAL:maximumHistoryCount = 32767
$historyFile = (Join-Path (Split-Path $profile) "commandHistory.clixml")
if(Test-Path $historyFile)
{
Import-CliXml $historyFile | Add-History
}
## Register for the engine shutdown event
$null = Register-EngineEvent -SourceIdentifier `
([System.Management.Automation.PsEngineEvent]::Exiting) -Action {
## Save our history
$historyFile = (Join-Path (Split-Path $profile) "commandHistory.clixml")
$maximumHistoryCount = 1kb
## Get the previous history items
$oldEntries = @()
if(Test-Path $historyFile)
{
$oldEntries = Import-CliXml $historyFile -ErrorAction SilentlyContinue
}
## And merge them with our changes
$currentEntries = Get-History -Count $maximumHistoryCount
$additions = Compare-Object $oldEntries $currentEntries `
-Property CommandLine | Where-Object { $_.SideIndicator -eq "=>" } |
Foreach-Object { $_.CommandLine }
$newEntries = $currentEntries | ? { $additions -contains $_.CommandLine }
## Keep only unique command lines. First sort by CommandLine in
## descending order (so that we keep the newest entries,) and then
## re-sort by StartExecutionTime.
$history = @($oldEntries + $newEntries) |
Sort -Unique -Descending CommandLine | Sort StartExecutionTime
## Finally, keep the last 100
Remove-Item $historyFile
$history | Select -Last 100 | Export-CliXml $historyFile
}PowerShell provides easy script-based access to a broad variety of
system, engine, and other events. You can register for notification of
these events and even automatically process any of those events. In this
example, we subscribe to the only one currently available, which is
called PowerShell.Exiting. PowerShell
generates this event when you close a session.
This script could do anything, but in this example we have it save our command history and restore it when we launch PowerShell. Why would we want to do this? Well, with a rich history buffer, we can more easily find and reuse commands we’ve previously run. For two examples of doing this, see Examples and .
Example 1-19 takes two main
actions. First, we load our stored command history (if any exists).
Then, we register an automatic action to be processed whenever the
engine generates its PowerShell.Exiting event. The action itself is
relatively straightforward, although exporting our new history does take
a little finesse. If you have several sessions open at the same time,
each will update the saved history file when it exits. Since we don’t
want to overwrite the history saved by the other shells, we first reload
the history from disk and combine it with the history from the current
shell.
Once we have the combined list of command lines, we sort them and pick out the unique ones before storing them back in the file.
For more information about working with PowerShell engine events, see Create and Respond to Custom Events.
Get Windows PowerShell Cookbook, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
