Summary: Customize the Windows PowerShell ISE by automatically adding custom headers to new scripts. The Microsoft Scripting Guys show you how.

Microsoft Scripting Guy Ed Wilson here. Oliver, my friend in Regensburg, Germany, was having a problem adding a user to a group from another forest. He kept asking me questions when I was either in a meeting, working on a Scripting Guy article, or talking on the phone—it was getting embarrassing because I really wanted to help him. Finally, I decided to use Outlook 2010 to schedule a Live Meeting with him.

The time arrived, and we spent a cool hour working through some of the issues. Today, he sent me an IM that said he had the script working. He has promised to write a Guest Blogger article about the script and the issues he was having. Interestingly enough, I did not meet Oliver when I was in Regensburg. It was only after I became a Scripting Guy that I met him. Regensburg is a great place to take pictures. The following photo is one I took during my time there while I was teaching a Windows PowerShell class.

It is not that I did not want to help Oliver, but that my time just seems to get away from me. I have a very heavy schedule, which means I rely extensively on Microsoft Outlook 2010 reminders, tasks, and appointments. If I were ever to lose my Outlook data, I would be in serious trouble. Hmmm, maybe I need to write a script to back up Outlook data. Just added that to my Outlook tasks.

It was not on my calendar, but I decided to add a function to my Windows PowerShell profile that would add the header information to a script in the Windows PowerShell ISE. This is something I have been doing manually for nearly two years. It does not take but a minute for me to type this information, but if you think about all the Windows PowerShell scripts I have written in the last two years, the function would have saved me at least enough time to take a day off.

The Add-HeaderToScript function is shown here.

Add-HeaderToScript

Function Add-HeaderToScript
{
  <#
   .Synopsis
    This function adds header information to a script 
   .Example
    Add-HeaderToScript
    Adds header comments to script 
   .Example 
    AH
    Uses alias to add header comments to script
   .Notes
    NAME: Add-HeaderToScript
    AUTHOR: Ed Wilson, msft
    LASTEDIT: 09/07/2010 19:37:28
    KEYWORDS: Scripting Techniques, Windows PowerShell ISE
    HSG: WES-09-12-10
   .Link
    Http://www.ScriptingGuys.com
 #Requires -Version 2.0
 #>
 $header = @”
# —————————————————————————–
# Script: $(split-path -Path $psISE.CurrentFile.FullPath -Leaf)
# Author: $env:username
# Date: $(Get-Date)
# Keywords:
# comments:
#
# —————————————————————————–
“@
 $psise.CurrentFile.Editor.InsertText($header)
} #end function add-headertoscript 

The comment-based help was added by the Add-Help function I added to my Windows PowerShell ISE profile yesterday.

The same technique for the Add-HeaderToScript function is followed that was used in the Add-Help function. A here-string holds the header information, and the InsertText method adds the header at the current insertion point using the command shown here:

$psise.CurrentFile.Editor.InsertText($header)

Because an expanding here-string is used, it means that many of the values required by the header block can be obtained automatically. For example, if the script has been saved, the command shown here will return the name of the current script:

$(split-path -Path $psISE.CurrentFile.FullPath -Leaf)

If the script has not been saved, the Script: field will be set to untitled.ps1. The Author: field and the Date: field of the header block are filled using the same techniques that were used in yesterday’s Add-Help function. Again, if you do not like the user name stored in the $env:username environmental variable, you can hard code the value for the Author: field.

Because Add-HeaderToScript is kind of long to type, you have two choices. You can use tab expansion and type Add-He and press Tab, which will complete the function name. Or you can create an alias. I added the following command to my Windows PowerShell ISE profile to create an alias called ah to call the function. Because it is possible you might have an alias ah already used (it is not taken by default), I added a test for the ah alias, and only create it if the alias is available. The code is shown here:

if(!(Test-Path alias:ah))

 {

  New-Alias -Name ah -Value add-headertoscript -Description “MrEd alias” |

  Out-Null

  }

When I run the Add-HeaderToScript function by using the ah alias, the header shown in the following image is added to the script. Note that this script was previously saved with the name that appears in the Script: field.

Well, I think I am going to break out my saxophone, go outside, and annoy the neighbors for a while. Actually, the neighbor’s dog is a real fan and cannot resist the temptation to sing along with me. He does not seem to know all the words to “Sweet Home Chicago” but he really gets into the spirit.

We invite you to follow us on Twitter and Facebook. If you have any questions, send email to us at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow when we will begin Guest Blogger Week. We have some absolutely fantastic posts lined up. Until then, peace.

Ed Wilson and Craig Liebendorfer, Scripting Guys