As I mentioned before, I have created a CodePlex project to track the development of a WPF PowerShell host using AvalonDock and AvalonEdit.

It’s still in the very beginning stages, but it’s comparable to the code I used in this tutorial series (except that it’s using different technologies, all of which I’m new to).

PowerShellWorkBench will eventually include:

• Treeview controls
• Node/Edge Graphs (using the GraphXL library)
• Context-menus based on powershell ETS
• Whatever you think of and submit

If you’re interested in contributing to PowerShellWorkBench, drop me a line (mike).

-Mike

[EDIT]: The windows forms-based powershell workbench project can be downloaded here.

Before we proceed with putting powershell objects in a treeview (which I promised last time), I need to explain some changes I have made to the code.

• Refactoring the InvokeString functionality ouf of the menu item event
• Merging the error stream into the output stream
• Replacing the clear-host function with a custom cmdlet

First, we had been calling the invoke method in the OnClick event of the menu item. While that works fine as a proof-of-concept, we’re going to need that functionality elsewhere, so it’s a simple matter to extract the logic into a function as follows:

Sub RunToolStripMenuItem1Click(sender As Object, e As EventArgs)
  	InvokeString(txtScript.Text)
End Sub

Private Sub InvokeString(strScript As String)
	dim ps As powershell=PowerShell.Create()
        ps.Runspace=r
        ps.AddScript(strScript)
        ps.AddCommand("out-default")
        ps.Commands.Commands.Item(ps.Commands.Commands.Count-1).MergeUnclaimedPreviousCommandResults = PipelineResultTypes.Error + PipelineResultTypes.Output
        Dim output As Collection(Of psobject)
        output=ps.Invoke()

End Sub

In this new InvokeString method you see highlighted (if you allow javascript :-)) the line of code that merges the error stream into the output stream (so that errors we throw with our new cmdlets will show up in the console).  We’ll still need to update the our PSHostUserInterface class to handle the WriteError method, but that’s pretty easy (as are the debug, verbose, and warning methods):

Public Overloads Overrides Sub WriteErrorLine(value As String)
	MainForm.PowerShellOutput.AppendText("ERROR:"+value +vbcrlf)
End Sub

Public Overloads Overrides Sub WriteDebugLine(message As String)
	MainForm.PowerShellOutput.AppendText("DEBUG:"+message +vbcrlf)
End Sub

Public Overloads Overrides Sub WriteProgress(sourceId As Long, record As System.Management.Automation.ProgressRecord)
	Throw New NotImplementedException()
End Sub

Public Overloads Overrides Sub WriteVerboseLine(message As String)
	MainForm.PowerShellOutput.AppendText("VERBOSE:"+message +vbcrlf)
End Sub

Public Overloads Overrides Sub WriteWarningLine(message As String)
	MainForm.PowerShellOutput.AppendText("WARNING:"+message +vbcrlf)
End Sub

With that, we can see that the built-in clear-host isn’t going to work:

ERROR:Exception setting "CursorPosition": "The method or operation is not implemented
ERROR:."
ERROR:At line:8 char:16
ERROR:+ $Host.UI.RawUI. <<<< CursorPosition = $origin
ERROR:    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
ERROR:    + FullyQualifiedErrorId : PropertyAssignmentException
ERROR:
ERROR:Exception calling "SetBufferContents" with "2" argument(s): "The method or oper
ERROR:ation is not implemented."
ERROR:At line:9 char:33
ERROR:+ $Host.UI.RawUI.SetBufferContents <<<< ($rect, $space)
ERROR:    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
ERROR:    + FullyQualifiedErrorId : DotNetMethodException
ERROR:

You can see that, by default, “clear-host” is a function that relies on the RawUI class in the host (using rectangles, and filling with spaces, it looks like).  We really don’t want that kind of access in our interface, so we’re going to replace this function with a cmdlet that simply clears the textbox.

