Over the last few weeks I’ve posted articles on the different parameter validation options in Windows PowerShell. More than one person suggested consolidating the articles. That seemed like a good idea. There were a variety of ways to handle this but I wanted something more PowerShell-oriented. Then I realized, why not produce PowerShell About topics? I could create a module that primarily was a collection of about topics on scripting in PowerShell. Import the module and you get the documentation.

In fact, this is a slick idea you might want to take advantage of: create a PowerShell module with nothing but documentation delivered via About_* files. If you are spending a lot of time in the shell, stay there! But before I get sidetracked, let’s look at the module I’m calling ScriptingHelp.

As I said the module is mostly a collection of About_* topics based on some of my blog articles. Then I realized I wanted to make it easier to expose them so I threw together a brief function called Get-ScriptingHelp.

The About topics are edited and revised versions of material previously posted on my blog.

I plan on contributing additional content over time based on previous blog articles, suggestions or anything that comes to mind that I think can help you write more effective PowerShell scripts and functions.

To that end, I have also included a function to help you start scripting even faster. It is a new function wizard called Invoke-FunctionWizard. When you run the wizard, you will be prompted for information about your new function such as its name and parameter information. The wizard will then write a string object with the skeletal outline of your new function, complete with comment-based help. If you run the wizard in the ISE it will automatically insert the text into the currently open file.

But perhaps you’d like to see all of this in action.

I hope you’ll let me know what you think and if you find this useful or worthy of continued development. You can download a zip file of ScriptingHelp_0_9. Extract the folder as a subfolder under C:\Users\\Documents\WindowsPowerShell\Modules. Then import the ScriptingHelp module. This should work in both the console and the PowerShell ISE. Enjoy!

I’ve been writing about the different parameter validation attributes that you can use in your PowerShell scripting. One that I use in practically every script is [ValidateNotNullorEmpty()]. This validation will ensure that something is passed as a parameter value. I’m not talking about making a parameter mandatory; only that if the user decides to use the parameter that something is passed. Let’s look at my demo.

I’ve used the attribute on both parameters. The first parameter I’ve also made mandatory which makes it more likely that something will be entered. But if not, then the script will fail.

I would get a similar message if the user forgot to complete the command.

Even though I’m using a default value for Computername, as soon as the parameter is detected PowerShell assumes I’m going to use a different value.

Validation should work for missing values, a variable that might be null, or in general anything that is meaningless. However, it won’t prevent something quirky like this:

The variable, while semantically meaningless to us, is not null or empty but a string of 1 space. If there’s the chance you might run into this situation then you can add additional validation checks to the parameter.

If you’d like, feel free to download Demo-ValidateNotNull and see for yourself.

I spoke this past weekend at a SQL Saturday event in Rochester, NY. My first SQL Saturday event and it was a lot of fun. A great turnout and some very interested attendees. I did three PowerShell sessions on jobs, scheduled jobs/tasks and an intro to workflows. The latter talk I think blew out some neurons on a few people, but I believe they were still enthusiastic about it.

For SQL Saturday attendees, I’ve posted my slide deck and demo files on the conference site. For everyone else, if you are interested, I’ll also make them available here.

PowerShell 3 Jobs and Tasks
PowerShell Background Jobs
PowerShell Workflow Basics

I expect I’ll be covering this material again in the future here as well as in my Prof. PowerShell column. And as always, if your organization is thinking about some private PowerShell training or mentoring, let me know.

At the PowerShell Deep Dive in San Diego, I did a lightning session showing off something I had been working on. Sometimes I don’t know what possesses me, but I felt the need for a better way to navigate my PowerShell scripts files that had many functions. Some files, especially modules, can get quite long and contain a number of functions. When using the PowerShell ISE I wanted a faster way to jump to a function. The problem is I don’t always remember what I called a function or where it is in the file. It is very easy to jump to a particular line in the ISE using the Ctrl+G shortcut.

So I started with some basics.

I decided I’d use a regular expression pattern to find my functions. I write my functions like this:

So I came up with a regex pattern to match the first line and to include the Filter keyword as well.

I first thought of searching the content of the current file, but that won’t give me a line number. Then I thought of Select-String. With my regex pattern, I can get the content of the current file and pipe it to Select-String. The match object that comes out the other end of the pipeline includes a line number property (awesome) and the matching line. I decided to do a little string parsing on the later to drop off the trailing curly brace.

Because I’m in the ISE I felt the need to stay graphical, so my first thought was to pipe the results to Out-Gridview.

Here’s a sample result.

Now I can see the function name and line number. In the ISE I can do Ctrl+G and jump to the function. Of course, if I modify the file and line numbers change I need to close the grid and re-run my command. But wait, there’s more….

I’ve never done much with the WPF and figured this would be a great opportunity to do something with the ShowUI module. I already had the data. All I had to do was create a form with ShowUI. This is what I ended up with.

The result is a stack panel of buttons in a scroll control. The button shows the line number and function name.

When a button is clicked, the function gets the line number and automatically jumps to it. Originally I was leaving the control open, but this means the function is still running. And if I change the script the line numbers are off so I simply close the form after jumping to the function.

In the end, I packaged all of this as a script file that adds a menu choice. If ShowUI is available, the function will use it. Otherwise the function defaults to Out-GridView.

Now, I can click the List Functions menu choice and I’ll get a graphical list of any functions in the current file. I’m sure the regex could be tweaked. I’m also sure there are improvements I could make to the ShowUI code, but it works.

Download Get-ISEFunction and let me know what you think.

I continue to tinker with Office applications and Windows PowerShell. I was looking at an Excel issue related to opening a new workbook. To verify the problem wasn’t PowerShell related I offered a suggestion to try creating an Excel workbook in VBScript.

In VBScript creating a blank workbook in Microsoft Excel can be accomplished with three lines of code.

In Windows PowerShell we essentially use the same 3 lines.

But PowerShell is all about the objects, so how about a quick and dirty approach? Something perhaps in one line:

You could easily build a simple function to run the 3 lines it takes to open a new Excel workbook but one-liners like this make me smile. Granted, I’m probably not likely to use it, but if nothing else I think it reinforces the object nature of Windows PowerShell.

Each expression nested in () is treated as an object. The inner most expression using New-Object, creates the Excel application object which has a Workbooks property that is an object with an Add() method. Invoking this method creates the workbook object. If I stopped there Excel would be running but not visible. So I get the Application property of the workbook object, and set the Visible property to True.

This command doesn’t offer any way to continue working with Excel from PowerShell; it only opens a new workbook. Let me be clear, I’m not advocating that this is how you work with Excel from PowerShell. I think you will need scripts like the ones I posted from my Deep Dive session. But this one-liner demonstrates what is possible with PowerShell and maybe it will add a little smile to your day as well.

Last week at the PowerShell Deep Dive in San Diego, I did a short presentation on integrating Microsoft Office applications like Excel and Word with Windows PowerShell. I easily could have spoken much longer and probably tried to cram too much in. I spent a lot of time with my demos. I expect at some point a video of my talk will be posted on the TEC site. In the mean time you can download a PDF of my slide deck and a zip file with all of my demos. Some of the scripts have been revised slightly since my presentation. The scripts are NOT intended for production use. They are demonstration and proof-of-concept scripts. Many of them have hard coded paths for additional files so read them carefully before you try to run. I’ve tried to comment extensively so you can understand what is going on, but this is admittedly a complicated topic. I’m hoping to create some additional videos around these demos, but if you have questions please post a comment.

Enjoy.

Recently, Josh Atwell posted a PowerShell script that performed a countdown. Naturally, I was inspired and did the whole “embrace and extend” thing. Don’t get me wrong: Josh’s script is perfectly fine. I saw some opportunities to try some things and use it as a teaching device. If nothing else, let’s have a little fun.

First off, here’s my version, then I’ll go over a few highlights.

The basic premise hasn’t really changed. Run the function specifying the number of seconds to count down and at the end of the countdown display a message. I thought why not really do something? So I added an optional Scriptblock parameter. At the end of the countdown, it will be executed using Invoke-Command.

Next, I decided to add a way to abort the countdown. If you run the function in the ISE and use the Progress bar parameter, you can click the Stop button. In the console, you could press Ctrl+C but that seemed a little heavy handed to me so I inserted code to watch for a key press, specifically the ESC key. If the key press is detected, I set a flag variable to False and the seconds to 0 to break out of the While loop.

After the loop I inserted commands to check if the countdown was aborted or not. If not, then I display the message and run the scriptblock, if supplied.

