The markup generated is (I hope) reasonable and lightweight, with some simple css rules pre-applied. Feel free to customize the script to generate help however you like.

Generating many at once

I forgot to mention the other parameters on Get-HtmlHelp. They’re pretty cool, because if you want to upload your help you can do so with this. Say you created a module, and you wanted to generate all the help into files for uploading. You want to set the -BaseUrl to the location you will upload them to, and then use the -OutputFolder parameter to generate an html file for each command into the specified folder:

Now you can just take those files and upload them to the right spot on your website. I actually have some scripts which I can wrap around this to post the help to a wiki, but you’re just going to have to wait for that until the next time I get inspired to work on help …

Show-Help

I did include a little function in the comments and in the help for Get-HtmlHelp which uses ShowUI to display the rich formatted help in a popup window:

So anyway, enough of that. When you run it, it looks like this (click for the full screenshot):

One Catch

If you try this with IE and you get the error Unexpected error launching Internet Explorer. Protected Mode must be set to the same value (enabled or disabled) for all zones ... it means exactly what it says. You need to open “Internet Options” from your start menu (or from IE), and go through each “zone” and set the “Enabled Protected Mode” check box to the same value for each zone (either all checked, obviously the most secure, or all unchecked). I’m not going to debate whether setting them all unprotected is a good idea … I set mine to all protected, but I don’t generally use IE anyway.

If you want more help, Selenium’s documentation is great, and there’s a section on Getting Started with Selenium WebDriver which I found quite helpful (make sure your examples are in “csharp” and you can almost just copy and paste — someone should offer to do them in PowerShell).

If you want more information about the Internet Explorer driver and this problem in particular, the short answer is that “Protected Mode” is a security boundry, so if you cross over it the COM automation object doesn’t work — thus, you need to make sure you always stay on the same side. There’s a good discussion on the mailing list archive about how it works and why, as well a weird alternative documented on the Selenium JavaDocs

I’ve been playing with PowerShell 3 for a few months now, and I guess it’s long past time I started blogging about it.

There are a lot of new things coming in this release, but for me, the biggest change is the fact that PowerShell is now based on the Dynamic Language Runtime, a runtime environment that adds a set of services for dynamic languages to the Common Language Runtime (CLR), which is the core of the .NET Framework. The DLR makes it easier to develop dynamic languages to run on the .NET Framework. Of course, PowerShell is a dynamic language that runs on the .NET framework, but it was originally begun before the DLR had been released, so it’s only now that it’s finally been adapted to the DLR.

However, although PowerShell 3 is implemented using the DLR, it’s not a DLR language in every way that IronPython or IronRuby are. Let me borrow a couple of graphics from the DLR overview documentation.

The DLR Overview

You can see there’s three major sections to the DLR as it’s available on CodePlex: hosting, runtime, and language. However, not all of the DLR actually shipped in the .NET Framework 4.0 CLR.

The DLR shipped in CLR 4

PowerShell 3 takes advantage of all (or most) of what shipped in the CLR, but since the PowerShell team wasn’t willing to be responsible for shipping the rest of the DLR in the operating system, they didn’t implement the rest of it. Which is to say, PowerShell 3 is using the DLR Language Implementation code, with Shared AST and Expression trees, as well as the DynamicObject and Call Site Caching portions of the runtime, but none of the Common Hosting pieces like ScriptRuntime, ScriptScope, ScriptSource, or CompiledCode …

This means that you cannot use the same hosting APIs for PowerShell that you use for IronPython or IronRuby. However, even though you’re stuck using the same hosting APIs that you used with PowerShell 2 … you do get to use dynamic instead of PSObject when you’re working with the output in C#.

This really is a big deal

I wouldn’t care to speculate how many of the changes you’ll see in PowerShell 3 are directly due to the conversion to the DLR, but there are a few changes that you ought to be aware of. The first thing that you’ll probably notice is the difference in execution and performance. Anything you’ve learned about the relative performance of Scripts vs. Functions vs. Cmdlets and the load time of binary vs. script modules is going to go right out the window with PowerShell 3, as scripts and functions are now no longer (re)interpreted each time they’re run, but are compiled, executed, and (sometimes) cached. The result is that initial runs of scripts and imports of script modules are sometimes slower than they used to be, but subsequent runs of the same script or execution of functions from script modules run much faster, and this applies in particular to actual scripts in files and pre-defined functions in modules. Running a function repeatedly is now much faster than pasting the same code repeatedly into the console.

A more subtle, but significant difference is the change to PSObject.