That brings up another “benefit” of writing your own GUI host…the ability to implement cmdlets without writing SnapIns.  With 2.0, you can write advanced functions (and I encourage you to do that), but with 1.0 you didn’t have that option.  With your own host, you get to add cmdlets without the pain of a SnapIn installer.  The two things we need to do are:

1. Create a cmdlet class to do the work
2. Add the cmdlet to the runspace configuration

When we replace the clear-host function, we’re going to also want to remove the existing function, but that’s not typical.  Here’s the code:

First, the cmdlet class (I usually put all of the cmdlets in the same file, rather than having a single file for each class, but that’s just a preference):

Imports System.Management.Automation
Imports System.ComponentModel

 _
Public Class ClearHost
    Inherits Cmdlet

    Protected Overrides Sub EndProcessing()
        MainForm.PowerShellOutput.Clear
    End Sub
End Class

To add the cmdlet to the runspace (and remove the function), I added these lines after the r.Open() call:

InvokeString("remove-item function:clear-host")
r.RunspaceConfiguration.Cmdlets.Prepend(New CmdletConfigurationEntry("clear-host",GetType(ClearHost),Nothing))
r.RunspaceConfiguration.Cmdlets.Update()

Now, finally, on to the promised treeview manipulation.  I want the cmdlet to be fairly simple, allowing you to specify the name of the label of the new node, and optionally the label of the parent node and an object to attach to the node (we’ll put it in the tag property of the treenode).  We’ll also need to expose the treeview control in a shared member of the form (since the cmdlet doesn’t have a reference to the specific window we instantiate).

First, here’s the cmdlet.  I’ve tried to make the code as simple as possible, so there are no tricks involved.

 _
Public Class NewTreeNode
	Inherits Cmdlet

	private _nodename as String=""
	private _parentnodename as String=""
	private _object as PSObject=nothing
 _
    Public Property NodeName() As String
        Get
            Return _nodename
        End Get

        Set(ByVal value As String)
            _nodename = value
        End Set

    End Property
 _
    Public Property ParentNodeName() As String
        Get
            Return _parentnodename
        End Get

        Set(ByVal value As String)
            _parentnodename = value
        End Set

    End Property
 _
    Public Property PSObject() As PSObject
        Get
            Return _object
        End Get

        Set(ByVal value As PSObject)
            _object = value
        End Set

    End Property

    Protected Overloads Overrides Sub EndProcessing()
		MyBase.EndProcessing()
		Dim _node As TreeNode
		Dim _parent As TreeNode
		_parent=PWBUIHandling.FindNodeInTree(_parentnodename,mainform.Tree.Nodes)
		If _parent is nothing then
			_node=MainForm.Tree.Nodes.Add(_nodename,_nodename)
		Else
			_node=_parent.Nodes.Add(_nodename,_nodename)
		End If
		_node.Tag=_object
    End Sub
End Class

In the form, we’ll need to add a treeview (I also added a second splitter to help organize the UI, but that’s obviously not necessary).  Adding the shared property,setting it, and adding the cmdlet to the runspace complete the changes:

Public Partial Class MainForm

Public Shared PowerShellOutput As textbox
public shared Tree as TreeView
private host as new PowerShellWorkBenchHost
private r As Runspace=RunspaceFactory.CreateRunspace(host)
	Public Sub New()
		' The Me.InitializeComponent call is required for Windows Forms designer support.
		Me.InitializeComponent()

		PowerShellOutput=txtOutput
		Tree=treeView1
       	r.ThreadOptions=PSThreadOptions.UseCurrentThread
        r.Open()
        InvokeString("remove-item function:clear-host")
      	r.RunspaceConfiguration.Cmdlets.Prepend(New CmdletConfigurationEntry("clear-host",GetType(ClearHost),Nothing))
      	r.RunspaceConfiguration.Cmdlets.Append(New CmdletConfigurationEntry("new-treenode",GetType(NewTreeNode),Nothing))
      	r.RunspaceConfiguration.Cmdlets.Update()

   End Sub

With that, let’s see how it works:

Obviously, I haven’t built an application that’s ready for use, but I think it is a good example of how you can use the PowerShell APIs to create a scriptable environment that you can customize.  And the fact that the code written to make it happen is less than 200 lines is a testament to the useful nature of the API (actual hand-coded lines, that is, there are about 400 lines in the whole project).

What’s next?  I think I’ll stop on the tutorial and segue into the codeplex project I’m starting (it should be live in the next week or 2).  In it, you should find things like

• Syntax Highlighting (thanks to AvalonEdit)
• Advanced docking interface (thanks to AvalonDock)
• Tab Expansion
• Custom pop-up menus for UI objects (like the nodes in the tree, for example)
• Whatever else I (or anyone who wants to contribute) think of

-Mike

P.S.  I just realized that I forgot to include the FindNodeInTree function that the cmdlet called.  I hate that the treeview class doesn’t include a Find method.  Here’s the code:

	Function FindNodeInTree(nodename As String, nodes As TreeNodeCollection) as TreeNode
		dim rtn as TreeNode =nothing
		If nodes.ContainsKey(nodename) Then
			Return nodes(nodename)
		Else
			For Each node As treenode In nodes
				rtn=FindNodeInTree(nodename,node.Nodes)
				If rtn IsNot Nothing Then
					return rtn
				End If
			Next

		End If
		return rtn
	End Function

In the last post, we got to the point that we were actually using the new host objects that we implemented, but we still hadn’t provided anything more than trivial implementations (throwing an exception) for the methods that make a custom host useful, e.g. the write-* functions.

Before we do that, we need to discuss interaction between PowerShell (the engine) and windows forms (though we would have had the same issue with WPF).  In PowerShell 1.0, the engine creates its own thread to run the Invoke() method, and doesn’t provide a way to change that thread’s apartment model, which is MTA.  The reason that is important is that to interact safely with Windows Forms (or WPF), you need to be in the same thread.  The bottom line is that when using the 1.0 object interface, you can’t directly interact with the window environment.  Which means that any hopes you had of writing some simple code to append text to the textbox in the WriteHost method are going to be dashed.  Unless, of course, you use the 2.0 object model.  The designers realized the shortcoming, and in 2.o they allow you to change the child thread to STA.

So now we have a couple of choices.  As I mentioned in part 3, I was purposely using the 1.0 object model, since 2.0 wasn’t final, and the 1.0 methods would work fine in a 2.0 install.   One thing we could easily do is switch the code to 2.0, set the threading model to STA, and go on our merry way.  Another approach would be to have the Host objects interact with the user interface indirectly.  One way to do that would be to simply have the host methods package their arguments into an object, and add the object into a queue that is consumed in a timer event handler on the form.  This works quite nicely, and provides an easy separation between the host and the interface.

For now, though, for the sake of simplicity (and to keep the code from getting longer than anyone would care to read), we’ll just use the 2.0 object model.  As I mentioned in part 4, I plan to create a project on Codeplex for a more complete host than I can really create in a tutorial.  It will include code to keep the host and interface separate (which I think I like better).

Here is the revised code in the form to use the 2.0 model (I’ve moved some of the declarations out of the Click method because the objects don’t need to be recreated each time):

Public Partial Class MainForm

public shared PowerShellOutput as textbox
private host as new PowerShellWorkBenchHost
private r As Runspace=RunspaceFactory.CreateRunspace(host)
	Public Sub New()
		' The Me.InitializeComponent call is required for Windows Forms designer support.
		Me.InitializeComponent()

		PowerShellOutput=txtOutput
       	r.ThreadOptions=PSThreadOptions.UseCurrentThread
        r.Open()
     End Sub

    Sub RunToolStripMenuItem1Click(sender As Object, e As EventArgs)

 		dim ps As powershell=PowerShell.Create()
        ps.Runspace=r
        ps.AddScript(txtScript.Text)
        ps.AddCommand("out-default")
        Dim output As Collection(Of psobject)
        output=ps.Invoke()

    End Sub

