To demonstrate this, I wrote a simple Out-Grid script. But then I got carried away, and wrote the script I’ve shown in this screenshot. The resulting script not only illustrates how to code WPF in PowerShell without XAML, it also illustrates one of the few areas where you’re much better off loading from XAML than writing the plain code — and that’s a DataTemplate. It is possible to write them in code, but believe it or not, some of their features are accessible only from XAML.

I’ve updated both the script and the screenshot to correct a bug I noticed last night after I posted this … so if you tried this and got a lot more columns than you had bargained for … here is the Select-Grid script again. I updated it again just now to switch my Set-PsDebug statement for a Set-StrictMode statement, after reading Jeffrey Snover’s post about strict mode best practices.

I’m not going to paste the whole script in-line, but I thought I’d paste some of it here so that I could give a little explanation of what’s happening, in case you need a little help figuring it out…

Using modules …

Some of you may know that normally in a script like this we would put the “utility” functions inside the BEGIN block so-as to encapsulate them from your main runspace, and may be wondering why I didn’t in this case. It’s because the new CTP2 of PowerShell has this concept called a “module” ... which is somewhat like a script snapin — basically it allows you to have functions in the script which don’t end up in the main runspace, but which are still available to the other functions (or cmdlets, in this case) in the script.

I will write a separate post about how PowerShell Modules work, and what you can do with them … it’s too complicated to get into here. Suffice it to say that all I had to do to the script is add a line at the bottom: Export-ModuleMember Select-Grid and rename it to Select-Grid.psm1 and put it in a specific location: Documents\WindowsPowerShell\Packages\Select-Grid\Select-Grid.psm1 — but of course, I couldn’t resist cleaning it up a bit as I was writing about it (if you grabbed it before v3.4, you should grab it again — look in the comment at the top).

Having done that, all you have to do is run Add-Module Select-Grid instead of dot-sourcing it, and then run it as before (see the screenshot).

Let’s talk about code bay-bee …

There’s a few things I wanted to point out in the module’s code, so lets get to that. The first thing is that the main code is in a cmdlet, rather than a function — mostly because the cmdlet automatically handles both command arguments and pipeline arguments and allows me to handle them both the same way. Since I want to handle all of the input at once, my BEGIN and PROCESS blocks are basically empty, serving only to collect the inputs.

One caveat I will point out: The CTP has a problem where it strips the ETS attributes from things when you specify the type. So if you write a cmdlet with a parameter types like [System.IO.FileSystemInfo], and then add data to them with Add-Member, that data won’t show up in the script cmdlet. Hopefully this will be considered an important bug and will be fixed in the next CTP/Beta. The workaround in the meantime is to just use [PSObject] when you want to get the ETS attributes.

So, lets review the important bits of this …

This constructs the window, and the only things I’ll point out here is that I used SizeToContent so that the window would automatically adjust it’s size, and I put the ListView and GridView directly into their containers, instead of assigning them to variables first. It might help you to have a $grid or a $list variable to work with in the rest of the code (eg: instead of $window.Content.View = new...GridView, you’d be doing $list.View = $grid), but since this is PowerShell and not C#, I don’t end up having to manually cast things to use their specific properties, so this actually keeps my code cleaner. In C# this would be a mess, because the View property is only a property of a ListView type, so you would have to cast the $Window.Content to a ListView in order to use that property, and then … well, lets just say the last line of that code would end up something like this (assuming you were using the namespaces and didn’t have to type them out):

The next interesting feature of this code (at least, in my opinion) is the Get-PropertyTypes function — I won’t elaborate much here, but the purpose of this code is to get a hash of the property names and types when the user specifies a list of properties to show. The main reason I did this that I was having problems sorting columns with missing values, so I go through the values and add a NoteProperty with an appropriate default (for which I need to know the variable’s type).

We then construct columns for each property we want to bind to. This could be drastically simplified if we didn’t need the sorting, but since we do, it looks like this:

That block only has one thing worth mentioning that might not be clear from the comments: to avoid double-sorting the data, we have to Clear() the SortDescriptions before we add a new one (otherwise it sorts when we add, and then sorts again when we remove the old SortDescription). Since we need to know the direction that the current sort is in, I refactored it into a module-level variable, and wrote a New-SortDescription function which creates the SortDescription based on that … allowing me to clear without first capturing the current sort direction, and then add the SortDescription straight to the GridView. Script modules rock — they are essentially a “class” semantic for PowerShell, with private member variables and everything.

The last thing I should write about is the CellTemplate magic. If you pass a Graph parameter to the cmdlet, it puts a custom CellTemplate on each column you name. If you specified the Properties parameter, you have to be careful to only specify column names which you also included there, and in general, they have to be numeric columns in order for this to work.

There’s really only three lines of code here (not counting the Xaml), so lets review them. First we add a “PropertyPercent” NoteProperty to each output object for each “Property” that we want to graph, and populate it with the appropriate value. Then, we find the appropriate column in the GridView that we’ve already set up — and remove it’s DisplayMemberBinding. If we don’t remove the binding, the CellTemplate has no effect.

Finally, we add the CellTemplate. The magic is that the cell template has a colored Rectangle behind a TextBlock, and uses a ScaleTransform — bound to the “PropertyPercent” NoteProperty we created earlier — to scale the width of the Rectangle. I can’t stress enough that this is just one of hundreds of possible visualizations you could use, so let me give you a few ideas, and then you should go find a friend that’s an artist or a designer and get them to spend some time playing with Expression Blend …

1. You could have a DataTransform that converted numbers to colors, and bind the TextBlock’s BackgroundBrush to that so each cell is simply colored differently (eg: to color cells from red to blue based on a temperature value).
2. You could databind the FontSize of a TextBlock based on a numeric value in a non-displayed property, so you could show words with relative size (like a “Tag Cloud”).

1. You could databind the Angle property of the RotateTransform on a pair of lines or shapes to create an analog clock to display times

So many possibilities …

I came up with two really obvious ideas which I think are both good demonstrations of useful things to do from PowerShell, and are good examples of something that really just doesn’t work with WinForms.

User Input prompts

I’ll write more about this in future posts, but for now, take as an ultimate example the latest post from mow, The PowerShell Guy in which he rewrites his PowerShell WMI Explorer to be WPF based — it seems to not only run faster, but be based on less code (of course, that might just be because he’s gained experience since the first version).

Data-bound Graphs

There are dozens of ways you can do data-bound graphs in PowerShell — including 3d — but the simplest to demonstrate (and coincidentally the easiest for me to come up with a use-case for) is a plain bar graph. I’ve written a simple graph window in XAML, and created a script Out-BarGraph which lets you send data to it … but there are, as the Genie says, some caveats, provisos, addendums, and quid pro quos.

The main catch is that you have to specify the ScriptBlock parameters so that the script can figure out which properties to use as the Labels and Values — the purpose of this script is not to provide the most efficient way to bind PowerShell data to WPF, but rather to bind the data in a way that is easily translatable to new data types — because of this, you can use the script with file sizes, web traffic logs, performance monitor data, etc.

The second catch is that we export the data to a temp file. In order to make it easy to handle multiple data-types, the WPF actually databinds to XML which we create by using PowerShell’s built in Export-CliXml cmdlet. The only constraint that whatever is exported must have three specific properties (Label, Value, Percentage) which the Out-GraphableXml function in the script calculates using script blocks you provide. I chose to do this so that you could see that you could create the xml from anywhere easily … but you could choose to databind to actual objects instead.

Finally, there are a few additional constraints. This bar graph doesn’t update itself — it’s just a static graph of a given set of data. It can’t represent negative numbers. You must provide the percentage attribute as a number between 0 and 1 (again, in my example script the Out-GraphableXml function in the script calculates the percent based on the largest value).

The Script

Having laid out the shortcomings of the script, let me present it to you here in full glory. Unlike the downloadable version linked above, this script includes the XAML source in-line as a Data block, so the entire script and UI code are in a single file. Scroll to the end of the script for some explanations…

Some XAML Tips

I learned a few things about XAML markup while doing this.

1. If you bind to an XML data source that’s in-line in your XAML, you do so using the x:XData element, and then a single root element inside that. You must specify a blank xmlns parameter on that root element, or it won’t work. However, when you bind to an eternal XML document, as in our case — you need to specify the XML namespaces using a XmlNamespaceMapping collection — and you must use a prefix, and then repeat that prefix throughout your Xaml whenever you specify an XPath. However, attributes don’t require the prefix (I’m not actually sure why) so in the code above I simply used wildcards for practically every element.
2. When you specify attribute tests (like /Node[attribute='value']) in binding markup, you get an error because of the equals sign and quotes, but you can just escape them with a backslash, or you can use a Binding@ element and put the test in the XPath attribute (which doesn’t need escaping).
3. The XAML Grid element is the only element that supports proportional sizing and supports making all the things in a column (or row) the size of the largest item. It’s a pain to work with by hand because you have to specify each RowDefinition and ColumnDefinition and then assign each child control a Grid.Column and Grid.Row and possibly even a Grid.ColumnSpan or Grid.RowSpan …

1. If you only learn two of the “complicated” controls, learn about Grid and ItemsControl.

Some PowerShell WPF Tips

1. You can generate XML using XDocument instead of XmlDocument, but to be perfectly honest, since you’re already moving slow, the simplest way to write XML in PowerShell is to just use here-strings. In fact, if you need to generate a bunch of rows of XML, this snippet should help send you in the right direction:
   [XML]$xml = &{
   "<?xml version='1.0' encoding='UTF-8'?>"
   "<scale xmlns=''>"
   10..1 | ForEach-Object { "<Mark Label='$(($max/10)*$_)' />" }
   "</scale>"
   }
2. Although the about_data_section help says that you can use [XML]”...” as a literal in a Data section — you can’t. Just get used to casting it on the way out … Also,
3. If you need to cast a parameter to a function, (or specify it as a reference parameter) you have to enclose it in parenthesis: Out-GraphableXml $data ([ref]$max) $Label $Value — it’s not enough to put the type there.
4. Don’t forget, reference parameters in PowerShell are actually a type (PSReference), and to access the variable inside a PSReference variable $foo, you have to use $foo.Value.

1. Sometimes, the Dispatcher.Invoke trick isn’t enough — in the case of this data-bound form, it needs to go through at least 3 cycles of handling events before it will finish drawing:
   $graph.Show()
   1..3 | %{ $graph.Dispatcher.Invoke( "Render", [Windows.Input.InputEventHandler]{ }, $null, $null) }

Well, I figured that out, so I thought I’d go ahead and share … basically, all you have to do is call Invoke() on the window’s dispatcher. The reason that works is that WPF handles events and “work” in general in the order it needs to be done, so since the most important thing is drawing the UI it will do that first, and since your UI is based on downloading the image, it will take care of that first.

This is PowerShell v2 CTP2 code…

All of this code is written to target the CTP2 release of PowerShell v2 — it will not work in PowerShell v1 or even in v2 CTP1 … and it may not work in later releases, although I expect it will. Also, as with any code which uses WPF from PowerShell, these code examples require you to launch PowerShell with the -STA option.

Having said that, lets just straight to a WPF example

That’s almost as simple as it could get, but let me explain a few things which I left out previously, in case you’re new to XAML or even WPF. The Window tag is one of several acceptable root tags in XAML, but it’s the only one which will let you pop up a new window (in PoshConsole, you can display XAML inline using Out-WPF, and you can use almost any XAML nodes, but for now, lets focus on what works in general in the CTP2 console). The xmlns attribute is required in order for the xml to be verifiable to the schema, but in XAML it’s particularly important because without it, this would just be XML —not Xaml— and wouldn’t produce UI.

WPF Windows

