Tag Archives: Help

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.