Get-ChildItem -ne dir

For the past little while I’ve had many opportunities to be able to speak in front of a lot of IT professionals (both administrators and developers) about PowerShell. This has included touring with the EnergizeIT Certification Bootcamp User Group Tour and presenting at various local user group events here in Ottawa. It also included helping out a little at the PowerShell demo station at the IT Pro week of TechEd 2008. All of this has been great fun because I really love being able to talk face-to-face with IT professionals and help them with their problems (I guess sitting in a cubicle for 10 years writing code must have gotten to me).

During these presentations, one (of several) common messages that I have been delivering is this:

If you go into cmd.exe to run some command, do it in PowerShell instead.

In general, this recommendation works well because you can draw from skills you’ve acquired while using cmd.exe and apply those directly in PowerShell. These commands don’t work exactly the same way they did outside of PowerShell, but in most cases you won’t notice and you can start getting comfortable using the PowerShell console instead of cmd.exe.

What about the cases where you will notice that one of the commands that you know and use doesn’t function the same way in PowerShell? Let’s look at an example of a very common cmd.exe command that either doesn’t work in PowerShell in many cases without modification or that doesn’t give you the results you were looking for in others. The command I’m talking about is the dir command. Dir is a good example to use to illustrate this for several reasons:

It is often the first command that anyone will try in PowerShell when they open it for the first time if they haven’t seen demonstrations showing all of the cool commands like Get-Service, Get-Process, Get-QADUser, etc. (aside from help, but what else are you going to try in a command shell you’re not familiar with where your current directory is somewhere in the file system?).
It has a ton of command-line arguments to allow you to do some really complex directory searches on the file system with a very pithy command syntax.
It outputs some useful details and aggregate information that is not part of the list of objects returned.
It isn’t a standalone application that can be simply run from PowerShell.

Assume for example that you want to perform a recursive directory search for all files with a certain extension. In cmd.exe, you would use a command syntax similar to this (varying on the extension, of course):

dir /s *.ps1

Running this command as is inside of PowerShell results in an error because the Get-ChildItem command (for which dir is an alias) doesn’t have a /s parameter. All parameters in PowerShell are prefixed with a dash (-) instead of a slash (/), and the parameter for recursion in Get-ChildItem is -recurse (or -r), something that /s doesn’t necessarily translate to very intuitively. Still, the help documentation you get from help dir is comprehensive, so you can quickly discover the -recurse parameter that way. So now we have this:

dir -r *.ps1

When you run this in PowerShell, you won’t get an error anymore, but you will not likely get the results you expect either. Personally, I know this has caused me to do some head-scratching a number of times. The only ps1 files that will be listed are those that are in your current directory and those that are in a subdirectory (recursive) that ends with “.ps1”. In other words, you most likely won’t get any results from this command. Another visit to the help file and looking at the examples reveals that you actually meant to pass *.ps1 as the filter, not the path, so you need to do this:

dir -r -fi *.ps1

That’s not quite the same syntax as dir /s *.ps1 and it will definitely take some getting used to. Also, if you were looking for the total amount of space consumed on the hard drive by these sorts of files like you would get in the results from cmd.exe, you won’t find that in PowerShell either. This can be quite frustrating, especially to the newcomer.

Here’s another scenario: what if you want to do something simple like view all files in the current directory that are hidden? It should be simple, right? Here’s the cmd.exe syntax for that command:

dir /a:h

This command will also raise an error in PowerShell. Once you get past the error and you learn the correct syntax, you’ll discover that the syntax in PowerShell, is a little more complicated, like this:

dir -fo | ? { $_.Attributes -band 2 }

Please note that the value of 2 is actually the integer value of [System.IO.FileAttributes]::Hidden and the ? is an alias for the Where-Object cmdlet. In practice I would use the [System.IO.FileAttributes]::Hidden enumeration instead of the value of 2 because I don’t have the attribute values memorized, but I am using pithy commands as short as I can make them to illustrate a point.

In both of these cases, as well as every other case I could come up with using dir, the old cmd.exe dir command syntax is shorter and it produces more information. Plus, like many PowerShell users who have been using cmd.exe for a while, I already know the switches that are available in dir today. There are a ton of cases like this because dir has so many switches that it supports, and these switches can be combined in many different ways to produce very useful results.

There are other issues with applying your knowledge of the dir command within PowerShell as well. For example, with Windows Vista and Windows Server 2008, the dir command had some new switches added to it:

/r to show alternate file streams
/a:i to show files that are not content indexed
/a:l to show reparse points

Each of these switches works in Windows Vista and Windows Server 2008 but they don’t work in Windows XP or Windows Server 2003. And by default, they don’t work in PowerShell either.

What do you do when facing differences like this that make it harder for you to get what you need from PowerShell? Well, there are three options to choose from:

Run back to cmd.exe when working with the file system because it already works (if it ain’t broke, don’t fix it).
Translate the dir commands you use into PowerShell dir (or Get-ChildItem or gci) syntax and use them.
Find a Poshoholic and ask him to help.

Personally I recommend the third option. 🙂

If you choose the first option you’re not learning PowerShell, you’re going back to oldschool cmd.exe (yuck!), you’re not getting rich .NET objects that you can work with in a pipeline, and you’re not getting support for the newer dir switches in downlevel operating systems like Windows XP and Windows Server 2003. If you choose the second option, while that’s an admirable choice, there may be more work there than you think. Really, the third option is the best. And if you go with the third option, here are the sort of results you are going to get:

Over the last little while I’ve slowly put together a set of PowerShell extensions that will allow you to have full dir support in PowerShell like what is shown above on Windows XP, Windows Vista, Windows Server 2003 and Windows Server 2008, whether you’re running 32-bit or 64-bit. This includes supporting for the following:

Writing the PowerShell pipeline equivalent of dir to the host, regardless of which switches are used (this can be disabled).
Full alternate file stream (AFS) support on demand; this includes retrieving alternate file streams, blocking or unblocking files, and adding or removing alternate data streams on any file or folder. Even on Windows XP and Windows Server 2003 where dir in cmd.exe doesn’t support retrieving this information!
Filtering options for files that are not content indexed and showing reparse points (not to mention any other attribute filters that are supported by dir) on all platforms supported by PowerShell.
Recognition of and support for the dircmd environment variable.
Support for every dir switch that is available today.
Outputting detailed header and footer information just like you get from dir in cmd.exe.

See that green block of text in the screenshot? That’s tutorial information, showing you the dir command you typed as well as the equivalent PowerShell command. This is output no matter what your dir command is, unless you disable it by running “$PSTutorialDisabled = $true”. Want the tutorial back? Just remove the $PSTutorialDisabled variable or set it to $false. Also if you noticed, the screenshot output includes detailed header and footer information plus integrated alternate file stream details like you get in dir. That output is controlled by a script I wrote called Process-FileSystemChildItem (alias: pfsci), which you can see being called in the PowerShell equivalent script generated by the tutorial. This modular support for outputting header and footer details as well as alternate file streams allows you to use Get-ChildItem and pipe the results to Process-FileSystemChildItem, selecting which output options are important to you.

What if you want to work with alternate file streams? Looking at that list of files in the output above, removing the alternate file streams and showing header and footer information with the results is as simple as running this script:

gci *.ps1 `
| % { if ($_.IsBlocked) { $_.Unblock() } } `
| pfsci -showAlternateFileStreams

Want to block a file or folder? Just do this:

(Get-Item $myItem).Block()

How about setting your own alternate file stream on a file or folder? Here’s that syntax:

(Get-Item $myItem).WriteAlternateFileStream(‘Secret message’,’Poshoholic was here.’)

To retrieve the contents of that stream, it’s as simple as this:

(Get-Item $myItem).AFS[‘Secret message’].GetContents()

If either the true dir support or the AFS support interests you, you’ll need to download a few files and import them into PowerShell. The required files along with their details for importing them into PowerShell are as follows:

ImportDirCmd.ps1
Requirements: dir.ps1, Process-FileSystemChildItem.ps1, Get-PSResourceString.ps1, FileStreams.types.ps1xml, and FileStreams.format.ps1xml

This file contains the required commands to load all of this functionality into PowerShell, provided that all items are in the same folder. To use this functionality in PowerShell, simply dot-source this file after you have downloaded it and all required files. This is the easiest way to extend PowerShell using this functionality.

dir.ps1
Requirements: Process-FileSystemChildItem.ps1

This file contains the script that processes the dir command you enter, parses it, generates the equivalent Get-ChildItem pipeline, outputs the tutorial information to the host and executes the command. To use this command, simply invoke the script file directly using the call operator or dot-source the file and use the dir alias it creates.

Process-FileSystemChildItem.ps1
Requirements: FileStreams.types.ps1xml, FileStreams.format.ps1xml, and Get-PSResourceString.ps1

This file contains a script that supports outputting detailed header and footer information with pipelined file system items as well as alternate file stream information. If the required type data and format data files are automatically loaded into the PowerShell session if they haven’t been loaded already. To use this command, simply invoke the script file directly using the call operator or dot-source the file and use either the Process-FileSystemChildItem or the pfsci alias it creates.

Get-PSResourceString.ps1
Requirements: None

This file contains a script that supports loading localized resources to be used in PowerShell scripts. This is a utility command often used when making parameters required, and therefore this file must either be placed in your path or it must be dot-sourced to create the Get-PSResourceString and grs aliases. I use this internally when reporting certain errors back to the host, and I always call it by name without a path.

FileStreams.types.ps1xml
Requirements: None

This file contains the xml definitions for extending the PowerShell types to include types for alternate file streams, as well as extensions for FileInfo and DirectoryInfo objects so that they support file streams. To use these extensions, import the file as follows:

Update-TypeData .\FileStreams.types.ps1xml

If you don’t update the type data manually, when you call Process-FileSystemChildInfo the type data will be updated automatically as long as the file is in the path or in the same directory as the Process-FileSystemChildInfo.ps1 script.

FileStreams.format.ps1xml
Requirements: None

This file contains the xml definitions for formatting alternate file streams in PowerShell. To use this formatting, import the file as follows:

Update-FormatData -PrependPath .\FileStreams.format.ps1xml

You must use -PrependPath to import this file correctly. If you don’t update the format data manually, when you call Process-FileSystemChildInfo the format data will be updated automatically as long as the file is in the path or in the same directory as the Process-FileSystemChildInfo.ps1 script.

Once you’ve downloaded these files, unblocked them and imported them into PowerShell, dir should work as well for you (better in some cases) as it does in cmd.exe, and you should have additional management support for blocked files and alternate file streams in general through PowerShell itself. And hopefully, you’ll learn more about PowerShell along the way!

Thanks for reading,

Kirk out.

P.S. Thanks to /\/\o\/\/ (Marc van Oursow) for the work he did with alternate file streams in this post and for the related files he included in PowerTab. This work was my starting point for the support for alternate file streams. My extension here differs slightly from his in that I don’t use a dll (this allows me to support both 32-bit and 64-bit platforms), my method signatures are slightly different and I added support for folders since they can also have streams added to them, but his work gave me a big head start on this.