Keith's profileKeith Hill's BlogPhotosBlogListsMore  |  Tools Help |
|
|
August 03 Effective PowerShell Item 16: Dealing with ErrorsThere are several facets to the subject of errors in PowerShell that you should understand to get the most out of PowerShell. Some of these facets are error handling, error related global variables and error related preference variables. But the most fundamental facet is the distinction between “terminating” and “non-terminating” errors. Terminating Errors Terminating errors will be immediately familiar to software developers who deal with exceptions. If an exception is not handled it will cause the program to crash. Similarly if a terminating error is not handled it will cause the current operation (cmdlet or script) to abort with an error. Terminating errors and are generated by:
The gist of a terminating error is that the code throwing the terminating error is indicating that it cannot reasonably continue and is aborting the requested operation. As we will see later, you as the client of that code, have the ability to declare that you can handle the error and continue executing subsequent commands. Terminating errors that are not handled propagate up through the calling code, prematurely terminating each calling function or script until either the error is handled or the original invoking operation is terminated. Here is an example of how a terminating error alters control flow: PS> "Before"; throw "Oops!"; "After" Note that “After” is not output to the console because “throw” issues a terminating error. Non-terminating Errors Have you ever experienced the following in older versions of Windows Explorer? You open a directory with a large number of files, say your temp dir, and you want to empty it. You select the entire contents of the directory, press Delete and wait. Unfortunately some processes invariably have files open in the temp directory. So after deleting a few files, you get an error from Windows Explorer indicating that it can’t delete some file. You press OK and at this point Windows Explorer aborts the operation. It treats the error effectively as a terminating error. This can be very frustrating. You select everything again, press Delete, Explorer deletes a few more files then errors and aborts again. You rinse and repeat these steps until finally all the files that can be deleted are deleted. This behavior is very annoying and wastes your time. In an automation scenario, premature aborts like this are often unacceptable. Having a special category of error that does not terminate the current operation is very useful in scenarios like the one outlined above. In PowerShell, that category is the non-terminating error. Even though a non-terminating error does not terminate the current operation, the error is still logged to the $Error collection (discussed later) as well as displayed on the host’s console as is the case with terminating errors. Non-terminating errors are generated by:
Here is an example of how a non-terminating error does not alter control flow: PS> "Before"; Write-Error "Oops!"; "After" After Note the Write-Error command issues a non-terminating error that gets displayed on the host’s console then the script continues execution. Error Variables There are several global variables and global preference variables related to errors. Here is a brief primer on them:
The $Error global variable can be used to inspect the details of up to the last $MaximumErrorCount number of errors that have occurred during the session e.g.: PS> $error[0] | fl * -force PSMessageDetails : As the output above shows, errors in PowerShell are not just strings but rich objects. The object may be a .NET exception with an embedded error record or just an error record, The error record contains lots of useful information about the error and the context in which it occurred. The default output formatting of errors can be a bit hard to digest. The PowerShell Community Extensions come with a handy Resolve-Error function that digs through the error information and surfaces the important stuff e.g.: PS> Resolve-Error # displays $error[0] by default The $? global variable is handy for determining if the last operation encountered any errors e.g.: PS> Remove-Item $env:temp\*.txt -Recurse -Verbose In this case, the Remove-Item cmdlet only partially succeeded. It deleted two files but then encountered a non-terminating error. This failure to achieve complete success i.e. no errors, is indicated by $? returning False. Working with Non-Terminating Errors Sometimes you want to completely ignore non-terminating errors. Who wants all that red text spilled all over their console especially when you don’t care about the errors you know you're going to get. You can suppress the display of non-terminating errors either locally or globally. To do this locally, just set the cmdlet’s ErrorAction parameter to SilentlyContinue e.g. Remove-Item $env:temp\*.txt -Recurse -Verbose -ErrorAction SilentlyContinue For interactive scenarios it is handy to use 0 instead of SilentlyContinue. This works because SilentlyContinue is part of a enum and its integer value is 0. So to save your wrists you can rewrite the above as: ri $env:temp\*.txt -r -v –ea 0 Note that for a script I would use the first approach for readability. To accomplish the above globally, set the $ErrorActionPreference global preference variable to SilentlyContinue (or 0). This will cause all non-terminating errors in the session to not be displayed on the host’s console. However they will still be logged to the $Error collection. Setting the $ErrorActionPreference to Stop can be useful in the following scenario. If you misspell a command, PowerShell will generate a non-terminating error as shown below: PS> Copy-Itme .\_lesshst .\_lesshst.bak; $?; "After" False In this case, the misspelled Copy-Itme command failed ($? returned False) but since the error was non-terminating, the script continues execution as shown by the output “After”. If you are hard-core about correctness you can get PowerShell to convert non-terminating errors into terminating errors by setting $ErrorActionPreference to Stop which has global impact. You can also do this one a cmdlet by cmdlet basis by setting the cmdlet’s –ErrorAction parameter to Stop. The last issue to be aware of regarding non-terminating errors is that a Windows executable that returns a non-zero exit code does not generate any sort of error. The only action PowerShell takes is to set $? to False if the exit code is non-zero. There is no error record created and stuffed into $Error. In many cases, the failure of an external executable means your script cannot continue. In this case, it is desirable to convert a failure exit code into a terminating error. This can be done easily using the function below: function CheckLastExitCode { Note that Get-PSCallStack is specific to PowerShell v2.0. Invoke CheckLastExitCode right after invoking an executable, well at least for those cases where you care if an executable returns an error. This function provides a couple of handy features. First, you can specify an array of acceptable success codes which is useful for exes that return 0 for failure and 1 for success and is also useful for exes that return multiple success codes. Second, you specify a cleanup scriptblock that will get executed on failure. Handling Terminating Errors Handling terminating errors in PowerShell comes in two flavors. Using the trap keyword which is supported in both version 1 and 2 of PowerShell. Using try { } catch { } finally { } which is new to version 2. Trap Statement Trap is a mechanism available in other shell languages like Korn shell. It effectively declares that either any error type or a specific error type is handled by the scriptblock following the trap keyword. Trap has the interesting property that where ever it is declared in a scope, it is valid for that entire scope e.g.: Given the following script (trap.ps1): Invoking it results in the following output: PS> .\trap.ps1 Note that it doesn’t matter that the trap statement is after the line that throws the error. Also note that since the default value for $ErrorActionPreference is 'Continue', the error is displayed, logged to $Error but execution resumes at the next statement. Note: within the context of a trap statement, $_ represents the error that was caught. Another thing to consider is whether to use Write-Host or Write-Output to display text in the trap statement. The example above implicitly uses Write-Output. This has the benefit that the text can be redirected to a log file. The downside is that if the exception is handled and execution continues, that text will become part of the output for that scope which, in the case of functions and scripts, may not be desirable. If you want to execute cleanup code on failure but still terminate execution, we can change the trap statement to use the break keyword. Consider the following script: function Cleanup() {"cleaning up"} Note that the inner trap calls the Cleanup function but then propagates the error. As a result, the “Inner After” statement never executes because control flow is transferred outside the scope of the trap statement. The outer trap then catches the error, displays it and continues execution. As a result, the “Outer After” statement is executed. The interaction between the control flow altering keywords valid in a trap statement (break, continue and return), the $ErrorActionPreference variable if no control flow altering keyword is used and the final behavior is somewhat complex as is demonstrated by the table below: Trap Behavior:
* <object> is appended to the end of the trap scope’s output. All of the examples of trap shown above trap all errors. You may want to trap only specific errors. You can do this by specifying the type name of an exception to trap as shown below: trap [System.DivideByZeroException] { "Please don't divide by 0!"} If you want to execute different code for different errors, you can define multiple trap statements in your script: trap [System.DivideByZeroException] { "Please don't divide by 0!"}trap [System.Management.Automation.CommandNotFoundException] { "Did you fat finger the command name?" } If you define multiple trap statements for the same error type the first one wins and the others within the same scope are ignored. Try / Catch / Finally Version 2 of Windows PowerShell introduces try/catch/finally statements - a new error handling mechanism that most developers will be immediately familiar with. There are two main differences between trap and try/catch/finally. First, a trap anywhere in a lexical scope covers the entire lexical scope. With a try statement, only the script within the try statement is checked for errors. The second difference is that trap doesn’t support finally behavior i.e., always execute the finally statement whether the code in the try statement throws a terminating error or not. In fact, any associated catch statements could also throw a terminating error and the finally statement would still execute. You can fake finally behavior with trap by calling the same “finally” code from the end of the lexical scope *and* from the trap statement. Consider the Cleanup function from the earlier example. We want to always execute Cleanup whether the script errors or not. The example shown in the previous section using the Cleanup function works OK unless the Cleanup function throws a terminating error. Then you run into the issue where Cleanup gets called again due to the trap statement. This sort of cleanup is much easier to represent in your script using try/finally e.g.: function Cleanup($err) {"cleaning up"} "Outer Before" This example results in Cleanup always getting called whether or not the script in the try statement generates a terminating error. It also shows that you can mix and match trap statements with try/catch/finally. One last example shows how you can use catch to handle different error types uniquely: function Cleanup($err) {"cleaning up"} "Outer Before" The use of the finally statement is optional as is the catch statement. The valid combinations are try/catch, try/finally and try/catch/finally. In summary, PowerShell’s error handling capabilities are quite powerful especially the ability to distinguish between non-terminating and terminating errors. With the addition of the new try/catch/finally support in version 2.0 the important scenario of resource cleanup is easy to handle. April 05 Effective PowerShell Item 15: Using the Output Field Separator $OFS$OFS is the “output field separator” variable. Whatever value it contains will be used as the string separator between elements of an array that is rendered to a string. For example, consider the following array definition and subsequent rendering to string: PS> $array = 1,2,3 What would you expect the resulting string to be? Here’s the output: 1 2 3 How does PowerShell go about rendering elements of an array into a single string? It is pretty simple as you would expect. Each element is converted to its string representation. The only other detail left is to determine what characters to use to separate each element in the final string. The $OFS variable is not initially created by PowerShell and if it doesn’t exist, PowerShell uses a single space character to separate elements as you can see in the example above. What is neat is that PowerShell gives you the ability change the separator string by setting the $OFS variable like this: PS> $OFS = ', ' Note that the separator doesn’t have to be single character. It doesn’t even have to be a string, but in the end whatever value that is assigned to $OFS is converted to a string e.g.: PS> $OFS = $true This is an admittedly weird example. In the common case, you will just assign a string to $OFS like “, “ or “`t” or “`n”, etc. $OFS also works for multi-dimensional arrays e.g.: PS> $array = new-object 'int[,]' 2, 3 Unfortunately, $OFS doesn’t work so well for jagged arrays: PS> $array = @(@(1,2),@(3,4)) When I see folks use [string]::Join() or –join in version 2 of PowerShell, I wonder if it would be better to use $OFS and string rendering. Here is an example I came across recently: $typeDecls = @($_.GetGenericArguments() | %{"[string]`$Of" + $_.Name}) –join ', ' Using $OFS the script changes to: $OFS = ', ' In this example, the use of $OFS shines because you benefit by delaying the string rendering of the arrays until the last moment. In this case, I wanted to keep both $typeDecls and $paramDecls as arrays so that they could be concatenated together and then rendered as a string containing a comma separated list. If these two variables had been converted to strings earlier, as in the “before” script above, then you need special case logic in the event $typeDecls and/or $paramDecls are empty. March 08 Effective Windows PowerShell: The Free eBookI’ve gotten some requests to turn my Effective PowerShell blog posts into booklet form which I have done. I expect that this document will grow over time as I add new items. If you have feedback (typos, suggestions, etc) please drop me a line. Errata: psmdtag:book - Effective Windows PowerShell eBook March 06 Effective PowerShell Item 14: Capturing All Output from a ScriptBoth version 1 and version 2 of Windows PowerShell have a nasty limitation when it comes to capturing *all* output from a script. First up, within a script there is no way to redirect host (Write-Host), verbose, warning and debug message to a log file. There is a mechanism within PowerShell that allows you to capture these streams of information - Start-Transcript. At first blush, this seems promising however the wheels fall off pretty quickly primarily because Start-Transcript doesn’t capture the output of EXEs. So all that output from compilers, build tools, etc doesn’t get captured. That’s a huge, gaping hole. Furthermore, Start-Transcript is really aimed at capturing your entire PowerShell session. It isn’t particularly suited for script logging. For instance, some folks including myself use Start-Transcript in their profile to capture an entire PowerShell session. This is very handy when you need to look up how you did something previously which is possible because you can search your transcript files. However, if you start a script that blindly calls Start-Transcript it will error. You can only call Start-Transcript if it hasn’t already been started . There is no notion of nested transcripts. If you find these limitations as annoying as I do, please vote on them via the Microsoft Connect site: https://connect.microsoft.com/feedback/ViewFeedback.aspx?FeedbackID=283088&SiteID=99 For now, the best way to accomplish this is to use a host that can capture all PowerShell output. It turns out that executing the script through another instance of PowerShell.exe will allow you to capture all the output. For instance, consider the following script (test.ps1) that exercises the various output streams: 1: $DebugPreference = 2 2: $VerbosePreference = 2 3: $WarningPreference = 2 4: 5: hostname.exe6: Write-Host "host" 7: Write-Output "output" 8: Write-Error "error" 9: Write-Verbose "verbose" 10: Write-Warning "warning" 11: Write-Debug "debug"
Updated 3/7/09: Aleksandar pointed out that you can just use Powershell.exe. No need to go through cmd.exe. Thanks! psmdtag:script - Logging output May 11 Effective PowerShell Item 13: Comparing Arrays in Windows PowerShellPowerShell has a lot of useful operators such as -contains which tests if an array contains an particular element. But as far as I can tell PowerShell doesn't "seem" to provide an easy way to test if two array's contents are equal. This if often quite handy and I was a bit surprised by this apparent omission. I came upon this need to compare arrays while answering a question on the microsoft.public.windows.powershell newsgroup. The poster wanted to find UTF8 encoded files by inspecting their BOM or byte order mark. One relatively straight forward approach to this is:
While it is easy enough to visually inspect this and see we have a match, visual inspection doesn't work in a script. :-) You could also test each individual element which isn't bad for a three element array but when you hit say 10 elements that approach might starting looking tedious. You might think that we could just compare these two arrays directly like so:
But comparing arrays via the -eq operator doesn't actually compare the contents of two arrays. As you can see above, this results in no output. When the left hand side of the -eq operator is an array, PowerShell return the elements of the array that match the value specified on the right hand side (shown above where I test for -eq to 0xbb). OK so it looks like we need to roll our own mechanism to compare arrays. Here is one way: function AreArraysEqual($a1, $a2) { while ($enum1.MoveNext() -and $enum2.MoveNext()) { And it works as expected:
However there turns out to be a way to do this within PowerShell but it isn't exactly obvious. At least it wasn't to me - at first.
Good old Compare-Object will compare the arrays and if there are no differences it won't output anything. If we wrap the output of Compare-Object in an array subexpression @() then we will get an array with either 0 or more elements. A simple compare of the length to 0 will confirm that there was no output, hence the arrays are equal. [Updated: 5/12/2008 - need to use -SyncWindow 0 to get correct result - thanks Arnoud and Roman] Let me elaborate more on this updated information. As Roman points out in the comments on this post, Compare-Object compares two objects to see if they have the same set of elements. Normally it does not care if the elements are in the same sequence in each object (each array in this case). For example: PS> $a1 = 1,1,2 Obviously that isn't what we want when comparing arrays for equality. Fortunately, as Arnoud points out, we can use the SyncWindow parameter with a value 0 to get Compare-Object to "force sequence equality" as Arnoud succinctly phrases it. How about performance of these two approaches:
Compare-Object beats out my PowerShell function by a good margin which isn't too surprising[1]. After all, one is compiled code and the other is interpreted script. So there you have it. If you need a quick way to compare to arrays, just remember that arrays are objects too and that is what Compare-Object does best - compare two objects. [1] - Except for comparing against the same array where my function is two orders of magnitude faster. It seems that the Compare-Object cmdlet could benefit from a quick System.Object.ReferenceEquals check. :-) Admittedly this is a bit of a corner case scenario. May 09 Effective PowerShell Item 12: Understanding ByValue Pipeline Bound ParametersIn item 11, I covered ByPropertyName pipeline bound parameters. In this post, I'll cover the other variety of pipeline binding - ByValue. ByValue binding takes the input object itself and attempts to bind it by type using type coercion if possible to parameters decorated as ByValue. For example, most of the *-Object utility cmdlets operate on whatever object is presented to them. The help on Where-Object shows this: -inputObject <psobject> Required? false It turns out that ByValue isn't nearly as popular as ByPropertyValue. How can I make such a statement you ask? Well this is one of the things that I love about PowerShell. It provides so much metadata about itself. It is very "self describing". You can easily walk every parameter on every cmdlet that is currently loaded into PowerShell. First let's see what information is available for a parameter:
The interesting properties for us here are the Name and ValueFromPipeline* properties. Given this information it is easy to figure out how many of each type there are:
So from here we can see the following:
So indeed binding by property name is much more common. Binding by value from the pipeline is primarily for cmdlets that manipulate objects. In the query below we can see that the InputObject parameter is by far the most common "ByValue" pipeline bound parameter:
A little further digging reveals the cmdlets that use the ByValue bound InputObject parameters as shown below. Note that a single parameter can appear in more than one parameter set on a cmdlet, which explains why there are only 36 cmdlets that account for the 40 instances of InputObject.
As you can see most of these cmdlets are designed to deal with objects in general. Note to cmdlet developers - pipeline bound parameters is how your cmdlets receive pipeline objects. When writing a cmdlet there is no $_. If your cmdlet wants to "participate" in the pipeline it must set the ParameterAttribute property ValueFromPipeline and/or ValueFromPipelineByPropertyName to true on at least one of its parameters. As mentioned above most ByValue parameters are of the InputObject (type psobject or psobject[]) variety so they pretty much accept anything. However not all cmdlets work that way. The -Id parameter (type [long[]]) on Get-History is pipeline bound ByValue. The follow Trace-Command output shows how PowerShell works hard when necessary to convert the input object's type to the expected type. In this case a scalar string value of '1' to an array of Int64:
Note that on the first attempt, PowerShell tries to convert the string to an array of Int64 and fails. Then it tries again by treating the input as psobject. It throws that psobject at an internal help class method LanguagePrimitives.ConvertTo() that successfully converts the string '1' to an Int64[] containing the value 1. When a parameter is both ByValue and ByPropertyName bound, PowerShell attempts to bind in this order:
There is more to the parameter binding algorithm like finding the best match amongst different parameter sets. BTW one last tidbit related to parameters. The PowerShell help topics aren't completely automatically generated and as a result they aren't always correct. For instance, look up the parameters on Get-Content and see if you find a -Wait parameter - you won't. :-) However the metadata is always complete and correct e.g.:
Hopefully this post has given you more knowledge about ByValue parameters and how to explore and get more information on cmdlet parameters in general. In summary, there actually isn't much you need to know about ByValue pipeline bound parameters because in most cases they just work intuitively. Just be sure to keep your eye out for those parameters that bind ByPropertyName. They are the ones whose pipeline bound usage isn't as obvious. April 06 Effective PowerShell Item 11: Understanding ByPropertyName Pipeline Bound ParametersEverybody likes to be efficient, right? I mean we all generally like to solve a problem in an efficient way. In PowerShell that usually culminates in a "one-liner". Honestly for pedagogical purposes I find it better much better to expand these terse, almost 'Obfuscated C' style commands into multiple lines. However there is no denying that when you want to bang out something quick at the console - given PowerShell's current line editing features - a one-liner helps stave off repetitive stress injuries. It's not PowerShell's fault. They're just using the antiquated console subsystem in Windows that hasn't changed much since NT shipped in 1993. One trick to less typing is to take advantage of pipeline bound parameters. Quite often I see folks write a command like:
That works but the use of the Foreach-Object cmdlet is technically unnecessary. Many PowerShell cmdlets bind their "primary" parameter to the pipeline. This is indicated in the help file for Get-Content as shown below: -path <string[]> Required? true <snip> -literalPath <string[]> Required? true
Note that there are actually four parameters on Get-Content that accept pipeline input ByPropertyName. Two of which are shown above. The other two are ReadCount and TotalCount. The qualifier ByProperyName simply means that if the incoming object has a property of that name it is available to be "bound" as input to that parameter. That is, if a type match can be found or coerced. For instance, we could simplify the command above by eliminating the Foreach-Object cmdlet altogether:
While it is intuitive that Get-Content should be able to handle the System.IO.FileInfo objects that Get-ChildItem outputs, it isn't obvious based on the ByPropertyValue rule I just mentioned. Why? Well the FileInfo objects output by Get-ChildItem don't have either a Path property or a LiteralPath property even accounting for the extended properties like PSPath. So how the heck does Get-Content determine the path of a file in this pipeline scenario? There are at least two ways to find this out. The first is the easier approach. It uses a PowerShell cmdlet called Trace-Command that shows you how PowerShell binds parameters. The second approach involves spelunking in the PowerShell assemblies using Lutz Roeder's .NET Reflector. Let's tackle this problem initially using Trace-Command. Trace-Command is a built-in tracing facility that shows a lot of the inner workings of PowerShell. I will warn you that it tends to be prolific with its output. One particularly useful area you can trace is parameter binding. Here's how we would do this for the command above:
This outputs a lot of text and unfortunately it is "Debug" stream text that isn't easily searchable or redirectable to a file. Oh well. The interesting output from this command are the following lines: BIND PIPELINE object to parameters: [Get-Content] This output has been simplified a bit to be more readable in this post. I also changed the initial command to output just a single FileInfo object to reduce the amount of output. The information we get from Trace-Command shows us that PowerShell tries to bind the FileInfo object to the Get-Content parameters and fails (NO COERCION) on all except for the LiteralPath parameter. OK well that tells us definitively how Get-Content is getting the path but it doesn't make sense. There is no LiteralPath property on a FileInfo object and there is no extended property called LiteralPath either. This is where the second technique of using .NET Reflector (download here) can be used to see a reverse compiled version of the PowerShell source. After starting .NET Reflector and loading the Microsoft.PowerShell.Commands.Management.dll assembly, we find the GetContentCommand and inspect the LiteralPath parameter shown below: [Alias(new string[] { "PSPath" }), Parameter(Position = 0, ParameterSetName = "LiteralPath", Mandatory = true, ValueFromPipeline = false, ValueFromPipelineByPropertyName = true)] public string[] LiteralPath { } Note the Alias attribute on this parameter. It creates another valid name for the LiteralPath parameter - PSPath which corresponds to the extended PSPath property on all FileInfo objects. That is what allows the ByPropertyName pipeline input binding to succeed. The property named PSPath matches the parameter name albeit via an alias. Where does that leave us? There are a number of cases where we can pipe an object directly to a cmdlet in the next stage of the pipeline because of pipeline input binding where PowerShell searches for the most appropriate parameter to bind that object to. Here is another example of piping directly to another cmdlet without resorting to the use of the Foreach-Object cmdlet:
You also now have a way to determine how PowerShell binds pipeline input to a parameter of a cmdlet. And thanks to Reflector we know that some parameters have aliases like PSPath to assist in this binding process. That's it for ByPropertyName pipeline input binding. There is another type of pipeline input binding called ByValue that I'll cover in a future post. November 24 Effective PowerShell Item 10: Understanding PowerShell Parsing ModesThe way PowerShell parses commands can be surprising especially to those that are used to shells with more simplistic parsing like CMD.EXE. Parsing in PowerShell is a bit different because PowerShell needs to work well as both an interactive command line shell and a scripting language. This need is driven by use cases such as:
Part and parcel with providing a powerful scripting language is to support more types than just the string type. In fact, PowerShell supports most .NET types including String, Int8, Int16, Int32, Decimal, Single, Double, Boolean, Array, ArrayList, StringBuilder among many, many other .NET types. That's very nice you say but what's this got to do with parsing modes? Think about this. How would you expect a language to represent a string literal? Well most folks would probably expect this representation: "Hello World" And in fact, that is recognized by PowerShell as a string e.g.:
And if you type a string at the prompt and hit the Enter key, PowerShell, being a very nice REPL environment, echoes the string back to the console as shown above. However what if I had to specify filenames using quotes as shown below?
That would immediately "feel" different than any other command line shell out there. Even worse, typing all those quotes would get really annoying, really fast. What to do, what to do? Well my guess is that the team, pretty early on, decided that they were going to need two different ways to parse. First they would need to parse like a traditional shell where strings (filenames, dir names, process names, etc) do not need to be quoted. Second they would need to be able to parse like a traditional language where strings are quoted and expressions feel like those you would find in a programming language. In PowerShell, the former is called Command parsing mode and the latter is called Expression parsing mode. It is important to understand which mode you are in and more importantly, how you can manipulate the parsing mode. Let's look at an example. Obviously we would prefer to type the following to delete files:
That's better. No bloody quotes required on the filenames. PowerShell treats these filenames as strings even without the quotes in command parsing mode. But what happens if my path has a space in it? You would naturally try:
And that works as you would expect. OK now what if I want to execute a program with a space in its path:
That didn't work because are far as PowerShell is concerned we gave it a string, so it just echoes it back to the screen. It did this because it parsed this line in expression mode. We need to tell PowerShell to parse the line in command mode. To do that we use the call operator '&' like so:
Tip: Help prevent repetitive stress injuries to your wrists and use tab (and shift+tab) completion for auto-completing the parts of a path. If the resulting path contains a space PowerShell will insert the call operator for you as well as surround the path with quotes. What's going on with this example is that PowerShell looks at the first non-whitespace character of a line to determine which mode to start parsing in. If it sees [_aA-zZ] or & or . or \ then PowerShell parses in Command mode. One exception to these rules happens when the line starts with a name that corresponds to a PowerShell language keyword like "if", "do", "while", etc. In this case, PowerShell uses expression parsing mode and expects you to provide the rest of the syntax associated with that keyword. The benefits of Command mode are:
So why do we need expression parsing mode? Well as I mentioned before it sure would be nice to be able to evaluate expressions like so:
It isn't a stretch to see how some shells might interpret this example as trying to invoke a command named '64-2'. So how does PowerShell determine if the line should be parsed in expression mode? If the line starts with a number [0-9] or one of these characters: @, $, (, ' or " then the line is evaluated in expression mode. The benefits of expression mode are:
One consequence of the rules for expression parsing mode is that if you want to execute an EXE or script whose name starts with a number you have to quote the name and use the call operator e.g.:
If you were to attempt to execute "64E1" without using the call operator, PowerShell can't tell if you want to interpret that as the number 64E1 (640) or execute the exe named 64E1.exe or the script named 64E1.ps1. It is up to you to make sure you have placed PowerShell in the correct parsing mode to get the behavior you want which in this case means putting PowerShell into command parsing mode by using the call operator. Note I have observed that if you specify the full command name e.g. 64E1.ps1 or 64E1.exe, it isn't necessary to quote the command. Now what if you want to mix and match parsing modes on the same line? Easy. Just use either a grouping expression (), a subexpression $() or an array subexpression @(). This will cause the parser to re-evaluate the parsing mode based on the first non-whitespace character inside the parens. Sidebar: What's the difference between grouping expressions (), subexpressions $() and array subexpressions @()? A grouping expression can contain just a single statement. A subexpression can contain multiple semicolon separated statements. The output of each statement contributes to the output of the subexpression. An array subexpression behaves just like a subexpression except that it guarantees that the output will be an array. The two cases where this makes a difference are 1) there is no output at all so the result will be an empy array and 2) the result is a scalar value so the result will be a single element array containg the scalar value. If the output is already an array then the use of an array subexpession will have no affect on the output i.e. array subexpressions do not wrap arrays inside of another array. In the following example I have embedded a command "Get-ChildItem C:\Windows" into a line that started out parsing in expression mode. When it encounters the grouping expression (get-childitem c:\windows), it begins parsing mode re-evaluation, finds the character 'g' and kicks into command mode parsing for the remainder of the text inside the grouping expression. Note that ".Length" is parsed using expression mode because it is outside the grouping expression, so PowerShell reverts back to the previous parsing mode. ".Length" instructs PowerShell to get the Length property of the object output by what was evaluated inside the grouping expression. In this case, it is an array of FileInfo and DirectoryInfo objects. The Length property tells us how many items are in that array.
We can do the opposite. That is, put expressions in lines that started out parsing in command mode. In the example below (admittedly lame) we use an expression to calculate the number of objects to select from the sequence of objects.
Using the ability to start new parsing modes, we can nest commands within commands. This a powerful feature and one I recommend mastering. In the example below PowerShell is happily parsing the command line in command mode when it encounters '@(' a.k.a. the start of an array subexpression. This causes PowerShell to re-evaluate the parsing mode but in this case it finds a nested command. One that grabs the new filename from the first line of the file to be renamed. I used the array subexpression syntax in this case because it guarantees that we will get an array of lines even if there is just one line. If you use a grouping expression instead and the file happens to contain only a single line then PowerShell will interpret the [0] to be "get me the first character in the string" which is "f" in the example below.
There is one final subtlety that I would like to point out and that is the difference between using the call operator (&) to invoke commands and "dotting" commands. Consider invoking a simple script that sets the variable $foo = 'PowerShell Rocks!. Let's execute this script using the call operator and observe the impact on the global session:
Note that using the call operator invokes the command in a child scope that gets thrown away when the command (script, function, etc) exits. That is, the script didn't impact the value of $foo in the global scope. Now let's try this again by dotting the script:
When dotting a script, the script executes in the current scope. As a result, the variable $foo in script.ps1 effectively becomes a reference to the global $foo when the script is dotted from the command line resulting in changing the global $foo variable's value. This shouldn't be too surprising since "dot sourcing", as it's also known, is common in other shells. Note that these rules also apply to function invocation. However for external EXEs it doesn't matter whether you dot source or use the call operator since EXEs execute in a separate process and can't impact the current scope. Here's a handy reference to help you remember the rules for how PowerShell determines the parsing mode.
Once you learn the subtleties of these two parsing modes you will be able to quickly get past those initial surprises like how you execute EXEs at paths containing spaces to putting these parsing modes work for you. September 29 Effective PowerShell Item 9: Regular Expressions - One of the Power Tools in PowerShellWindows PowerShell is based on the .NET Framework. That is, it is built using the .NET Framework and it exposes the .NET Framework to the user. One very nice feature of the .NET Framework is the Regex class in the System.Text.RegularExpressions namespace. It is a very capable regular expression engine. PowerShell uses this regular expression engine in a number of scenarios:
Obviously to get the most out of these operators and the Select-String cmdlet it helps to have a good grasp of regular expressions. PowerShell provides a help topic named "about_Regular_Expression" that you can view like so: PS C:\> help about_reg* This topic provides a nice quick reference on the various metacharacters in a regular expression but you are not going to learn a great deal about creating powerful regular expressions. To learn how to get the most out of regular expressions and hence PowerShell, I highly recommend Jeffrey Friedl's book Mastering Regular Expressions. Right now on the Amazon site it has 117 reviews and its rating is 4 1/2 stars out of 5. There is a shortcoming in PowerShell's support for regular expressions that you need to know about. Most other script languages support regular expression syntaxes where you can find all matches in a string. For example in Perl I could do this: $_ = "paul xjohny xgeorgey xringoy stu pete brian"; # PERL script Unfortunately the Select-String cmdlet doesn't have this feature - yet. So for now you can work around this limitation by using the System.Text.RegularExpressions.Regex class directly. Fortunately you don't have to type that long class name because PowerShell has a type alias: [regex]. Very convenient! PS C:\> $str = "paul xjohny xgeorgey xringoy stu pete brian" One thing to watch out for is when your regular expression is written to search across line boundaries. For instance, if you use Get-Content to grab the contents of a file to apply the regular expression against, keep in mind that Get-Content streams the file one line at a time. For regular expressions that operate across lines you will need to apply the regex to the file contents represented as a single string. In that case, I would do this: PS C:> $regex = (?<CMultilineComment>/\*[^*]*\*+(?:[^/*][^*]*\*+)*/) Note the use of the PowerShell Community Extensions cmdlet "Join-String" which takes the individual strings output by Get-Content and creates a single string separated by newline characters. Also note that this example shows the usage of a named capture: CMultilineComment. Now it would be even better if Select-String supported a "MatchAll" parameter that found all string matches in the specified file or string. That said, this example does show that when PowerShell is missing a feature, the access that it provides to the .NET Framework is a great escape hatch! If I have one beef with regular expressions it is that there are a number of engines and their support for various features and metacharacters varies. I'm especially annoyed that Visual Studio's regular expression find & replace doesn't use the .NET regular expression engine. I constantly have to switch mental contexts when moving between the two. Oh well, as long as you stay within PowerShell I think you will find that a good grasp of regular expressions will help you be more productive. September 24 Effective PowerShell Item 8: Output Cardinality - Scalars, Collections and Empty Sets - Oh My!In the last post Effective Powershell Item 7: Understanding "Output", we covered a lot about PowerShell output. However there is a bit more you need to understand to use PowerShell effectively. This post concerns the cardinality of PowerShell output. That is, when does PowerShell output a scalar versus a collection (or array) versus no output (empty set). In this post I use the term collection in a broad manner for various types of collections including arrays. Working with Scalars PS C:\> $num = 1 However you may be dealing with scalars when you think you are working with collections. For instance, when you send a collection down the pipe, PowerShell will automatically "flatten" the collection meaning that each individual element of the collection is sent down the pipe, one after the other. For example: PS C:\> filter GetTypeName {$_.GetType().Fullname} So in fact, the down stream pipeline stages do *not* operate on the original collection as a whole. The vast majority of the time, PowerShell's collection flattening behavior within the pipe is what you want. Otherwise, you would wind up with code like this to manually flatten the collection: PS C:\> foreach($item in $array){$item} | GetTypeName Note that this would require us to manually flatten every collection with the insertion of an extra foreach statement in the pipe. Since pipes are typically used to operate on the elements of a sequence and not the sequence as a whole, it is very sensable that PowerShell does this flattening automatically. However there may be times when you need to defeat the flattening. There's good news and bad news on this topic. First the bad news. Technically you can't defeat this behavior. PowerShell always flattens collections. The good news is that we can work around PowerShell flattening behavior by creating a new collection that contains just one element - our original collection. This sounds like it would be a real pain to do this but fortunately PowerShell provides us with a nice shortcut. For example this is how I would modify the previous example to send an array intact down the pipe and not each element: PS C:\> ,$array | GetTypeName The change is subtle. Notice the comma just before $array? That is the unary comma operator and it instructs PowerShell to wrap the object following it, whatever that object is, in a new array that contains a single element - the original object. So PowerShell is still doing its flattening work, we just introduced another collection to get the result that we wanted. Another feature of PowerShell that is somewhat unique with respect to scalar handling is how the foreach statement handles scalars. For example, the following script might surprise some C# developers: PS C:\> $vars = 1 This is because in languages like C#, the variable $vars would have to represent a collection (IEnumerable) or you would get a compiler error. This isn't a problem in PowerShell because if $vars is a scalar, PowerShell will treat $vars as if it were a collection containing just that one scalar value. Again this is a good thing in PowerShell otherwise if we wrote code like this: PS C:\> $files = Get-ChildItem *.sys Would need to modify it to handle the case where Get-ChildItem finds only one .SYS file. Our script code does not have to suffer the "line noise" necessary to do the check between scalar versus collection data shapes. Now the astute reader may ask - What if Get-ChildItem doesn't find *any* .SYS files? Hold that thought for a bit. Working with Collections PS C:\> $nums = 1,2,3+7..20 Sometimes you may always want to treat the result of some command as a collection even if it may return a single (scalar) value. PowerShell provides a convenient operator to ensure this - the array subexpression operator. Let's look at our Get-ChildItem command again. This time we will force the result to be a collection: PS C:\> $files = @(Get-ChildItem *.sys) In this case, only one file was found. It is important for you to know when you are dealing with a scalar versus a collection because both collections and FileInfo's have a Length property. I have seen this trip up more than a few people. Given that the unary comma operator always wraps the original object in a new array, what does the array subexpression operator do when it operates on an array? Let's see: PS C:\> $array = @(1,2,3,4) As we can see, in this case the array subexpression operator has no effect. Again the astute reader should be asking - what about the case where Get-ChildItem returns nothing? Working with Empty Sets
Seems simple right? Well these rules combine in somewhat surprising ways that can cause problems in your scripts. Here's an example: PS C:\> function GetSysFiles { } So far so good. GetSysFiles has no output so the foreach statement had nothing to iterate over. Let's try a variation. Let's say for sake of argument that our function took a long argument list and we wanted to put the function invocation on its own line: PS C:\> $files = GetSysFiles SomeReallyLongSetOfArguments Hmm, now we got output and all we did was introduce an intermediate variable to contain the output of the function. Honestly this violates the Principle of Least Surprise in my opinion. Let me explain what is happening. By using the temp variable we have invoked rule #2 - assigning to a variable results in our empty set being represented by $null in $files. Seems reasonable so far. Unfortunately our foreach statement abides by rule #3 so it iterates over the scalar value $null. Now PowerShell handles references to $null quite nicely. Notice that our string substitution above in the foreach statement didn't error when it encountered the $null. It just didn't print anything for $null. However, .NET framework methods aren't nearly as forgiving: PS C:\> foreach ($file in $files) { "Basename: $($file.Substring(2))" } Bummer. That means that you really need to be careful when using foreach to iterate over the results of something where you aren't sure whether the results could be an empty set and your script won't tolerate iterating over $null. Note that using the array subexpression operator can help here but it is crucial to use it in the correct place - again an issue with the language that shouldn't exist IMO. For example, the following placement does *not* work: PS C:\> foreach ($file in @($files)) { "Basename: $($file.Substring(2))" } Since $files was already set to $null, the array subexpression operator just creates an array with a single element - $null - which foreach happily iterates over. What I recommend is to put the function call entirely within the foreach statement if the function call is terse. The foreach statement obviously knows what to do when the function has no output. If the function call is lengthy, then I recommend that you do it this way: PS C:\> $files = @(GetSysFiles SomeReallyLongSetOfArguments) When you apply the array subexpression operator directly to a function that has no output, you will get an empty array and not an array with a $null in it. If you find this situation as confusing and error prone as I do, please feel free to vote on the following defect submission: Foreach should not execute the loop body for a scalar value of $null function ReturnArrayAlways {
$result = @()
# Do something here that may add 0, 1 or more elements to array $result
# $result = 1
# or
# $result = 1,2
,$result
}
In summary, watch out for how the foreach statement deals with the scalar value $null which can get synthesized automatically by PowerShell when a function has no output. September 16 Effective PowerShell Item 7: Understanding "Output"In shells that you may have used in the past, everything that appears on the stdout and stderr streams is considered "the output". In these other shells you can typically redirect stdout to a file using the redirect operator '>'. And in some shells like Korn shell, you can capture stdout output to a variable like so: DIRS=$(find . | sed.exe -e 's/\//\\/g') If you wanted to capture stderr in addition to stdout then you can use the stream redirect operator like so: DIRS=$(find . | sed.exe -e 's/\//\\/g' 2>&1) You can do the same in PowerShell: $Dirs = Get-ChildItem -recurse Looks about the same in PowerShell so what's the big deal? Well there are a number of differences and subtleties in PowerShell that you need to be aware of. Output is Always a .NET Object First, remember that PowerShell output is always a .NET object. That output could be a System.IO.FileInfo object or a System.Diagnostics.Process object or a System.String object. Basically it could be any .NET object whose assembly is loaded into PowerShell even your own .NET objects. Be sure not to confuse PowerShell output with the text you see rendered to the screen when you don't capture output. In Effective PowerShell Item 3: Know Your Output Formatters we covered this notion that when a .NET object is about to "hit" the host (console) PowerShell uses some fancy formatting technology to try to determine the best "textual" representation for the object. When you capture output to a variable, you are *not* capturing the text that was rendered to the host. You are catching the .NET object. Let's look at an example: PS C:\> Get-Process PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName Now let's capture that output and examine its type: PS C:\> $Proc = Get-Process PowerShell As you can see, a System.Diagnostics.Process object has been stored in $Proc and not the text that was rendered to the screen. But what if we really wanted to capture the rendered text? In this case, we could use the Out-String cmdlet to render the output as a string which we could then capture in a variable e.g.: PS C:\> $Proc = Get-Process PowerShell | Out-String Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName Another nice feature of Out-String is that it has a Width parameter that allows you to specify the maximum width of the text that is rendered. This is handy when there is wide output that you don't want wrapped or truncated to the width of your host. Function Output Consists of Everything That Isn't Captured I've seen this problem bite folks time and time again on the PowerShell newsgroup. It usually happens to those of us with programming backgrounds who are familiar with C style functions. What you need to be aware of is that in PowerShell, a function is quite a bit different. While a function in PowerShell does provide a separate scope for variables and a convenient way to invoke the same functionality multiple times without breaking the DRY principle, the way it deals with output can be confusing at first. Essentially a function handles output in the same way as any PowerShell script that isn't in a function. What the heck does that mean? Let's look at an example. For instance a programmer might look at this function definition: function foo { "hi"; read-host "press enter"; "there" } And expect it to prompt with "press enter" and then display "hi" and "there" but you would be wrong: PS C:\> foo there Even though you can think of "hi" and "string" as outputs of the function, those outputs are output "immediately". They aren't returned from the function and then output to the host or to a capturing variable. This is probably not surprising to those familiar with other shells but if your background is in programming it goes against your preconceived notions of what a function is. PowerShell also allows us to use a C style construct - the return statement - in a way that furthers this incorrect impression that PowerShell functions are like C functions e.g.: PS C:\> function bar { That should return us an array of System.Diagnostic.Process objects, right? We told PowerShell to "return $Proc". Let's check the output: PS C:\> $result | foreach {$_.GetType().Fullname} Whoa! Why is the first object System.String? Well a quick look at its value and you'll see why: PS C:\> $result[0] Notice that the informational message we thought we were displaying to the host actually got returned as part of the output of the function. There are a couple of subtleties to understand here. First, the return keyword allows you to exit the function at any particular point. You may also "optionally" specify an argument to the return statement that will cause the argument to be output just before returning. "return $Proc" does *not* mean that the functions only output is the contents of the $Proc variable. In fact this construct is semantically equivalent to "$Proc; return". The second subtlety to understand is this: The line: is equivalent to this line: That makes it clear that the string is considered part of the "output". Now what if we wanted to make that information available to the end user but not the script consuming the output of the function? Then we could have used Write-Host like so: PS C:\> function bar { Write-Host does not contribute to the output of the function. It writes directly to the host. This might all seem obvious now but you have to be diligent when you write a PowerShell function to ensure you get only the output you want. This usually means redirecting unwanted output to $null (or optionally type casting the expression with the unwanted output to [void]). Here's an example: PS C:\> function LongNumericString { Note that we don't *need* to use the return keyword like we do in C style function. Whatever expressions and statements that have output will contribute to the output of our function. In the function above, we obviously want the output of $strBld.ToString() to be the function's output. So what is the output? PS C:\> LongNumericString Capacity MaxCapacity Length Yikes! That is probably more than what you were expecting. The problem is that the StringBuilder.Append() method returns the StringBuilder object so that you can cascade appends. Unfortunately now our function outputs 20 StringBuilder objects and one System.String object. It is simple to fix though, just throw away the unwanted output like so: PS C:\> function LongNumericString { Other Types of Output That Can't Be Captured In the previous section we saw one instance of a particular output type - Write-Host - that doesn't contribute to the stdout output stream. In fact, this type of output can't be captured. The argument to Write-Host's -object parameter is sent directly to the host console bypassing the "stdout" output stream. So unlike stderr output that can be captured as shown below, Write-Host output doesn't use streams and therefore can't be redirected. PS C:\> $result = remove-item ThisFilenameDoesntExist 2>&1 Write-Host output can only be captured using the big stick - the Start-Transcript cmdlet. Start-Transcript logs everything that happens during a PowerShell session. If you need to create a comprehensive log file that captures everything then Start-Transcript is the only game in town. [Update: 05/25/2008 - Well except for one major hole. Transcripts don't capture any output from EXEs. Thanks to Shay for pointing that out.] Keep in mind that Start-Transcript is meant more for session logging than individual script logging. For instance, if you normally invoke Start-Transcript in your profile to log your PowerShell session, a script that calls Start-Transcript will generate an error because you can't start another transcript if one has already been started. You have to stop the previous one first. Here is the run down on the forms of output that can't be captured except via Start-Transcript:
If you happen to agree with me that this situation should be better in a future version of PowerShell, please feel free to vote on these two issues: Capture Warning, Verbose, Debug and Host Output Via Alternate Streams That's it. Just remember to keep an eye on what statements and expressions are contributing to the output of your PowerShell functions. Testing is always a good way to verify that you are getting the output you expect. September 04 Effective PowerShell Item 6: Know What Objects Are Flowing Down the PipeTo use Windows PowerShell pipes effectively, it really helps to know what objects are flowing down the pipe. Sometimes objects get transformed from one type to another. Without the ability to inspect what type is being used at each stage of the pipeline the results you see at the end can be mystifying. For example, the following question came up on the microsoft.public.windows.powershell newsgroup: Given a set of subdirs in a known directory, I need to cd into each directory and execute a command. One approach to solving this is: PS C:\> Get-Item * | where {$_.PSIsContainer} | push-location -passthru | That worked fine for my du utility because it works off the current directory. However in the spirit of experimentation I thought I would try specifying the full path. I was a bit surprised when it didn't work: PS C:\> Get-Item * | where {$_.PSIsContainer} | push-location -passthru | Du v1.31 - report directory disk usage No matching files were found. So what is going on here? Let's see how you could find out using our old friend Get-Member: PS C:\> Get-Item * | where {$_.PSIsContainer} | Get-Member TypeName: System.IO.DirectoryInfo Name MemberType Definition OK that is what I expected so far - DirectoryInfo objects. Let's look further down the pipe: PS C:\> Get-Item * | where {$_.PSIsContainer} | Set-Location -PassThru | Get-Member TypeName: System.Management.Automation.PathInfo Name MemberType Definition WTF! Set-Location took our DirectoryInfo objects and turned them into PathInfo objects and passed those down the pipe honoring my -PassThru parameter. However in this case, Set-Location didn't actually "pass through" the object. It gave us an entirely new object! You will notice that the PathInfo object doesn't have a Fullname parameter but it does have several path related parameters. I wonder which one we should use? Don't forget item 4 - know your output formatters (aka format-list * is your friend). Let's try it: PS C:\> Get-Item * | where {$_.PSIsContainer} | Set-Location -PassThru | Drive : Now that we can see the property values it is pretty obvious that the ProviderPath property is the one to use when passing the path to a legacy EXE. It is very doubtful that such an EXE would understand how to interpret the Path property. Note that in this example I also used Select -First 1 to pick off the first directory. This is handy if the command outputs a *lot* of objects. There's no use waiting for potentially thousands of objects to be processed when all you need is to see the property values for one of them. One thing to note about Get-Member for this scenario is that it outputs a lot of type member information that is just noise when all you want to know is the type names of the objects. Get-Member also only shows you the type information once for each unique type of object. This gives you no sense of how many objects of the various types are passing down the pipe. This information is easy to access via the GetType() method that is available on all .NET objects e.g.: PS C:\> Get-ChildItem | Foreach {$_.GetType().FullName} GetType() returns a System.RuntimeType object that has all sorts of interesting information. The property we are interested in is FullName. If I had used Get-Member instead I would have gotten about 125 lines of text surrounding the two lines indicating the type names. In fact this sort of filter is so handy that it is worth putting in your profile: PS C:\> filter gtn { if ($_ -eq $null) {'<null>'} else {$_.GetType().Fullname }} The PowerShell Community Extensions provides this filter however its implementation is a bit more robust. For instance, there are occasions when it is also important to know that *no* objects were passed down the pipeline. Our simple gtn (short for Get-TypeName) filter isn't so helpful here: PS C:\> @() | gtn We get no output which is perhaps a reasonable indication that no objects were output down the pipe. However with the PSCX implemention of this filter, we wanted to provide a bit more guidance in this situation e.g.: PS C:\> @() | gtn 126> ,@() | gtn -full In summary, when debugging the flow of objects down the pipe be sure to take advantage of Get-Member to show you what properties and methods are available on those objects. Use Format-List * to show you all the property values on those objects. And use our handy little filter gtn (aka Get-TypeName) to see the type names of each and every individual object passed down the pipe in the order that the next cmdlet will see them. Effective PowerShell Item 5: Use Set-PSDebug -Strict In Your Scripts - ReligiouslyWindows PowerShell is like most dynamic languages in that it allows you to use a variable without declaring its type and without having assigned to it. This is handy for interactive use, you can do stuff like this: PS C:\Temp> Get-ChildItem | Foreach -Process {$sum += $_.Name.Length} -End {$sum} Here $sum isn't a defined variable and yet we are adding a value to it and assigning to it. PowerShell just assumes a value of $null and coerces that 0 in the case above. Try this at the prompt: PS C:\Temp> $xyzzy -eq $null It is not likely that this variable is already defined somewhere. Of course we could verify that like so: PS C:\> Test-Path Variable:\xyzzy and indeed it isn't defined. So what has this to do with using Set-PSDebug -Strict in scripts - religiously? Well, once you get burned by an unfortunate typo that takes time to notice and time to track down, you will want a way to avoid repeating that mistake. Take this script for example: $Suceeded = test-path C:\ProjectX\Src\BuiltComponents\Release\app.exe if ($Succeeded) { This script has a problem with it that PowerShell won't tell you about. It will happily indicate that every build fails even though that may not be true. This is all because of a minor typo where I misspelled $Succeeded when testing the path. In this snippet, the typo may be obvious to you but when you have a several hundred line script file, typos aren't always so obvious. You can prevent this particular problem from ever happening by placing Set-PSDebug -Strict at the top of your script file just after the param() statement (if any). For example, given this script as FOO.PS1: Set-PSDebug -Strict if ($Succeded) { PS C:\Temp> .\foo.ps1 What would have happened if we had omitted the Set-PSDebug -Strict invocation? This script would have output "doh". NOTE: that in some cases we may need to initialize a variable in order to avoid the error above. This is a small price to pay to avoid this sort of problem. BTW the title of this post was perhaps a bit "over the top". There may very well be times not to use Set-PSDebug -Strict in your scripts. As always, use your judgment. There you have it. A simple way to avoid a major headache with debugging large scripts. Effective PowerShell Item 4: Commenting Out Lines in a Script FileOK the last couple of items have been long. I promise a short one here. Windows PowerShell doesn't provide multiline comments. Multiline comments come in handy when you need to comment out multiple lines in a script file. However there is a reasonable workaround. Use a here string. A here string allows you to enter multiple lines of text and prevent PowerShell from interpreting commands. However the extent of PowerShell's interpretation depends on which type of here string you use. For instance, in double quoted here strings, PowerShell expands variables and also execute subexpressions. This is an example of a double quoted here string e.g.: PS C:\> @" However a single quoted here string doesn't do this: PS C:\> @' Use the single quoted here string to comment out lines of script since it evaluates nothing in the contained string. Just note, the here string is an expression so if you do nothing more, the whole string will be emitted to the console. Usually you don't want that when you are commenting out code. All you need to do is cast the string to [void] (or redirect the string to $null): [void]@' This will effectively comment out those lines of script. NOTE: There are a couple of gotchas to be aware of with here strings. There can be *NO* whitespace after the initial @' character sequence. If there is one single space after this sequence you will get this cryptic error: Unrecognized token in source text. The other gotcha is that the closing '@ character sequence has to start in column zero otherwise you get this error message: Encountered end of line while processing a string token. The final gotcha to watch out for is that you can't nest here strings within another here string of the same ilk (single quoted or double quoted). What this means for our commenting out script scenario is that you won't be able to surround a chunk of script that uses a single quoted here strings with another single quoted here string to comment out that code. Effective PowerShell Item 3: Know Your Output FormattersI have mentioned previously that Windows PowerShell serves up .NET objects for most everything. Get-ChildItem (alias Dir) outputs a sequence of System.IO.FileInfo and System.IO.DirectoryInfo objects output. Get-Date outputs a System.DateTime object. Get-Process outputs System.Diagnostics.Process objects and Get-Content outputs System.String objects (or arrays of them based on how -ReadCount is set). You get the idea - PowerShell's currency is .NET objects. This isn't always obvious because of the way that PowerShell renders these .NET objects to text for display on the host console. Let's imagine for a moment that we had to figure out how to solve this problem ourselves. Our first approach might be to rely on the ToString() method that is available on every .NET object. That would work fine for some .NET objects e.g.: PS C:\> (get-date).ToString() But not so well for others: PS C:\> (Get-Process)[0].ToString() Hmm, that is certainly less than satisfying. Guess we need to think a little harder. OK let's not strain our brains. :-) Let's just look at how the PowerShell team solved this problem. They invented the notion of "views" for the common .NET types as well as a default view for any particular .NET type they provide a view for. You don't have to use the formatting cmdlets. If you don't specify a formatting cmdlet then PowerShell will choose a formatter based on the default view for a .NET type which could be tabular, list, wide or custom. Quick defintion break: Types for objects. The System.DateTime class is a .NET type, there is only one of these. The Get-Date cmdlet outputs an instance of this type a.k.a an object. There can be many DateTime objects based off the one definition of System.DateTime. PowerShell defines a view for the type that gets applied to all instances (objects) of that type. OK so what if PowerShell doesn't define a view for a .NET type? This is a certainty because the possible set of .NET types is infinite. I could create one right now called Plan9FromOuterSpace, compile it into a .NET assembly and load it into PowerShell. How's PowerShell going to deal with the type it isn't familiar with? Let's see: @' PS C:\> csc /t:library Plan9.cs Director Genre NumStars It seems that up to a certain number of public properties (IIRC 5), PowerShell will use a tabular view. If you more than that number of public properties then PowerShell falls back to a list view. OK back to the topic of views. There can be (and often is) multiple views defined for a single .NET type. These views are defined in XML format files in the PowerShell install directory: PS C:\> Get-ChildItem $PSHOME\*format* Directory: Microsoft.PowerShell.Core\FileSystem::C:\Windows\System32\ Mode LastWriteTime Length Name These views look like this: <View> <Name>process</Name> <ViewSelectedBy> <TypeName>System.Diagnostics.Process</TypeName> <TypeName>Deserialized.System.Diagnostics.Process</TypeName> </ViewSelectedBy> <TableControl> <TableHeaders> <TableColumnHeader> <Label>Handles</Label> <Width>7</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Label>NPM(K)</Label> <Width>7</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Label>PM(K)</Label> <Width>8</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Label>WS(K)</Label> <Width>10</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Label>VM(M)</Label> <Width>5</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Label>CPU(s)</Label> <Width>8</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Width>6</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader /> </TableHeaders> <TableRowEntries> <TableRowEntry> <TableColumnItems> <TableColumnItem> <PropertyName>HandleCount</PropertyName> </TableColumnItem> <TableColumnItem> <ScriptBlock>[int]($_.NPM / 1024)</ScriptBlock> </TableColumnItem> <TableColumnItem> <ScriptBlock>[int]($_.PM / 1024)</ScriptBlock> </TableColumnItem> <TableColumnItem> <ScriptBlock>[int]($_.WS / 1024)</ScriptBlock> </TableColumnItem> <TableColumnItem> <ScriptBlock>[int]($_.VM / 1048576)</ScriptBlock> </TableColumnItem> <TableColumnItem> <ScriptBlock> if ($_.CPU -ne $()) { $_.CPU.ToString("N") } </ScriptBlock> </TableColumnItem> <TableColumnItem> <PropertyName>Id</PropertyName> </TableColumnItem> <TableColumnItem> <PropertyName>ProcessName</PropertyName> </TableColumnItem> </TableColumnItems> </TableRowEntry> </TableRowEntries> </TableControl> </View> The XML definition above is of the "table view" for the Process type. It defines the column attributes of the view as well as the data that goes into each column, in some cases massaging the data into a more easily consumable value (KB vs bytes or MB vs bytes). Here is the "wide view" definition for the Process type: <View> <Name>process</Name> <ViewSelectedBy> <TypeName>System.Diagnostics.Process</TypeName> </ViewSelectedBy> <WideControl> <WideEntries> <WideEntry> <WideItem> <PropertyName>ProcessName</PropertyName> </WideItem> </WideEntry> </WideEntries> </WideControl> </View> In this "wide view" the only property that PowerShell will display is the ProcessName. In searching the DotNetTypes.format.ps1xml, we can find more definitions. The following StartTime "named view" isn't invoked by default, you have to specify it by name to the Format-Table cmdlet: <View> <Name>StartTime</Name> <ViewSelectedBy> <TypeName>System.Diagnostics.Process</TypeName> </ViewSelectedBy> <GroupBy> <ScriptBlock>$_.StartTime.ToShortDateString()</ScriptBlock> <Label>StartTime.ToShortDateString()</Label> </GroupBy> <TableControl> <TableHeaders> <TableColumnHeader> <Width>20</Width> </TableColumnHeader> <TableColumnHeader> <Width>10</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Width>13</Width> <Alignment>right</Alignment> </TableColumnHeader> <TableColumnHeader> <Width>12</Width> <Alignment>right</Alignment> </TableColumnHeader> </TableHeaders> <TableRowEntries> <TableRowEntry> <TableColumnItems> <TableColumnItem> <PropertyName>ProcessName</PropertyName> </TableColumnItem> <TableColumnItem> <PropertyName>Id</PropertyName> </TableColumnItem> <TableColumnItem> <PropertyName>HandleCount</PropertyName> </TableColumnItem> <TableColumnItem> <PropertyName>WorkingSet</PropertyName> </TableColumnItem> </TableColumnItems> </TableRowEntry> </TableRowEntries> </TableControl> </View> Why I am showing you all this? I think it is important to understand the "magic" behind how a .NET object - this binary entity - gets rendered into text on your host console. With this knowledge, you should never forget that you are dealing with .NET objects first and foremost. You also may be wondering if there is an easier way to figure out what views are available for any particular .NET type. There is if you have the PowerShell Community Extensions installed. PSCX provides a handy script provided by Joris van Lier called Get-ViewDefinition and you can use it like so: PS C:\> get-viewdefinition System.Diagnostics.Process Name : process Name : Priority Name : StartTime Name : process From this output you can see that there are quite a few views that you might not have been aware of related to the System.Diagnostics.Process .NET type that Get-Process outputs. Let's check out these alternate views: PS C:\> Get-Process | Format-Wide audiodg csrss
ProcessName Id HandleCount WorkingSet PriorityClass: Normal ProcessName Id HandleCount WorkingSet PriorityClass: High ProcessName Id HandleCount WorkingSet
ProcessName Id HandleCount WorkingSet StartTime.ToShortDateString(): 8/31/2007 ProcessName Id HandleCount WorkingSet StartTime.ToShortDateString(): 8/29/2007 BTW what if you have forgotten what formatters are available to you in PowerShell? Don't forget that you can use the first of the "big four" cmdlets, Get-Command like so: PS C:\> get-command format-* CommandType Name Definition You are probably already pretty familiar with Format-Table. It presents data in tabular format. This is the default format for many views including those for System.Diagnostics.Process and . Format-Wide is also pretty straight-forward. PowerShell displays a single property defined by PowerShell (ie the most interesting) in multiple columns. Format-Custom is interesting but probably not a formatter that you will use that often - it will be implicitly invoked for those .NET types that have custom views like System.DateTime: <View> <Name>DateTime</Name> <ViewSelectedBy> <TypeName>System.DateTime</TypeName> </ViewSelectedBy> <CustomControl> <CustomEntries> <CustomEntry> <CustomItem> <ExpressionBinding> <PropertyName>DateTime</PropertyName> </ExpressionBinding> </CustomItem> </CustomEntry> </CustomEntries> </CustomControl> </View> DateTime is a ScriptProperty that PowerShell that is defined like so: PS C:\> get-date | Get-Member -Name DateTime TypeName: System.DateTime Name MemberType Definition This brings me to my favorite formatter that I use when I'm spelunking PowerShell output. Notice that the Definition column above is truncated. Often when I want to see everything I will use the Format-List cmdlet. This formatter outputs the various property values on individuals lines so that data is rarely truncated e.g.: PS C:\> get-date | Get-Member -Name DateTime | Format-List TypeName : System.DateTime Now we can see the entire definiton of the DateTime ScriptProperty. NOTE: PowerShell often defines an abbreviated set of these property values to display by default with the Format-List cmdlet. It doesn't want you to be overwhelmed with information. However, when you're spelunking you want to see all the gory details. All you have to do to get all the property values is execute "format-list *". Check out the default list format for a Process object: PS C:\> (Get-Process)[0] | Format-List Id : 1284 versus what you get when you ask Format-List to give you everything: PS C:\> (Get-Process)[0] | Format-List * __NounName : Process See what I mean? Look at how much information you would have missed if you forgot that little 'ol "*"! In summary, if there is one and only one thing you get out of this long post please let it be this. "Format-List *" is the formatter to use when you want to look at all the property values of an object. September 03 Effective PowerShell Item 2: Use the Objects Luke. Use the Objects!Using Windows PowerShell requires a shift in your mental model for how command line shells deal with information. In most shells like CSH, Korn shell, BASH, etc you deal primarily with information in text form. For instance the output of ls or ps is captured into a string variable and cut, prodded and parsed to coax out the required piece of information. As it turns out, PowerShell provides very handy text manipulation functions like:
Note that by default, PowerShell treats all text (actually System.String objects) case-insensitive when doing things like a comparison or a regular expression search or replace. Because of these handy string manipulation features, it is very easy to "fall back" into the old way of string cutting, parsing and string comparisons. Sometimes this is unavoidable even in PowerShell but many times you can just use the object provided to you. The benefits are often:
Let's look at an example. The following issue came up in the public.microsoft.windows.powershell newsgroup recently. How do you test the output of dir a.k.a. get-childitem to filter out directories leaving only the files to be operated on further down the pipeline? Here's an approach to this problem that I think of as "falling back" into the old ways: PS C:\Windows\System32> get-childitem | where-object {$_.mode -ne "d"} First let me point out that this command doesn't work but more importantly it relies on string comparisons to determine whether or not an item passing down the pipeline is a folder. If you are bent on doing the filtering the "old way" then the following will work however vis-a-vie the previous solution it illustrates how easy it is to get the string comparison wrong: PS C:\Windows\System32> get-childitem | where-object {$_.mode -notlike "d*"} Yet there is a better approach for this type of problem - the PowerShell way. PowerShell decorates every item that is output by the Get-ChildItem and *-Item CMDLETs with additional properties. This is even independent of which provider is being used - file system, registry, function, etc. We can see those extra properties, all of which are prefixed with PS, by using our old friend Get-Member like so: PS Function:\> new-item -type function "foo" -value {} | gm TypeName: System.Management.Automation.FunctionInfo Name MemberType Definition One of those extra properties is PSIsContainer and this property tells us that the object is a container object. For the registry, this means RegistryKey and for the file system it means directory (DirectoryInfo object). So this problem can be solved more directly like so: PS C:\Windows\System32> get-childitem | where-object {!$_.PSIsContainer} That is a bit less to type and is much less error prone. However what about this performance claim? OK let's try both of these approaches (I'll also throw in the regex-based -notmatch) and measure their performance: PS C:\Windows\System32> OK so what are the results: PS C:\Windows\System32> $oldWay1 | measure-object TotalSeconds -ave Count : 1 PS C:\Windows\System32> $oldWay2 | measure-object TotalSeconds -ave Count : 1 PS C:\Windows\System32> $poshWay | measure-object TotalSeconds -ave Count : 1 So doing a little math - in PowerShell - we get: PS C:\Windows\System32> "{0:P0}" -f (169.26 / 61.53) Yikes! The string comparison approach using the Mode property is over 275% slower than using the PSIsContainer property. With PowerGadgets we can see this: PS C:\> $data = @{
PowerGadgets are pretty sweet. I use them a lot in presenting various reports to my management chain. This is off topic but I have one chart that displays the checkin activity per day. It is interesting to see the spike in checkins just before each iteration milestone is reached. :-) In summary, keep in mind that even though the PowerShell console output gives you the illusion that you are only dealing with text, there are .NET objects behind all that text output! You are often dealing with objects richer in information than System.String and many times those objects have just the information you are looking for in the form of a property. You can then extract that information without resorting to text parsing. For an additional example of operating object properties vs text, check out my post on Sorting IPAddresses the PowerShell Way. Effective PowerShell Item 1: The Four Cmdlets That are the Keys to Finding Your Way Around PowerShellI have been a big fan of the Effective series of books over the years from Effective COM to Effective XML. Without trying to be too presumptuous, I thought I would capture some of the tidbits I've picked up over the last couple of years using Windows PowerShell interactively and writing production build & test scripts. This first item is pretty "basic" and I debated whether or not it belongs in an "Effective PowerShell" article. In the end, these four cmdlets are so critical to figuring out for yourself how to make PowerShell work for you that I thought it was worth it. Unfortunately this is a long post. I'm going to try hard to keep my future Effective PowerShell posts much shorter than this first one. The following four CMDLETs are the first four that you should learn backwards and forwards. With these four simple-to-use cmdlets you can get started using PowerShell - effectively. #1. Get-Command - This CMDLET is the sure cure to the blank, PowerShell prompt of death. That is, you just installed PowerShell, fired it up and you're left looking at this:
Now what? Many applications suffer from the "blank screen of death" i.e. you download the app, install it and run it and now you're presented with a blank canvas or an empty document. Often it isn't obvious how to get started using a foreign application. In PowerShell, what you need to get started is Get-Command to find all the commands that are available from PowerShell. This includes all your old console utilities, batch files, VBScript files, Perl files, etc. Basically anything that is executable can be executed from PowerShell. Of course, you didn't download PowerShell just to run these old executables and scripts. You want to see what PowerShell can do. Try this: PS C:\Users\Keith> get-command CommandType Name Definition By default, get-command list all the CMDLETs that PowerShell provides. Notice that Get-Command is one of those CMDLETs. Get-Command can list more information but how would you figure that out? This brings us to the second command you need to know and will be using frequently in PowerShell. #2. Get-Help - This CMDLET will provide information on what a CMDLET does, what parameters it takes and usually it will include examples of how to use the command. It will also provide help on general PowerShell topics like globbing and providers like Registry and FileSystem. Say you want to know what *all* the help topics are in PowerShell - easy - just do this: PS C:\Users\Keith> get-help * Name Category Synopsis And if you only want to see the "about" help topics try this: PS C:\Users\Keith> get-help about* Name Category Synopsis Now, let's try Get-Help on Get-Command and see what else we can do with Get-Command: PS C:\Users\Keith> get-help get-command -detailed NAME SYNOPSIS PARAMETERS -verb <string[]> -noun <string[]> -commandType <CommandTypes> TIP: you will want to use the -Detailed parameter with Get-Help otherwise you get very minimal parameter information. Hopefully in PowerShell v.next they will fix the "default view" of CMDLET help topics to be a bit more informative. There's a couple things to learn from the help topic. First, you can pass Get-Command a commandType to list other types of commands. Let's try this to see what PowerShell functions are available by default: PS C:\Users\Keith> get-command -commandType function CommandType Name Definition Excellent. We could do the same for filters, aliases, applications, etc. Also note that Get-Command allows you search for CMDLETs based on either a Noun or a Verb. There's a more compact form that most of the PowerShell regulars use instead of these parameters though: PS C:\Users\Keith> get-command write-* CommandType Name Definition You can swap the wildcard char to find all verbs associated with a particular noun (usually the more useful search): PS C:\Users\Keith> get-command *-object CommandType Name Definition Finally, we can pass a name to Get-Command to find out if this name will be interpreted as a command and if so, what type of command: cmdlet, function, filter, alias, externalscript, script or application. In this usage, Get-Command is like the Unix 'which' command on steriods. Let me show you what I mean: PS C:\Users\Keith> get-command more CommandType Name Definition Note that PowerShell tells me not only the location of applications like more.com, it also tells me what type of command each is (function vs application) as well as the functions defintion and the priority order of the commands. In this case, PowerShell will execute its 'more' function if you were to use the command 'more'. [Update 11/16/07: The output order is does *not* indicate the priority order in which PowerShell will execute commands with the same name. This is disappointing]. If you wanted to use the Windows executable, you would need to use the command 'more.com'. However there is even more information to be found here that meets the eye. This brings us to our third and final important cmdlet to become familiar with. #3. Get-Member - The single biggest concept that takes a while to sink in with most people using PowerShell for the first time is that just about *everything* is (or can be) a .NET object. That means when you pipe information from one CMDLET to another it quite often isn't text and if it is, it is still an object. To be specific, it is a System.String object. However, quite often it is some other type of object and being new to PowerShell, quite often you won't know what type of object it is or what you can do with that object. Let's take a further look at what information (ie objects) Get-Command outputs. In order to do this, we will use Get-Member like so: PS C:\Users\Keith> get-command more.com | get-member TypeName: System.Management.Automation.ApplicationInfo Name MemberType Definition Well now, isn't this interesting. Unlike the Unix 'which' command that only gives us the path to the application, here we get a bit more information. Let's examine the FileVersionInfo on this command: PS C:\Users\Keith> get-command more.com | foreach {$_.FileVersionInfo} ProductVersion FileVersion FileName This is just an inkling of the power of being able to access objects instead of unstructured information like plain text. Get-Member is also very handy for discovery what properties and methods are available on .NET classes. PS C:\Users\Keith> get-date | get-member TypeName: System.DateTime Name MemberType Definition You can also find out information about static properties and methods like so: PS C:\Users\Keith> [System.Math] | get-member -static TypeName: System.Math Name MemberType Definition #4 Get-PSDrive - Next to "everything is an object" the next biggest notion to digest in PowerShell is that the file system is one of many stores than can be manipulated by many of the same cmdlets you use to manipulate the file system. First, how do you find out which drives are available in PowerShell? Why use the Get-PSDrive command: PS C:\> Get-PSDrive Name Provider Root CurrentLocation All these drives can be manipulating using same cmdlets you use to manipulate the file system. What are those? Use Get-Command *-Item* to find out: PS C:\> Get-Command *-Item* CommandType Name Definition There you have it. The four CMDLETS that you *need* to know to really find your way around Windows PowerShell. Get-Command to find out what commands/functionality is available. Get-Help to find out how to use that functionality. Get-Member to figure out what information and functionality is available on those .NET objects you'll be dealing with in PowerShell. And Get-PSDrive to find out which stores you can operate on besides the obvious one (the file system). Comments are welcome. Update: Added Get-PSDrive based on Jeffrey's comment. |
|
|