I like the use of Write-Progress. I don’t think it gets enough attention. I decided to add in the progress bar which is incremented based on a percentage of how much time is to go.

I’m subtracting the percent value from 100 so that the progress bar moves from left to right. It looked odd to me to move from “Full” to “Empty”, although I suppose for a countdown that is more accurate. You can switch this back.

My last change is how the countdown is handled in the console, if you don’t use the progress bar. In Josh’s version he cleared the screen and then wrote the current time, clearing the screen each time. The effect is you see the number change in the upper left corner of the console. But what if you don’t want to clear the screen? Writing the number will use a new line for each value. Using Write-Host with -NoNewLine will simply append to the current line and look ugly. So I decided to have some fun with raw host data.

First, I grab the coordinates of the cursor’s current position using the RawUI property from $host.

I want this because I can use the coordinates to put the cursor to a specific location in the console.

I also added code and logic so that the number is displayed in Green using Write-Host until it reaches 10, at which point it is written to the console in red.

I also use the coordinates for some fun if you use -Clear. I put the countdown timer in the center of the console window. In order to do that I had to find the dimensions of the window and divide by 2, treating each value as an [INT].

Finally, I decided to also center the message. This meant figuring out the message length and then adjusting the X coordinate.

Curious to see what this looks like? (the clip has no audio)

You can download Countdown2 and load the Start-Countdown function into your PowerShell session. Be sure to read the help.

claim post. Nothing to see here.

Here’s another parameter validation attribute you might want to use in your PowerShell scripting and functions. If your parameter can take an array of values, you might want to limit that array to a certain size. For example, your parameter can take an array of computer names but you don’t want to process more than 5 for some reason. This is where [ValidateCount()] comes in to play.

This attribute takes two values, the minimum number of accepted parameter values and the maximum.

If used, this would mean I would need at least one computername but no more than 10. You could also set both values the same if you wanted an exact number:

Now, I’d have to pass exactly 2 numbers as parameter values. Let’s look at a more complete example.

This simple script writes each name in a random color, assuming I pass no more than 5 names.

If I exceed that count, PowerShell will throw a tantrum (I mean exception).

When you use this validation test, be sure your parameter is set to accept an array of values, e.g. [string[]]. If you’d like to try out my sample code feel free to download Demo-ValidateCount.

One of my favorite techniques when using WMI in PowerShell is to pipe an object to Select-Object and select all properties. Try this:

It works, but it also gets all of the system properties like __PATH which I rarely care about. I also get other properties like Site and Options which I typically don’t need. So here are some techniques you can use to view all WMI properties that probably matter most. Let’s begin with a typical command:

This object has a property called Properties which is a collection of WMI PropertyData objects. I could try something like:

Sure, I can see the properties and values but I don’t really have a good object to work with and this won’t help with multiple instances, at least not without a little extra work.

And maybe that’s all you need. If so, terrific. But I’m looking for an elegant solution. How about expanding the property names and saving them as an array of strings.

Then I can use them with Select-Object

That has promise. I could even turn this into a one-line command, assuming I’ve already defined $os.

If I didn’t want to take the extra step, here’s a complex alternative:

But this leads to yet another option, using the [WMIClass] type accelerator. When used, PowerShell creates an empty object of the specified WMI class which includes a property list.

This can be further simplified:

In fact, I can use this in an earlier expression to get the same non-System class results.

I’ll admit that’s a lot to type. So I need a shortcut. What about turning this into a scriptblock?

When I invoke the scriptblock, I’ll get the array of property names. I can now use this in my Get-WMIObject expression:

Definitely easier to type, but limited. I need the scriptblock to be more flexible so it can accommodate other WMI classes.

I’ll test it in the shell.

Excellent! Now for the real deal:

That’s exactly what I wanted with minimal effort. All I need is to have that scriptblock loaded in my PowerShell session and remember to specify the class name.

Another option would be to turn the scriptblock into a function, but I’ll leave that to you.

Naturally this isn’t perfect. If I need to query a remote computer with classes that aren’t on my computer, this won’t work; at least not without some revisions. But since I’d say 90% or more of WMI commands in PowerShell are with the Win32 classes, I think this is a handy trick to stick in your PowerShell toolbox.

If you’d like to try some of my code samples, you can download demo-wmiproperties.