End Class

The line of code that will allow the host methods to interact with the form is:

r.ThreadOptions=PSThreadOptions.UseCurrentThread

A few other changes that should be noted are:

• Adding a shared member PowerShellOutput to use in the host to update the textbox
• Switching from out-string to out-default (now that we’re handling host output, we can let the default behavior send the objects in the pipeline to the host)
• Removing the loop through the output (because of the previous point)

With that being said, I’ll make another comment.  If you’re trying to follow along with this series (as in, you have an editor open and are copying code in and trying it as you go), you’ll want to make sure you set a breakpoint on each of the throw statements in the host classes.  If you don’t do this, you won’t know what methods you need to implement (except by trial and error).  I have spent several hours debugging when the breakpoints would have showed me the problem immediately.  Please learn from my mistakes.

Now, we can finally get to coding the output routines.  We obviously need to implement some write* method, but there are several.   To figure out which one, I tried to run write-host “hello” and dir (fairly simple commands) and it turns out that we need to implement these methods for those to work:

• WriteLine
• Write  –both versions
• PSHostRawUserInterface.ForegroundColor
• PSHostRawUserInterface.BackgroundColor

I really wasn’t expecting the last color methods to come into play until we started passing them to the write-host cmdlet (which is why I lost so much time debugging).  Here are the implementations I’m using for now.  Note that we’re somewhat limited by the choice of a textbox (rather than a more fully-featured control) for output.
In PSHostUserInterface:

	Public Overloads Overrides Sub Write(value As String)
		If value=vblf Then
			mainform.PowerShellOutput.AppendText(vbcrlf)
		else
			MainForm.PowerShellOutput.AppendText(value	)
		End If
	End Sub

	Public Overloads Overrides Sub Write(foregroundColor As ConsoleColor, backgroundColor As ConsoleColor, value As String)
		MainForm.PowerShellOutput.AppendText(value	)
	End Sub

	Public Overloads Overrides Sub WriteLine(value As String)
		MainForm.PowerShellOutput.AppendText(value+vbcrlf)
	End Sub

and in PSHostRawUserInterface:

	Public Overloads Overrides Property ForegroundColor() As ConsoleColor
		Get
			return ConsoleColor.Black
		End Get
		Set
			Throw New NotImplementedException()
		End Set
	End Property

	Public Overloads Overrides Property BackgroundColor() As ConsoleColor
		Get
			return ConsoleColor.White
		End Get
		Set
			Throw New NotImplementedException()
		End Set
	End Property

With those changes, we are (finally) using the custom host for output. Here’s an obligatory screenshot:

Output at last!

So what’s next? Obviously, we should fill in appropriate implementations for the other write-* functions. Other than write-progress, they shouldn’t prove any challenge. Write-progress, on the other hand, would really look nice as a progressbar (possibly in a status bar?). There are a few other things to consider:

• clear-host is implemented as a function which uses the rawUI class to perform it’s stuff…that probably won’t work in out GUI app
• Colors (if you choose to implement them) are going to be specified using the ConsoleColor class (which is different from the Color class used by Windows Forms)
• Profiles….do you want to load them?  Do you want to have a profile specific to your new host?
• What about interacting with the GUI in other ways?

The last point is the main thing that drove me to write my own host.  You may be fortunate enough to have a GUI tool to do all of your administration duties, but I suspect that most of us have several tools that we have to switch between to get stuff done.  And those tools are probably not powershell-ready.  Writing your own host allows you to build your “dream environment”, combining the best features of your favorite tools, and adding script-support in the process.

Next time, we’ll see about doing something different…adding data from powershell into a treeview control (in the host, of course).

As usual, please let me know if you’re enjoying this series.

Mike