There’s several fun tricks you can do in WPF with the Window that you can’t do in Windows Forms without a lot of hacking. ShowInTaskbar is hardly worth mentioning (it just does what it says). The Opacity attribute is kind of cool — it just controls the translucency level (valid values are from 0 to 1, but below the smaller values aren’t really very useful) — but you can animate this pretty easily to cause your windows to fade in and out. But there are a few that are more impressive:

Size To Content

One of my favorite features of WPF windows it that you can use SizeToContent to have the form automatically take the size of whatever is inside it (which is really useful when you’re loading images off the web). You have to be careful with this though, because WPF is resolution independent but it’s also aware of how many pixels-per-inch images have been saved with. Typically, if you have a png file, it’s been saved at something like 200 or 300 pixels per inch to make it printable … but your screen’s resolution is only (approximately) 96 pixels-per-inch. This results in images being displayed, by default … at HUGE sizes compared to what you expect. Caveat emptor.

Transparency

A WPF window with AllowsTransparency set to true can be non-rectangular! It’s very important that you understand this isn’t about allowing translucency (that is, it has nothing to do with the Opacity setting). With this setting on, your window will basically not exist in any spot where there’s no color (See demo4 below). It will be not only be invisible — mouse-clicks won’t register. You’ll also be able to have true per-pixel transparency, with the ability to set the alpha level of each pixel, since WPF colors can be specified as #AARRGGBB quads.

WindowStyle

This wouldn’t merit mentioning, except that it has a tie-in with Transparency. You can set the WindowStyle in Windows Forms too, and just like Windows Forms, the valuesfor WPF are None, SingleBorderWindow, ThreeDBorderWindow, and ToolWindow … however, if you use AllowsTransparency, the only valid value for WindowStyle is “None.”

Startup Location

As with WindowStyle, this attribute is mostly special because of it’s exceptions. You can use WindowStartupLocation to specify where you want the form to appear. Valid values are Manual, CenterScreen, and CenterOwner. CenterScreen is the obvious choice for a splash screen, but I should point out something about the other two as well. CenterOwner means to center the window on it’s parent window … but it only works with other WPF windows. If you don’t set the owner to a WPF window, CenterOwner works just like Manual. The Manual setting allows you to specify the window position with the Top and Left attributes, or just let Windows position you in the default location.

Events and Delegates

There’s one line of code in the sample above which bears explaining — the call to Dispatcher.Invoke. The point of this call is to basically transfer the thread control to the window for a moment. In fact, the signature of the Invoke method is that it takes a priority (I use render because it’s basically immediate), a delegate (I pass a scriptblock), and arguments for the scriptblock. PowerShell will let you easily cast a scriptblock to a delegate method which takes two object parameters and doesn’t return a value … but it won’t let you convert them to any other method without using reflection and IL.Emit. Thus, we cast our scriptblock to any handy delegate type, and pass $null for both parameters.

But that Invoke() stuff is ugly

Of course, we don’t like having to manually update the window by calling Invoke(), but I still haven’t figured out how to spin out another thread safely … so the only other option is to just give control to the window (actually I think this could be done with background jobs, but I can’t seem to get the WinRM CTP configured properly).

Giving control to the window is actually the normal way of doing UI programming … and isn’t really a very big deal in PowerShell — you can write your event handlers for the controls on the window, and then call ShowDialog() and you’re off. Just to give you an example, I’ve tweaked an old WPF sample I had and ported it to PowerShell … the xaml file is here and I’ll paste the code (with comments) inline, but if you may also download the PowerShell script. You need both files for it to work, because the clock.xaml file is the only argument to the demo-wpf4.ps1 script

Check it out:

Post Script

I should probably mention that I coded the XAML for that clock by hand, using kaxaml, rather than using Expression Blend — I don’t necessarily recommend it, but it’s good practice once in a while. XAML supports a lot of animations, and I spent almost an entire day trying different things to create a smooth animation for the CPU and RAM bars which would let them animate smoothly from one value to the next. In the end I decided it would have to be written in code rather than XAML markup, and would complicate things even more than they already were.