Creating Your Own PowerShell Command

atomic powershellLast week, I posted a PowerShell function that you could use as an accelerator to create your own PowerShell tools. My tool takes command metadata from an existing PowerShell cmdlet and gives you the structure to create your own tool wrapped around what is in essence a proxy function.

The advantage, besides saving a lot of typing, is that by using a proxy function you can take advantage of the wrapped cmdlet’s features and parameters. But perhaps it would help to see an example. With the Get-CommandMetadata function loaded into the PowerShell ISE, I run this command:

Instead of using CDXML, or writing my own function to call Get-Cimstance, I’m going to create a proxy to Get-Ciminstance that designed to retrieve operating system information. Here’s what I start with.

As with any PowerShell scripting project, you have to think about who will run your command and what expectations they might have. In my example, I simply want to be able to specify a computer name or a CIM Session and retrieve information from the Win32_Operatingsystem class. So to begin with I can delete all the parameter definitions except Computername and CIMSession. I’ll also keep the OperationTimeOut parameter just in case. As you can see in the code sample, Get-CimInstance also has a number of parameter sets. Again, I can delete references to ones I’m not going to use.

Here’s my revised parameter definition.

One change I made was to give the computername a default value for the local computer. I amd doing this so that the PSComputername property will always have a value.

But you may be wondering, what about the classname? This is where the fun begins. I am going to hard-code other parameters into the function.

When the wrapped command is executed it will use these values which is what I want. At this point, I could save the function and run it. But the output would be the same as if I had run Get-Ciminstance and I have a specific output in mind. Here’s how.

First, copy and paste a new version of the $scriptCmd line. Comment out the original line.

What I need to do is create my own script command, which must be a single pipelined expression.

I still want the wrapped Get-Ciminstance command to run but then I’m going to pipe the results to Select-Object and specify some custom properties. That is the extent of my major changes, although I also will add some additional Write-Verbose lines for tracing and troubleshooting. After updating comment based help, here’s my final command.

Now to test it out:

I can specify a computername:

Or use CIMSessions.

osreport

I didn’t have to write any code to use the CIMSessions. I let the wrapped cmdlet handle everything for me. The end result is that I now have a very complete PowerShell tool that didn’t take much time to create. I probably spent more time getting the comment-based help written than anything.

Hopefully this gives you an idea of how to take your PowerShell toolmaking to the next level.

Using Optimized Text Files in PowerShell

documentIf you are like many IT Pros that I know, you often rely on text files in your PowerShell work. How many times have you used a text file of computernames with Get-Content and then piped to other PowerShell commands only to have errors. Text files are convenient, but often messy. Your text file might have blank lines. Your list of computernames might have a extra spaces after each name. These types of issues will break your PowerShell pipeline.

You can use Where-Object and filter out these types of problems. Or you can use a new function I wrote called Optimize-Text.

I’ve tried to add features to this command for what I think are common issues with text files. The core features are to remove any blank lines and trim leading and trailing spaces from each line of text. I’m working under the assumption that you will be using a command like Get-Content with some sort of list that you want to use with another cmdlet. You can insert Optimize-Text, in between.

For example, perhaps you want a quick and dirty ping test for a list of computers:

In this example, computers.txt is pretty mangled. There are blank lines and some names have leading and/or trailing spaces. Using Optimize-Text, fixes those issues. But wait…there’s more!

The advantage to using PowerShell is that everything is an object. Often, it helps to take advantage of pipeline binding. For example, the Computername parameter for Test-Connection accepts pipeline input by property name. So if the incoming object has a property that matches the parameter name, it will use it. Optimize-Text allows you to specify a property name. When you do, each line is turned into a custom object with a single property name.

This means I can run a command like:

And if you download this function today, I’ll throw in parameters to convert each line of text to upper case, to ignore lines with a specified comment character and to do additional filtering with a regular expression pattern!

By the way here’s what the text file looks like:

While it would be nice to think that all of the text files you use in PowerShell and neat and tidy, there’s no guarantee someone else might not come along and mess it up again. Hopefully, this function will help.

Please let me know how this works for you in the real world, or what other common problems you run into with text files. Be sure to look at full help and examples. Enjoy!

Friday Fun: Creating PowerShell Scripts with PowerShell

012914_1704_CreatingCIM1.png Sometimes PowerShell really does seem like magic. Especially when you can use it to handle complicated or tedious tasks, such as creating a PowerShell script. I know many an IT Pro who want to script but without having to actually write a script. Well, I’m not sure that is realistic, but you can get pretty close. Earlier this week I showed a set of commands built as proxy functions. I made an assumption that you find something like that useful. But perhaps it still seemed like a lot of work. So I built an accelerator tool for you I call Get-CommandMetadata.

The intent is that you can use this function to quickly create a PowerShell function based on a proxy command. My function includes parameters to give your command a new name and to strip out help references. I did this under the theory that you are building a new command on top of the underlying command and want to include your own help. If you run this function in the PowerShell ISE, it will paste your code into a new ISE tab.

So I can run this:

And end up with this:

All I need to do now is modify this to meet my needs and flesh out the help. By the way, the #requires statement uses whatever version you have on the system where you run the function. That’s about as easy as I can make it for right now but within a second I created 90 lines of PowerShell code with no typos!

As always I hope some of you will give this a try and let me know what you think. Enjoy your weekend.

Advice, solutions, tips and more for the lonely Windows administrator with too much to do and not enough time.

%d bloggers like this: