Friday Fun: A PowerShell Macro

Today’s Friday Fun is a little different in that it showcases two things I use almost every day: Microsoft Word and PowerShell. I am writing new articles and material almost daily and of course very often the content is PowerShell related. Usually I use the blog post template in Word to make it easier to upload. This works great because I can insert links in the Word document and they will be maintained when copied to WordPress. One of the steps I’ve started taking in my writing is to include a link to online help for a cmdlet.

For example, if I am writing about Get-WinEvent I’ll include a link on the cmdlet name. Of course I’m not going to manually get the link, copy it and create the hyperlink in Word. So I created a Word macro that calls a PowerShell script to get the online link and insert it as a hyperlink. Here’s how this all works.

There are a few ways to get the online help link for a given cmdlet. You could retrieve the HelpUri with Get-Command.

Or you can retrieve it using Get-Help.

As you can see the links are different, even though the online content is very similar. But since the latter is what you would get if you ran Get-Help Get-Service –online, I decided to go with that. I put together a simple script.

The function writes the link to the pipeline if found, otherwise it writes $Null. I’ll explain why in a moment.

With this script, I now turn to Word and created this macro.

I couldn’t find a way to capture the output of the PowerShell command so I ended up creating a temporary file that contains the link. If nothing was found then the file will have a 0 length. I found this easier because the macro reads the file and saves the contents to a variable, link. If the length of link is > 0 then Word inserts the hyperlink, complete with a constructed screen tip.

I stored the macro in Normal.dot so I always have it available.

I even gave it a keyboard shortcut under File – Options –Customize Ribbon

Finding ways to automate the dreary tasks from my day is very rewarding, plus I almost always learn something new. Hopefully you did to.

Turn On PowerShell Help Window

talkbubble-v3Here’s a little suggestion for today that might make it easier for you to use PowerShell. In PowerShell 3.0, the Get-Help cmdlet includes a terrific new parameter called -ShowWindow. When you ask for help with this parameter, you get complete help in a new window. The window is re-sizable, searchable and customizable. I love this thing because it means I can look at full cmdlet (or function) help without having to scroll back and forth in a console window.

help-window

Now for the fun part. PowerShell 3 also includes a feature where you can define default parameter values. These values are stored in a hash table where the key takes for the form “cmdletname:parametername” and you can use wildcards. In your PowerShell profile script add this line.

Now, whenever you run a help command using either Get-Help or the Help function, you will automatically get the popup help window. This won’t affect help commands like these:

You can always remove the entry from the $PSDefaultParameterValues hash table, or temporarily not use it by explicitly setting ShowWindow to $False.

Now you have no excuse for ignoring PowerShell’s help documentation.

Create an HTML PowerShell Help Page

Yesterday I posted an article about getting the online url for a cmdlet help topic. Today I want to demonstrate how we might take advantage of this piece of information.

Since the link is already in the form of a URL, wouldn’t it make sense to put this in an HTML document? At first glance, you might take the command from yesterday and pipe it to ConvertTo-HTML.


Get-Command -CommandType cmdlet | Get-Help |
Select Name,Synopsis,@{Name="URI";Expression={
($_.RelatedLinks | select -ExpandProperty NavigationLink | where {$_.uri}).uri}} |
Where {$_.URI} | ConvertTo-HTML -Title "Help Links" | Out-File c:\work\pshelp.htm

This code will work just fine. But if you look at the resulting file, we don’t have a link. I suppose it would be nice if ConvertTo-HTML could auto-detect URLs and automatically add a link, but it looks like we’ll have to do it. We could probably use a custom hash table to insert the HTML Anchor tags so here’s the first attempt:


Get-Command -CommandType cmdlet | Get-Help | Where {$_.RelatedLinks} |
Select Name,Synopsis,@{Name="URI";Expression={
#add the link tags as part of the output!
$link=$_.RelatedLinks | select -ExpandProperty NavigationLink | where {$_.uri}
if ($link.uri) {
$uri=$link.uri
Write "$uri"
}
else {
#no link so write a null
write $Null
}
}} | Where {$_.URI} | ConvertTo-HTML -Title "Help Links" |
Out-File c:\work\pshelp.htm

One additional change I made was to filter out cmdlets with no related links. Then in the expression scriptblock I can create a new value based on the URI value if it exists. But there is a problem with this, which you’ll see immediately if you run this code. ConvertTo-HTML sees the value of my new URI property and escapes the < and > characters.

That doesn’t help. But this is where the fact that ConvertTo-HTML only creates HTML code because we can parse the code and do a simple replace. Let me jump ahead and pull part of the finished dessert from the oven.


Function Convert-HTMLEscape {

<# convert < and > to < and >
It is assumed that these will be in pairs
#>

[cmdletbinding()]

Param (
[Parameter(Position=0,ValueFromPipeline=$True)]
[string[]]$Text
)

Process {
foreach ($item in $text) {
if ($item -match "<") {
<# replace codes with actual symbols This line is a shortcut to do two replacements with one line of code. The code in the first set of parentheses revised text with "<". This normally gets written to the pipeline. By wrapping it in parentheses it tells PowerShell to treat it as an object so I can then call the Replace() method again and add the >.
#>
($item.Replace("<","<")).Replace(">",">")
}
else {
#otherwise just write the line to the pipeline
$item
}
}
} #close process

} #close function

This function takes string input, presumably from ConvertTo-HTML and replaces the HTML escapes with the “real” characters. This I can use to write to the file.


...| Where {$_.URI} | ConvertTo-HTML -Title "Help Links" | Convert-HTMLEscape | Out-File c:\work\pshelp.htm

One of the reasons I put this in a function is to make it re-usable for future projects where I might need to escape these characters again. We’re getting closer. One last thing before we ice the final dessert: I have been using an expression to get all cmdlet help. But I like flexibility. What if tomorrow I only want a page with New* cmdlets from PowerCLI? So once again, I took my code that works just fine from a prompt into a more flexible and re-usable function.

Function Get-HelpUri {

[cmdletbinding()]

Param(
[Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a cmdlet name",
ValueFromPipeline=$True,ValueFromPipelinebyPropertyName=$True)]
[ValidateNotNullorEmpty()]
[string]$Name
)

Process {
Write-Verbose "Processing $name"
Get-Help $name | Where {$_.RelatedLinks} |
Select Name,Synopsis,@{Name="URI";Expression={
#add the link tags as part of the output!
$link=$_.RelatedLinks | select -ExpandProperty NavigationLink | where {$_.uri}
if ($link.uri) {
$uri=$link.uri
Write "$uri"
}
else {
#no link so write a null
write $Null
}
}}
} #close process

} #close function

This will write a custom object with the cmdlet name, synopsis and URI property with the HTML code. I still need to convert to HTML and then fix the tags but I can verify it works.


PS C:\> get-command new-object | get-helpuri | ConvertTo-Html |Convert-HTMLEscape



HTML TABLE

Name Synopsis URI
New-Object Creates an instance of a Microsoft .NET Framework or COM object. http://go.microsoft.com/fwlink/?LinkID=11335
5


The icing is to include some style via a CSS file. Here’s a short script on how I might build a file for all of the cmdlets in my current session.


Write-Host "Building cmdlet help report" -ForegroundColor Green

#the file to create
$file="c:\work\cmdletonline.htm"

#be sure to change the path to the CSS file if you want to use it
$cssPath="c:\scripts\blue.css"

#optional image
$imagePath="c:\work\talkbubble.gif"

#some pre content
$preContent=@"



Cmdlet Online Help




"@

#some post content
$postContent=@"

Help for cmdlets found on $env:computername on $(Get-Date)
"@

#a title for the report
$Title="Cmdlet Help"

<# Get all cmdlets in the current session, send them to the Get-HelpURI function to parse out help URLS, filter out those without a link, pass the remaining to the Convertto-HTML to generate HTML code which is piped to my function to replace < with > and the final HTML code is piped to
a file.
#>
Get-Command -CommandType cmdlet | Get-HelpURI | Where {$_.URI} |
ConvertTo-Html -PreContent $PreContent -PostContent $postContent -Title $Title -cssUri $cssPath |
Convert-HTMLEscape | Out-File -FilePath $file -Encoding ASCII

Write-Host "Finished. See $file for the results" -ForegroundColor Green

And here’s the final result in Internet Explorer.

Ok, maybe you don’t have a compelling need for this exact script, but I hope you picked up on the importance of writing code for re-use and taking advantage of the pipeline.

If you’d like to try my code out for yourself, including the graphic and CSS file, download this zip file.

PowerShell 3.0 Easy Rider

Today I gave an Live Meeting presentation for the PowerShell Virtual User Group. When the recording is posted I’ll update this post. I spoke about new features in Windows PowerShell 3.0 that I think will make it easier for people to use PowerShell more efficiently. I think they even might find it fun. Here is what I covered.

 

 

AGENDA
 New Help Options
 Default Parameter Values
 Simplified Syntax
 Improved Tab Completion
 Redirection Options
 Improved ISE Experience

The presentation started with some introductory slides, but most of the presentation was demo. As promised here is my presentation and a zip files with my demos and sample script.

Here is the link to the recording

Create a Master PowerShell Online Help Page

As I hope you know, PowerShell cmdlets can include links to online help. This is very handy because it is much easier to keep online help up to date. To see online help for a cmdlet use the -online parameter.

I decided to take things to another level and create an HTML page with links to online help

I created a relatively simple script called New-OnlineHelpPage.ps1. The script uses Get-Command to retrieve a cmdlet name, it’s module or snapin and it’s help link.

This expression filters out cmdlets without an online link. By default the script sorts by cmdlet name but if you use the -SortModule parameter, it will sort by module or snapin. Get-Command treats them as the same. The data is piped to ConvertTo-HTML to create the HTML report.

The function lets you specify a CSS file path which is stored in $CSS and I include a sample one in the download below. But now for the fun part. The help url looks like a link but it isn’t actionable. Remember that ConvertTo-HTML doesn’t create a file, it creates HTML which means I can intercept it and use a regular expression to find the URL and replace it with HTML code that turns it into a link. At the end of the process I finally pipe the HTML to Out-File to create the report.

The last step is to launch the HTML page using Invoke-Item. This will launch the file with whatever application is associated with the file extension you specified.

The script takes a few parameters.

The file it creates is stored in you TEMP folder by default. The script will process any cmdlet loaded in your PowerShell session so you can add snapins like PowerCLI or modules like ActiveDirectory and get those links as well. What you end up with is a single page with links to all the online help.

Even if this isn’t of use, I hope you picked up a little knowledge about Get-Command and ConvertTo-HTML. You can download a zip file with my script and a sample CSS file here.