Update 18.11.2013: pointed URL to a CodePlex project page.

---

Phinally!!!

Abstract

As you already know, last time I worked on my next PowerShell PKI module and encountered in an issue with Microsoft’s Cmdlet Help Editor. When I tried to open my module (and any other built-in module) I got very nice message:

Ok, I tried to download sources (thanks, they are available for download) and was stuck with WPF. I heard that WPF is a modern replacement for WinForms, and that was the only what I knew about WPF. I was able to fix mentioned message issue, but failed with application layout. The form has fixed size and no scroll bars. So I couldn’t access textboxes and commands which are outside of my screen (even if I worked on a 1680*1050 display). And I decided to create my own Help Editor with with “blackjack and hookers”.

How it was

The first question was: what to use, WinForms or modern super-puper WPF. I have a very little experience in WinForms (example: Bulk file signing with PowerShell and user interface), so in any way I had to learn any of them. Eventually WPF won.

I started new clean WPF project in my visual studio and tried to make simple tasks: place button, attach events and get the result. Not enough for solid project, but in any way. Step-by-step I dived deeper and deeper. I learned containers, controls, their properties, features, how they can be combined.

The first solid achievement for me was user control usage. I just wrote simple user control and added it to my main window. It was epic WIN! The next win was DockPanel. I figured out how to dock controls within a window. I used it to develop about 10 user controls and they are logically added to my form and loaded/unloaded on events.

After I got very basic UI (yet no scrollbars, just a set of textboxes, textblocks and listview controls), I started with object model. Just created a set of base classes to represent cmdlet object and it’s help content. Then I figured out how to bind collection to a ListView/ListBox. The next step was ListView/ListBox display change when the data was changed. In about 1 day I figured such things as Observable Collections and INotifyPropertyChange event implementation. Another win.

After a time I got almost usable UI with a ton of stubs in code-behind. This week I (assuming, today is sunday) got a very nice article about Model-View-ViewModel design pattern and bindings. Also another good guy Sergey Zwezdin (who is a friend of mine and ASP.NET MVP) explained me some advanced stuff about how to work with data bindings, dependency properties (this was the most complex thing for me and couldn’t figure it myself) and relay commands. Another several days were spent to rewrite the code. Create View Model classes and move all the code from code-behind to view Model files. It was crazy, almost everything in my application works via direct bindings rather than code-behind event handlers. This is the most major WIN.

When I started to learn WPF, I hated it, because everything there was unobvious and quite complex for me. After each (even very little) win I liked WPF more and more. By now, I can tell that I like WPF more than WinForms. Fact.

Finally I attached XML Reader and XML Writer (as PowerShell uses XML help format) from original cmdlet help editor (though, most code parts were optimized and rewrited in a more convenient way). And this weekend I ended with UX details (buttons, menu’s toolbars, behaviors and other things).

Even though the mainstream UI is Metro UI, I always liked Office 2003 UI style and finished with it. If you don’t like it, then you just can ignore it and write your own help.

How it works

When you start the editor, it will load modules in background (without locking current UI thread):

Once modules are loaded, they are displayed in the ListView (in a way they looked in original help editor):

you can either open existing help file or create a new help file. After module commands are loaded (again, they are loaded in background), you will see main editor UI:

I decided to use TabView control to separate help sections, as it is easier to implement and doesn’t look worse than TreeView in original help editor. One important thing. For Parameters, Examples and Related Links tabs I added ListView controls where you have to select an item you want to edit:

In the Example and Related Links tab I added two useful buttons which you can use to move selected example up or down:

Also, I want to note you that you can resize panels:

I used GridSplitter control to add an ability to extend cmdlet list in the case if you have long command names and you don’t want to scroll them all the time. Each panel has separate scrollbar, so there should not be any inaccessible element.

End Titles

Currently I don’t have a project page (and even not sure if I need it), so you can download the editor from my SkyDrive:

The project got a life and is moved to CodePlex:

>> Download PowerShell Help Editor <<

 

This application requires .NET 4.5 Framework.

Even though I don’t have project page, I’m accepting feature requests and bugs in comments, or via email. Any feedback is highly appreciated.

Credits are going to Sergey Zwezdin, Wassim Fayed and Google (really, I learned WPF through google search). Enjoy!

---