In PowerShell 3, PSObject is a true dynamic object, and thus the output of cmdlets or scripts called in C# can be used with the dynamic keyword in C# instead of with the pseduo-reflection methods which are required for working with PSObject. However, this is just the tip of the iceberg, so to speak.

In PowerShell 2, all of PowerShell’s Extended Type System (ETS) was based on PSObject. New members were always added to a PSObject which is wrapped around the actual “BaseObject” — regardless of whether they came from a types.ps1xml file, or from calling Add-Member on an object. If you use Add-Member on strongly objects that are not already wrapped in a PSObject, you have to specify the -Passthru parameter and capture the output in order to have your object wrapped into a PSObject that the new member can be added to. In addition, when you cast an object to a specific type, those ETS members are mostly lost. Take this script for example:

In PowerShell 2, $Count1 and $Count3 will be the number of folders in the current directory, but $Count2 will always be ZERO, because the PSIsContainer property is actually an ETS property that’s lost when you cast the object to FileSystemInfo (and therefore it always evaluates as null and

However, in PowerShell 3 that’s no longer true. PowerShell now works with everything as dynamic objects, and Add-Member no longer needs the PSObject to keep track of these ETS members. This script will now get $Count1, $Count2, and $Count3 equal, as expected. Obviously the -Passthru switch on Add-Member is only needed when you’re trying to pipeline things, and not for simple assignments. However, there may also be other implications on when things get wrapped into a PSObject, and when it matters.

I think you’ll agree that having PowerShell on the DLR is awesome! But be aware that there are a few inconsequential breaking changes hiding in this kind of stuff. For example, after running that script above, try these three lines on PowerShell 2 and PowerShell 3 CTP2:

In PowerShell 2, you’ll get False, and then the next two lines will work fine. In PowerShell 3 the first line will return True, and since Add-Member actually affects the underlying object even when it’s not wrapped in a PSObject, the third line will actually cause an error, because “Add-Member : Cannot add a member with the name “Note” because a member with that name already exists.”

Anyway, I’m sure I’ll have more to write about the DLR and the changes it’s bringing to PowerShell, but for now, I hope that’s enough to get you thinking

The basis for the module is the arrange-act-assert model of testing. First we arrange the things we’re going to test: set up data structures or whatever you need for testing. Then we act on them: we perform the actual test steps. Finally, we assert the expected output of the test. Normally, the expectation is that during the assert step we’ll return $false if the test failed, and that’s all there is to it. Of course, there’s plenty more to testing, but lets move on to my new module.

The module is called PSaint (pronounced “saint”), and it stands, loosely, for PowerShell Arrange-Act-Assert in testing. Of course, what it stands for isn’t important, just remember the name is PSaint

PSaint is really a very simple module, with only a few functions. There are two major functions which we’ll discuss in detail: Test-Code and New-RhinoMock, and then a few helpers which you may or may not even use:

Set-TestFilter

Sets filters (include and/or exclude) for the tests by name or category.

Set-TestSetup (alias “Setup”)

Sets the test setup ScriptBlock which will be run before each test.

Set-TestTeardown (alias “Teardown”)

Sets the test teardown ScriptBlock which will be run after each test.

Assert-That

Assserts something about an object (or the output of a scriptblock) and throws if that assertion is false. This function supports asserting that an exception should be thrown, or that a test is false … and supports customizing the error message as well.

Assert-PropertyEqual

This is a wrapper around Compare-Object to compare the properties of two objects.

How to test with PSaint: Test-Code

Test-Code (alias “Test”) is the main driver of functionality in PSaint, and you use it to define the tests that you want to run. Let’s jump to an example or two so you can see the usefulness of this module.

Let’s start with an extremely simple function that we want to write: New-Guid. We want a function that generates a valid random GUID as a string. We’ll start by writing a couple of tests. First we’ll test that the output of the function is a valid GUID.

Now, to verify that the test works, you should define this function (the GUID-looking thing is one letter short) and then run that test:

Another proof that it works would be that it should fail on this function too, because “x” is not a valid character in a Guid:

So, let’s write a minimal New-Guid that actually generates a valid Guid:

If you run our test on that, you will see:

If you don’t like the fact that the Category is empty, you could add a category or two to the end of our test. We should also switch to using Assert-That if we want to know which test in the assert failed. Finally, we want to write another test which would test that New-Guid doesn’t just return the same Guid every time, the way ours does right now:

Now, we have to actually fix our New-Guid function to generate real random Guids:

And at that point, we should have a function, and a couple of tests that verify it’s functionality…

The finer points of assertions

One thing you’ll notice the first time you use Get-Member after loading the PSaint module is a few script properties have been added to everything. I did this because I found myself writing the same Assert-That calls over and over and decided that it would be slicker to make these extension methods than to write new functions for each one:

There’s also a MustThrow([Type]$Expected, [string]$Message) which can be used on script blocks (note that this function executes the ScriptBlock immediately, so be careful how you use it).

We can use these to tidy up our tests quite a bit, while still getting good error messages when tests fail:

COM Objects

PSaint also has a wrapper for COM objects to help with testing them. It adds GetProperty and SetProperty methods to allow you to access COM object properties which don’t show up on boxed COM objects (a common problem when working with MSOffice, for instance). It also adds InvokeMethod for COM objects to invoke methods that don’t show up for similar reasons. These, of course, only help you if you’re already fairly literate with the COM object in question.

Mock Objects

PSaint includes New-RhinoMock, a function for generating a new mock object using RhinoMocks (which is included). Rhino Mocks is a BSD-licensed dynamic mock object framework for the .Net platform. Its purpose is to ease testing by allowing the developer to create mock implementations of custom objects and verify the interactions using unit testing.

I have to admit that this New-RhinoMock function is incomplete, and exposes only a fraction of the options and power in RhinoMocks, but it’s been sufficient for the few times when I’ve wanted to actually mock objects from PowerShell, so I’m including it here.

For those of you (developers) who want to know why RhinoMocks instead of your favorite mocking framework, the answer is astonishingly simple: it had the least number of necessary generic methods (which are impossible to call in PowerShell 2).

Some back-story

During development of a PowerShell module like ShowUI, I am usually not using a released version of the module, since I’m obviously working on the next version. In addition, sometimes I need to have “beta” and “stable” releases … so I might have two or three versions of the module that I need to be able to load in order to support users and actually do development.

In case you don’t know how modules work, here’s the deal: There’s an environment variable PSModulePath. It’s just like the Path environment variable, but for modules. The variable contains a semi-colon delimited list of folders paths, which PowerShell searches for modules. Some people think of a PowerShell module as basically a .dll (binary module), a .psm1 (script module), or a .psd1 (manifest module)... but it’s never just a file, it’s a *Folder* and a file. In order for PowerShell to find ShowUI when you write Import-Module ShowUI, you have to have a Folder in the PSModulePath named “ShowUI” and in it, a file (either .dll, .psm1, or .psd1) also named ShowUI.

What I would like

The Import-Module command has a -Version parameter. What I expected What I would like to be able to do is create a folder “ShowUI” and in there, create folders “1.0” and “1.1” and “1.2” and then be able to use Import-Module ShowUI -Version 1.1 to load a specific version.

Sadly, this doesn’t work. First of all, the -Version parameter on Import-Module, is a minimum only. Additionally, Import-Module requires the file and folder to match names exactly, so putting the module inside a subfolder doesn’t work even if there’s only one.

However, there are two things we can use to fix our problem:

1. Just like the PATH variable, PSModulePath works in order. PowerShell searches the listed paths one at a time and uses the first Module that meets the specified minimimum version.
2. Additionally, PowerShell allows you to specify a relative Path to a module that starts in a PSModulePath … I’ll explain more in a moment.

My actual working environment

All of my development projects are in $Home\Projects, so I put a “Modules” folder in there which is where I put modules that I’m actively working on. Then I add that folder to my PSModulePath environment variable: @$Env:PSModulePath += “;$Home\Projects” ...

Since I put it on the end, modules in there won’t be imported if there’s a module with the same name in my regular Module folder ( $Home\Documents\WindowsPowerShell\Modules ), unless I increment the version number in the psd1 metadata file and specify -Version when importing.

For example, I have two copies of WASP:

$Home\Documents\WindowsPowerShell\Modules\WASP\Wasp.psd1 (version 1.0)
$Home\Projects\Modules\WASP\Wasp.psd1 (version 2.0.0.2)

If I want to load the released version, I can just Import-Module WASP — this ensures that scripts that I have in my scripts folder generally load the released version of WASP. When I want to load the development version, I can Import-Module WASP -Version 2.0, and get the version from my Projects folder, because the released version’s version number is lower than 2.0.

More layers onion boy?

When I need to have more than one older version, this presents a problem, because I would need another folder in my path, and for the numbering scheme to work despite the fact that -Version is only a minimum value, I would need the released version (say 1.0) to come first in the path, then the beta version (say 2.0.1), then the development version (say 2.1) ... which means I’d need to add a $Home\Projects\BetaReleaseModules or something like that, and put it in my PSModulePath before the $Home\Projects\Modules folder. That would work, but you can imagine that it wouldn’t scale very well.

Here’s what I do: past the release and development versions, I start creating folders like this:

$Home\Documents\WindowsPowerShell\Modules\ShowUI1.0\ShowUI.psd1 (version 1.0)
$Home\Documents\WindowsPowerShell\Modules\ShowUI\ShowUI.psd1 (Release version: 1.1)
$Home\Documents\WindowsPowerShell\Modules\ShowUI1.1\ShowUI.psd1 (Release version: 1.1)
$Home\Documents\WindowsPowerShell\Modules\ShowUI1.2\ShowUI.psd1 (Beta version 1.2)
$Home\Projects\Modules\ShowUI\ShowUI.psd1 (Development version 1.3)

Now, if I Import-Module ShowUI, I’ll get 1.1 and if I specify Import-Module ShowUI -Version 1.2 I’ll get … version 1.3 (whoops).

To load ShowUI 1.2 with that structure I have to do this: Import-Module ShowUI1.2\ShowUI — specifying the folder name and the module name. Of course, I could use “ShowUIBeta” as the folder name instead, but usually when I get a request for help writing scripts, I can get people to give me the specific version that they’re working with, so I like the numbered folders instead.

A last important note is that I do not rename the psd1 or anything else.

I could rename the metadata file to $Home\Documents\WindowsPowerShell\Modules\ShowUI1.2\ShowUI1.2.psd1 and then I’d be able to Import-Module ShowUI1.2, but there’s a catch. If I rename it, then I’ve renamed the module. If I leave the metadata file as “ShowUI.psd1” then once I’ve imported the module I can call Get-Module ShowUI or Get-Command -Module ShowUI and they still work as they should.

In any case, this folder-naming stuff is less than ideal and will hopefully be fixed in a future release of PowerShell, but with a “Projects\Modules” folder I can have two versions, and usually a development and release version is enough. Personally, I keep old releases of major modules around in numbered folders just in case, but I rarely actually use them.

Let’s say you had a form that collected a bunch of user input, and then had a button that would fire off some work. We’ll assume that you wanted to prevent people from firing off the work again before they know the results of the first time, so you’ll disable the button while you’re working. Something like this (leaving out the boring stuff about collecting the user’s input and displaying the results):

It’s pretty simple. In fact, I think there’s only three things worth pointing out:

1. There are variables for named controls.
2. If you want to make sure a control has time to update it’s display while you’re executing your event handler, call UpdateLayout().

1. You can disable and enable buttons.

Now, try doing the same thing with Windows Forms.

This was my first attempt:

Now, I bet you noticed that took a bit more code than the WPF version in ShowUI, but the thing about it is that I also had to manually specify the positions of the controls (and I had to set the size of the form to make that work). And after all that, it still doesn’t actually work, and it has a few ugly behaviors:

First of all, disabling the control doesn’t work, because Windows posts all click events as messages to the button’s message queue, and it doesn’t know that it should ignore them, because it only processes one at a time — when it’s done running the Click handler the first time, it notices there’s another event … and since it’s enabled, it processes it. If you click it five times while it’s disabled, you’re going to get the work done five more times… eventually.

On top of that, although the label updates without being told to, it didn’t push the button down the screen or resize the form, so eventually it overlaps the button, passes through the bottom of the form and disappears.

The next thing I tried was to actually unhook the event handler before I disable the button … but that had no effect either, because (as I wrote earlier) the button doesn’t actually ignore the clicks while it’s doing the work — it just queues them up for processing later.

Of course, I could do the work in a background job so that the button would return immediately, but that doesn’t meet the requirements I have for not queuing up extra work before the first work is done, and in fact, then I’d have extra work to do to create a time to check and see if the remote job was finished or not.

[New] Thanks to SAPIENDavid, I’ve realized the simple fix for the disabling problem, we just have to call DoEvents to empty the event queue before we re-enable the button.

Here’s what did work:

To fix the other problems, I added a FlowLayoutPanel (which is very different from the StackPanel in WPF, but still serves the same purpose), and made all the relevant bits autosize (it’s always surprising to me when I need to drop back to WinForms, how everything has to be told to autosize and fill empty space).

That’s enough to take care of the output problem, and make the two solutions roughly equivalent (there’s still some differences, as you can see if you run them).

For what it’s worth, this was a real world question from a user at our Virtual User Group this morning, and I just couldn’t help sharing how much easier user interfaces are to write in ShowUI. Clearly a designer like PrimalForms makes laying out the controls easier — but when it comes to the little things, you still have to figure out to make them work, and actually implement your event handlers correctly.

Just for the record, here’s what it would take to implement the WPF solution without ShowUI:

In programming, we call those interactions “events.” An event in WPF covers all forms of user interactions like clicking a button, type in a textbox, or select items from a treeview or listbox, and even less obvious things like when the right or left mouse button get’s pressed down, or let up … or when the mouse moves, of when the control gets focus or looses it, or “touch” and “stylus” events, drag-and-drop events, etc. There are also events that aren’t caused by users, like events for when databinding is updated, when the control is initialized, hidden, made visible, etc.

In ShowUI, all events are handled by assigning scriptblocks to a parameter who’s name starts with “On_” like -On_Click or -On_GotFocus or -On_MouseLeftButtonDown or -On_TextInput … and so on.

Let’s say that you want a quick dialog like this:

You’re going to need to handle the OK button click, of course, but in that scriptblock, you’re going to want to get the text from the textbox, and make sure that it gets returned when the window is closed … and you’re going to want to close the Window!

We’re here to help! Within the event handler script blocks, ShowUI defines a bunch of variables for you to help you handle the event: $this is the source of the event, $_ is the event arguments, and $window is the top-level window that contains your UI. Any named controls in your script are also exposed as variables, so if you started with this script:

You’re going to be able to get the text from the TextBox using $FullName.Text because you know the TextBox has a property named “Text” (since it’s exposed as a parameter for you in the TextBox command), and because now you know that ShowUI creates a variable for all the named controls.

In order to write output from a script like that one, you have to set the Tag property on the top level control (in this case, the StackPanel, which is obviously named “Prompt”). You can do that easily by hand, or you can use the Set-UIValue function.

In order to close the window, you’re going to have to do one of two things: first, you can use the handy Close-Control function, or you can call the Close method on the window. The Close-Control function will look at the “parent” (and it’s parent) to try and find the window that needs to be closed — but if it can’t find one, it will just hide the parent, so if your button were several layers deep (unlike ours), you’d have to specify the top level control as a parameter.

Here’s two versions of what it could have looked like when I was finished:

One thing you’ll notice right away is that I cheated and actually added another event handler too: For the “Loaded” event on the StackPanel. This event handler is called during the initialization of the user interface, and gives you a chance to do things like what I did here: set the initial keyboard focus where you want it (so the user can start typing as soon as the window pops up).

However, if you run them both, you’ll notice another thing: the output is different. In the second example I took advantage of the fact that Set-UIValue will actually call Get-UIValue if you don’t pass it a parameter! The cool thing about Get-UIValue is that if it doesn’t find a “Tag” on the specified control, it will look through the children to find one, and create a hashtable out of the values it finds. So in this case, rather than write the code to get the value from the right textbox and set it myself, I just let the built-in features of ShowUI do their thing.

A bigger example

Of course, in neither example did I need to do anything with the button or with the actual parameters that are passed in to the button’s “Click” event … so perhaps one last (more complicated) example would be useful:

Hopefully, by now this doesn’t need a whole lot of explanation, but let’s walk through it anyway. First of all, if you’re not familiar with them, this script uses the excellent PowerShell Commands for Active Directory from Quest software. This doesn’t represent a full, complete, useful user interface — it’s more of an example that you can hopefully work from (and please, contribute ammendments on PoshCode).

You can see that I used a Grid with four rows and two Columns: with one column “Auto“sized, and one using up all the rest of the UI (you can resize the window to make the fields bigger). The first thing in the grid is the definition of a scripblock which I assigned to a variable $GetGroups. The reason I did that is because I wanted to reuse the scriptblock as the event handler for both the UserName and EmailAddress fields.

Without dwelling a whole lot on it, you can see the last line is the “OK” button which get’s the parent grid and calls Set-UIValue to invoke, as before, the hashtable collection of all the textbox values.

The interesting stuff is in that GetGroup event handler:

You can see that first we call Get-QADUser with the Text of $this field. By using $this, we make it so the event handler will work on both Textboxes, since it will get the text of whatever triggered the event handler. Get-QADUser doesn’t return anything unless it finds a user, and setting the SizeLimit ensures that we won’t end up waiting for it to retrieve “all” the users just because the Textbox was left empty. In fact, the point of that line is to make sure that we matched a user.

On the next line, I’m making sure that either the LogonName or Email of the user that we found matches fully the text that the user typed. This makes sure that the user that we matched is a full match, so we know we’ve gotten the person typing into the form to type a full, complete username or email address.

When it does match, we set the color to Black (in case it was an error and set to Red before), and we call Get-QADGroup to get all the groups that the user is a member of. We set those groups as the source for the $Group listbox, and they’ll immediately show up for the user. And finally, we update the few fields we’re showing from the user object we retrieved earlier.

Of course, when it doesn’t match, we set the text red to indicate an error, and then we zero out the data on the group listbox.

I hope this has helped some of you figure out event handlers in ShowUI — please feel free to ask questions in the comments below or on the ShowUI discussion boards.

An introduction to ShowUI

ShowUI is the next generation PowerShell module for building user interfaces in script. It’s the merger of my previous PowerShell UI project (called PowerBoots) with one by James Brundage, former Microsoft PowerShell team member and founder of Start-Automating (called WPK) which shipped in the Windows 7 resource kit.

If you want to follow along, you need to:

1. Get a copy of the ShowUI Module from CodePlex
2. Install it by putting the “ShowUI” folder in one of your “Modules” folders (list them by typing $Env:PSMODULEPATH in PowerShell v2, and feel free to create the one you want if it doesn’t exist). You should end up with something like C:\Users\Jaykul\Documents\WindowsPowerShell\Modules\ShowUI\ShowUI.psm1
3. Run PowerShell ISE, or use PowerShell.exe with the -STA switch (the best way to do this is to add it to the shortcut you use to launch PowerShell: open the properties dialog, and on the Shortcut tab, add “ -STA” to the Target)¹.

Did I hear someone ask what is WPF? It was introduced as part of .Net 3.0 (and vastly improved in .Net 3.5, and again in 4.0), so you can expect to find it preinstalled on computers from Vista on, and of course you can download and install it on XP if it’s not already installed. The only thing you really need to know about WPF for the purposes of this tutorial is that it is the new GUI toolkit for .Net, and that it is container based — you put elements into other elements to control the layout, rather like HTML and Java Swing… you can pick up the rest as we go along.

A simple ShowUI program

This first example is a little bit more verbose than it needs to be, because the -Content parameter is positional, so the first non-named argument you pass will be used for that. The same is true for the -Children parameter of panels, and in fact, each of the other similar content parameters: Items, Blocks, and Inlines.

Additionally, each control is aliased without the New- verb, so you could just call Button instead of New-Button … and of course, since our button doesn’t do anything, we could just as easily have used a Label, and written:

Note: “Label” is also the name of an executable for labelling drives in Windows, make sure ShowUI is imported before you run that command.

One last point: ShowUI brings a lot of features from WPK to the table, and one you’ll use a lot is the ability to skip specifying the window and put the -Show parameter on almost any WPF element. This is partly because we’re back to running PowerShell 2.0 with the -STA switch, but in any case, we can now skip the “New-BootsWindow” command, and our examples can be that much simpler.

We can put controls in a stack

StackPanels are awesome. So are WrapPanels. Try that code with a WrapPanel instead of a StackPanel and see what the difference is (hint: try resizing the window). Actually, try it with a UniformGrid too. WPF has several other panel containers too: Grid, ToolBarPanel, TabPanel, DockPanel, Canvas … we’ll talk about some more of those later.

Ok, lets see some formatting

To scoot the buttons out from the edge we can use margins or padding: margins go on the outside of containers, padding goes on the inside. We can also specify the FontFamily, FontSize, FontWeight, and FontStyle, as well as Foreground and Background colors …

So you see, the pink background is on the StackPanel, which has a (default, white) margin around it. If you wanted the whole background of the window to be pink, you would need to set the background of the Window instead of the StackPanel.

An aside on Typography

ShowUI doesn’t need to create a full set of typography-specific top-level elements the way Shoes does, because we are based on WPF, which has a far more powerful typography system available than any we’ve used previously. So, with WPF we start by selecting a control based on how much text you want to put in it, and how much formatting you want to apply: Label and TextBox are the simplest, TextBlock supports limited text formattings, and FlowDocumentViewer or RichTextBox support full rich content. And of course, Hyperlink supports clicking

For the typography elements, the content model changes a little bit. There are basically two types of typographical elements: Inline and Block elements (where inline elements can’t contain block elements). In fact, he TextBlock Content Model is similar to that of an inline element. It is actually a type-restricted “Items” container. Instead of being able to have anything as content, it can only contain Inline flow content elements such as AnchoredBlock, Bold, Hyperlink, InlineUIContainer, Italic, LineBreak, Run, Span, and Underline, and it will create a run automatically if you just put a text string in it.

Note: If you want support for the full document model (which allows Paragraphs and Lists), you need to use a FlowDocumentReader, FlowDocumentPageViewer, RichTextBox, or a FlowDocumentScrollViewer ... there’s lots more information about those on msdn.

Time for some artwork

In WPF, everything always starts out white, and you must position things based on the container. You can see that the Margin can be specified as a single value as in the previous example, or as separate values for Left, Top, Right, Bottom. Oddly, to satisfy PowerShell’s type-casting, you have to quote them so they’re a single comma-separated string, instead of four separate values.

Some more advanced drawing

When you want to start getting clever and overlapping things, you need to use a Canvas container. The Canvas can contain multiple items which are all absolutely positioned, but unlike most other containers, it doesn’t automatically expand to contain it’s children, so you typically have to set it’s size.

We also have to set the Stroke and Fill. These are the two colors that make up every object, and again, if we don’t set them, they default to white. Note that you can use named colors, or you can specify a hex value using “#RRGGBB” or “#AARRGGBB” to set the alpha channel. The StrokeThickness controls the line thickness.

One other thing to notice is that we positioned the Rectangle by using the Margin, but we positioned the arrow, which we built using a Polygon, based purely on the x,y coordinates of the points. The available shapes are Ellipse, Line, Path, Polygon, Polyline, and Rectangle. You can, of course, make nearly any shape you want with the Polygon.

There are other more advanced shapes available in external libraries, and we can even do 3D, use gradient or image fills…

We can even get images straight off the web

WPF loads the image on a background thread, and caches it in memory, so the window will show up and be responsive while you’re waiting for the image, and because we’ve specified -AsJob, you can actually continue using PowerShell while the image loads. Note: it will load much faster the second time you run that script.

Events

If you were paying attention to the typography example, you’ll have noticed that we introduced event handling without making a big fuss about it. Event handlers in PowerBoots are specified in much the same way that Properties are, except that their parameter names always start with “On_” and they take a script block. The Hyperlink element in a WPF window doesn’t automatically open a browser (because you can use it to change “pages” in a WPF application), so to make simple web links work, you have to handle the “RequestNavigate” event as shown above.

In order to update your user interface when an event triggers, you’ll need to have variables that point at the control(s) you want to affect. In ShowUI event handlers, you get a $this variable which points at the object that caused the event, a $_ variable which is the event arguments, and a $window variable for the top-level window … you also get variables for each named control in your window.

WPF Elements all have a Tag property which can be used to store any object, so as you can see in the previous example, you can use that to keep track of things … but more importantly, the value of the Tag on the top-level control will be output. In other words, when the window is closed, this example actually outputs to the PowerShell pipeline how many times you clicked the button.

Working with User Input

There are helper functions in ShowUI for working with that output value: Set-UIValue and Get-UIValue, and Get-UIValue is particularly helpful because if the control it’s called on has no value, it collects the values of all the child controls, so you can use it to output a whole form at once:

I’ve made this example more complicated than it needed to be to demonstrate some best practices. We could have made it much simpler by using a UniformGrid control instead of a GridControl, thus avoiding needing to set the -Row and -Column special parameters, but I wanted to show those to you anyway, and the form looks a lot better when the two columns can have different sizes:

You’ll notice how easily I specified the width of the columns, but the COUNT of the rows in the Grid panel. If you provide an array of values, they’re converted to GridLengths, but if you provide just one, it’s treated as the count. You can make grid columnds and rows AUTOmatically size to their contents, and you can make them * width to make them take up any extra space. You can even split the extra space by setting * on more than one column (and specify the proportion by using numbers, like: 1*, 2*).

I should also point out that if you use MinHeight and MinWidth instead of the Height and Width values, your controls will be able to size up to fill space when the window is resized! Try that script with Width and Height instead and resize the window to see the difference.

We used the Set-UIValue shortcut in this form, which brings up another point: when creating data forms, you only need to name the controls you want output from. Then you’ll be able to just call Set-UIValue on the parent to collect all the values from the controls and output them as a hashtable!

Finally, remember your defaults: set the focus to something so the user doesn’t HAVE to click to get started, and set a button to -IsDefault with a On_Click handler so that when the user hits enter they can submit the form.

Further directions

There’s a lot more possible with ShowUI: we can use gradients for colors, create data templates and styles, and even make chromeless windows, but you have the basics for getting started already.

This first release of ShowUI is still missing some features from both WPK and PowerBoots, but we’ll get to them as we progress. For now we’d like to invite you to come download the latest release, and write up or vote up the features that you want the most in the next version. Keep an eye on the release page and on the discussions and we’ll be cranking out new releases on a monthly basis for now.

I hope you’ve enjoyed this tour through ShowUI, and will be able to start applying it soon for fun and profit.

¹ The -STA switch is necessary because the .Net framework requires the STA threading model in order to do graphical user interfaces. PowerShell ISE doesn’t require it because unlike the PowerShell.exe command console (which is a Win32 native “console” application that hosts the .Net framework), PowerShell ISE is a .Net framework “graphical” application, and is therefore running in the STA model already.

So, first, to demonstrate the differences, lets create an executable which will use various methods to access its command-line parameters and print them out. We will do this in C# although you could do it in C++ and see some variations because the .Net runtime does some parsing of it’s own, which is a little weird — but this simple example should be enough to demonstrate the differences.

The code here is in PowerShell format, so you can simply paste it into PowerShell and get an executable as output, which you can then move to C:\Windows\System32 for testing purposes.

To test things, we are going to invoke it in PowerShell, in CMD.exe (DOS), and using the Run dialog (and finally, using Start-Process, to demonstrate that it has the same output as the Run dialog).

A note about path problems

In order to see the differences in how paths are handled, I put ArgsTest.exe in C:\Windows\System32\ — this allows me to call it with no path at all, with a full path, or with a partial path. That turned out to be important because the first difference of PowerShell is that it always executes the app with a FULL path, even if you’re calling it with a partial path.

The reason for this is simple: PowerShell doesn’t ever set the “CurrentDirectory” in it’s operating evironment when you Set-Location (presumably because they figured that often that location would be in a non-FileSystem provider). Because it doesn’t set the current directory, it always needs to invoke applications and scripts with their full path name.

The test case

We will execute the following (long) command-line:

And to get us started, lets look at what that looks like when you execute it from cmd:

Notice that in this output, Environment.CommandLine is exactly what was typed!
Now, let’s see the same thing from the run dialog:

The thing I want you to notice is that the results are almost exactly the same. The only difference is that cmd shows you just “ArgsTest.exe” which is what was actually typed, whereas the Run dialog inserts the full path to the executable.

But now, take a look at that same command in PowerShell:

A Diagnosis

The one thing we expected, of course, is that Powershell interpreted the $Home variable instead of the UserProfile variable, but that’s hardly the most significant difference …

In an attempt to translate what you wrote into what they think you meant, PowerShell has rewritten all of the quoting in the command line!

• First, since PowerShell understands that commas are simply array separators, they simply remove them completely when calling a “native” app. PowerShell is actually taking the array, and converting the array into a string with space separators. They don’t seem to respect $OFS when doing this, so I don’t really know what the justification is for doing it.
• Second, PowerShell changes single quoted strings into double quoted strings (without expanding the variables) to make sure that what PowerShell thinks of as strings are also thought of as strings by the target application (of course, they wouldn’t be strings in DOS, but this is PowerShell). If your executable depends on getting single quotes in the arguments, you’re going to have some pain because of that, otherwise, you won’t even notice.
• Third, PowerShell actually MOVES some quotes, like the one after /slashes … Obviously PowerShell doesn’t treat / as a switch, so it treats them as any other string character. Since in PowerShell, if you don’t quote the WHOLE string, you can still start quoting halfway through it when you realize you need to type spaces … they move the quote to the start of the string so that your app will see the same thing a cmdlet would have.

• Finally, PowerShell INSERTS extra quotes around -dashes. This is the one thing I can’t really explain right now. PowerShell inserts extra quotes which result in what looks like a real problem in the CommandLine string due to double-double quotes … but somehow those escape parsing as an escaped double quote character when you look at the output of GetCommandLineArgs.

Work arounds

You can get the same results from GetCommandLineArgs when invoking from a PowerShell command by quoting your single quotes and commas, knowing that you need to use $Env: instead of %%, and escaping your dollar signs:

However, if the app you’re calling relies on parsing CommandLine, instead of using args[] or GetCommandLineArgs(), then you have to do it differently, and you can’t ever know that until you try it…

The best workaround, therefore is to use Start-Process. Of course, if you have UserProfile or other environment variables, then you still have to replace those with $Env: and escape your other dollar signs, but if you don’t … you can just use a single-quote here-string. Note the minor difference:

And finally, we have it!

As you can see, the only difference is the value in Arg 5 … but this last attempt actually results in a completely compatible CommandLine and CommandLineArgs. Of course, if you need to capture the output, then you need to append: -Wait -RedirectStandardOutput StdOut.log; gc StdOut.log … but that won’t work if you need to use the application interactively (although, if you just want to script an interactive app, there is also a -RedirectStandardInput parameter).

In any case, if your app is non-interactive, you can use something like this:

But still

If you need to run an app in the PowerShell window, interact with it (e.g.: answer a prompt), and then capture, process, or redirect the output … you need to invoke the app “natively” ... not using Start-Process. The bottom line is that PowerShell still needs a way to invoke apps that works as simply as Start-Process, but that invokes them inline in the shell. In the meantime, you should generate that ArgsTest executable (from poshcode) to help you figure out the right combination of quotation magic to convince PowerShell 2.0 to pass the right values!

• PowerPoint Deck

• PDF Deck with notes