You Can Do -Help[Building HELP into your custom functions is a good thing! Here's a template to help you through it...]

Do you write your own Powershell functions for use in your AD or Exchange environment? Are they user friendly? Do others use them, or would you like them to? Do you add a -Help switch and display help text in your custom functions? You should! It's well worth your while to build in some HELP for a few reasons...

First, they won't be running to you to ask you syntactical questions even though you've told them six times already. Additionally, you won't be asking yourself those same questions when you try to use your awesome new function three weeks from now. Lastly, building inline help into your functions will force you to better understand how they work, as well as demonstrating your superior scripting abilities to your boss (make sure you demo the function at an upcoming staff meeting). Read on to see if your functions measure up.

Copy the code (link at end of post) and paste it into your Powershell session window to define the function called "MyTestFunction". To test the functionality, type the following at the Powershell prompt:

MyTestFunction (to show usage syntax)
MyTestFunction -Help (to display abbreviated help)
MyTestFunction -Help -Full (to display full help)
MyTestFunction SomeArgument (to simulate processing of SomeArgument)

---

Notes and Code for this post:
Get the shell function code here.
Although the copy code & "paste into your Powershell session" method of defining the function works for testing the function, the content should really be copied and pasted into an editor such as notepad.exe, then saved as a .ps1 script. This will retain the HELP text formatting (blank lines) that get stripped out when copy/paste into session window is used. Try it, you'll see what i mean.

This code works with Powershell v1 and v2.

Was there enough detail in this post?

.end


more...

A Customized Get-Mailbox... and more.

I like to make things easy for myself when possible. That being said, I also spend a good amount of time writing scripts that will help with that. Therein lies the rub. Is it worth my while to spend hours getting a script just right? The short answer, Yes I think it is. The somewhat longer answer and reasons behind it, is a topic for another day.

Often when I'm troubleshooting user issues, I'll need to get the user's mailbox information, usage statistics, and frequently their OWA settings. Getting this information from the Exchange Management Shell will require me to enter three cmdlets (once I figure out what the user's alias is). I can never remember to use the -ResultSize Unlimited switch until it's too late, nor can I remember to use the -ANR (Alternative Name Resolution) switch so I can search for FirstName, LastName, Alias, PrimarySMTPAddress, etc.

My solution... write a script that calls Get-Mailbox with the -ResultSize and -ANR switches built into it. But why stop there? The script will prompt for which of the 19 Michaels the search returned, then display full Get-Mailbox, Get-CASMailbox, and Get-MailboxStatistics information for the requested user. Now I have all the information I typically need to troubleshoot a user problem.

Are we finished? Nope. Why not turn this script into a function and load it in our Powershell $Profile so there is no need to dot source it? Sure, now we can run it no matter what our current directory is. Now we're talkin' right?... or are we? The problem now is... I'm not the only Exchange Admin in my group, and what if he thinks my script is cool and wants to use it? Ah... but we can handle that too! Yes indeed, instead of loading the function in Powershell's personal profile (see Understanding Powershell Profiles), we can add it to the machine profile instead. Now any user that logs onto the box and runs Powershell will have the function pre-loaded and available for use during their session.

The Home Stretch
This is all good stuff, and is working like a charm. We get to thinking about this a little more and realize... "Hey, I can only use this awesome new script on the server that I'm logged onto." Not really a problem as the script can access information from other machines. However, what if my buddy Bryan wants to use the script but he's logged onto one of the Hub/CAS servers and the script lives on the Mailbox Cluster? Several options here. The one we have been using is...

...you guessed it, another script! This script is just a simple file copy script to distribute the machine profile to the other Exchange servers in our environment. The script will check the current server and will, after getting confirmation from the user, copy the local machine profile to the other Exchange servers. This works well for us and provides a consistent environment while working in Powershell on any of our Exchange servers.

Note: For those of you who are running Exchange 2007 SP2, you can install Powershell v2, which gives you the import-module cmdlet, allowing you to locate your functions on a network drive and load them from a share. Change the function in one spot, and all of your servers are up to date at the next Powershell session login. Don't forget to name the file you store your functions in with a .ps1 extension, the import-module cmdlet won't allow .txt extensions.


.end
more...