Search results for 'app:weblogs' matching tags 'functions' and 'scripting techniques'

I Found This Module—What Do I Do?

Anonymous — Wed, 15 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about how to use a Windows PowerShell module.

Hey, Scripting Guy! I found this module in the Scripting Guys Script Repository. Now what do I do?

—SH

Hello SH,

Microsoft Scripting Guy, Ed Wilson, is here. This morning I have been busy booking travel to Madrid, Spain for TechEd 2013. I will have a booth there with the Scripting Wife. In addition, I will be joining the Windows PowerShell team for their instructor led lab—it will be way cool. Air travel these days is so much fun, I genuinely look forward to each upcoming flight. This includes my flight to TechEd 2013 in New Orleans, where you can also find the Scripting Wife and me. (I am also conducting a Windows PowerShell instructor led lab in the big easy.)

Note This is the fourth part of a multipart series about using Windows PowerShell functions and modules. Prior to reading this blog, you should read the previous posts:

What do I do with a module I find?

Let us suppose that I find a module such as the Windows Update PowerShell Module in the Scripting Guys Script Repository. What do I do with it? Well, the first thing I need to do is to download and to install the module. But this is where things are actually a bit confusing. This is because I can put the module anywhere I want to put it. One of the great things about Windows PowerShell modules is that no installer is required. Most modules, in fact, use a simple copy and paste type of installation (the so-called XCOPY deployment, but you do not need to use XCOPY if you do not wish to do so).

Where do I put the module?

There are two places I can put modules so that Windows PowerShell will automatically recognize them, and will automatically import them. These locations are stored in the PSModulePath environmental variable. From a basic categorization standpoint, one is in my profile/home directory, and the other one is in System32. This output on my computer is shown here.

PS C:\> $env:PSModulePath -split ";"

C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules

C:\Windows\system32\WindowsPowerShell\v1.0\Modules\

It requires admin rights to copy something into the System32 folder, and that is where people sometimes place modules that require admin rights. The problem with this location is that when Windows undergoes servicing, it remotes items from the system folders that it does not know about. This means that your admin type of modules can easily become deleted the next time you run Windows update or apply a service pack.

The problem with storing all modules in my profile/home directory location occurs if I am running as a normal user, and then I need to elevate to an account with admin rights so I can run a module that requires admin rights. My profile/home directory is now a NEW location because I am running as a different user. This makes it painful to navigate back to the old user profile location to launch the module manually.

The answer is simple. Modify the $env:PSModulePath location to include an additional folder—either one on a network, or a folder in an easily accessible location. For example, I have a central data folder that I use to simplify backups (an XCOPY backup, so to speak). I could easily create a central modules folder that is accessible for all users on the computer. This technique is shown here.

PS C:\> $env:PSModulePath = $env:PSModulePath + ';c:\data\modules'

PS C:\> $env:PSModulePath -split ";"

C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules

C:\Windows\system32\WindowsPowerShell\v1.0\Modules\

c:\data\modules

How do I put the module in its location?

Let’s go back to the Windows Update PowerShell Module from the Scripting Guys Script Repository. It is contained in a file called PSWindowsUpdate.zip. I click the PSWindowsUpdate.zip file in the Script Repository, and after I agree to the terms of use, Internet Explorer asks if I want to Open, Save, or Cancel my action. This is shown in the image that follows.

If I select Open, the zipped file opens revealing a subfolder as shown here:

Cool, it seems that all I need to do is to open my module directory and drag the folder from the zipped folder to my module home directory. The problem if I do this is the files in the folder will all be blocked. This is shown in the following image.

I can use Windows PowerShell 3.0 to unblock the files, but it is easier to unblock the files before installation. To do this, save the .zip file, then right-click it to unblock the file prior to extraction. In this way, all the files contained therein are unblocked. However, if I forget to do this, I can use a command such as the following to unblock the files:

PS C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules> gci .\PSWindowsUpdate -Re

curse | Unblock-File

After I copy the unzipped and unblocked Windows PowerShell module files to the module directory, I can import the module and use the cmdlets. Because I am dealing with Windows update, the Windows PowerShell console needs to be elevated. The following error appears if the Windows PowerShell console is not elevated.

After I elevate Windows PowerShell, I use the Import-Module cmdlet to import the module, and I use the Get-Command cmdlet to see what commands are exposed by the module. This is shown here.

Now that I see the commands, I can use them just like any other Windows PowerShell command from any other module. So I can check to see what updates are available via the Get-WUList cmdlet (function) as shown here:

PS C:\> Get-WUList

ComputerName Status KB Size Title

------------ ------ -- ---- -----

EDLT ---H-- KB2694771 5 MB Bing Desktop v1.2

To install an update, I use the Get-WUInstall function, and to hide an update I use the Hide-WUUpdate command. Pipeline support is available.

I can even check to see if a reboot is required as shown here:

PS C:\> Get-WURebootStatus

Reboot is not Required.

SH, that is all there is to using a Windows PowerShell module. Join me tomorrow when I will reveal the 2013 Scripting Games Event 4.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

I Found this PowerShell Function—Now What Do I Do? Part 3

Anonymous — Tue, 14 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about combining functions into a single function file, and using them in scripts.

Microsoft Scripting Guy, Ed Wilson, is here. This morning is sort of mellow. It seems as if the clouds are touching the ground, and all sound is suppressed by a thick cloth batten. After seemingly weeks of rain, it is nice to have a not so wet day. I am on the lanai sitting in our porch swing reading my email via Outlook Web Access on my Surface RT. I love the long battery life and the portability of this device, and the fact that it has Windows PowerShell makes it even better.

Note This is the third part of a multipart series about using Windows PowerShell functions and modules. Prior to reading this blog, you should read the previous posts:

If one function is cool, then two are even better

Yesterday in Part 2, I talked about dot sourcing a script that contains a function into the Windows PowerShell console so I could use the function just like it was a cmdlet. Today I want to expand on that idea just a bit by including two functions in a script file. The two functions use WMI to create a similar output to standard CIM functions in Windows 8. The equilivant functions in Windows 8 are Get-Volume and Get-NetAdapter. Here is the content of the two WMI functions:

TwoWmiFunctions.ps1

Function Get-Volume

{

Param($cn = $env:computername)

Get-WmiObject -class win32_volume -ComputerName $cn|

Select-Object driveletter, @{LABEL='FileSystemLabel';EXPRESSION={$_.label}},

filesystem,

@{LABEL="Size";EXPRESSION={"{0:N2} Gigabytes" -f ($_.capacity/1GB) }},

@{LABEL="SizeRemaining";EXPRESSION={"{0:N2} Gigabytes" -f ($_.freespace/1GB) }}

} #end function Get-Volume

Function Get-NetAdapter

{

Param($cn = $env:computername)

Get-WmiObject win32_networkadapter |

Where-Object {$_.netconnectionstatus} |

Select-Object name,

@{LABEL='InterfaceDescription';EXPRESSION={$_.Description}},

@{LABEL='ifIndex';EXPRESSION={$_.Index}},

@{LABEL='Status';EXPRESSION={

If($_.netconnectionstatus -eq 2){"not present"}

If($_.netconnectionstatus -eq 4){"up"}}}

} # end function get-NetAdapter

For ease of use, I have uploaded these functions to the Scripting Guys Script Repository: Two WMI Functions.

Using the function script by dot sourcing it

To dot source the script that contains the two functions, all I need to do is to place a period (dot) at the beginning of the console line, and then use the path to the script that contains the functions. I can then use the functions directly. This is shown here.

. C:\fso\TwoWmiFunctions.ps1

The following image shows dot sourcing the script that contains the two functions and then using the two functions.

Dot source to interop between Windows versions

Lots of people are migrating to Windows 8 on their desktops; but unfortunately for many network administrators, they are forced to interop between Windows 8 and other versions of Windows. One of the things that is great about Windows 8 (and Windows Server 2012 for that matter) are the many CIM functions that wrap WMI classes. These are convenient and easy to use. However, for down-level systems, I still need to use the WMI classes. To avoid really cluttering up a script with a bunch of WMI code, I can use dot sourcing to handle the transition period. Here is an example of how that might work:

if(gcm get-volume){Get-Volume} ELSE {. C:\fso\TwoWmiFunctions.ps1; Get-Volume}

So all I need to do is to use Get-Command to see if the Get-Volume function (available in Windows 8) exists. If it does, I call the Get-Volume command. If the Get-Volume function is not available (because the version of Windows is older than Windows 8), I dot source my TwoWMIFunctions.ps1 script that contains my two functions, and then I call Get-Volume from the dot-sourced script. This makes for a nice transitional bit of code.

Note When you create this sort of transitional function, ensure that the property names are the same. In this way, using one function or the other will also be the same. In my example TwoWmiFunctions.ps1 script, I had to rename several WMI class property names for compatibility.

In the following image, I use the dot-source technique to bring in the script that contains the compatibility functions.

Now What Do I Do? Week will continue tomorrow when I will talk about using a Windows PowerShell module. It is really cool, and you do not want to miss it.

Ed Wilson, Microsoft Scripting Guy

I Found this PowerShell Function—Now What Do I Do? Part 2

Anonymous — Mon, 13 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, continues his discussion about what to do with a Windows PowerShell function.

Microsoft Scripting Guy, Ed Wilson, is here. Last week I did not get a chance to finish answering a question from JB about how to use a Windows PowerShell function.

Note This is the second part of a multipart series about using Windows PowerShell functions and modules. You should read the first blog post, I Found this PowerShell Function—Now What Do I Do? – Part 1 prior to reading this post.

Functions promote code reuse

In the first installment in this series about using functions, I talked about the more traditional technique of copying and pasting the function directly into a script. This works well if you want to write a script. But one of the powerful things about Windows PowerShell is that I do not have to write a script. In fact, the great thing about Andy Schneider’s Set-ScreenResolution function is that he wrote it as a function.

Top ten Windows PowerShell function best practices

Of course, being able to reuse the code depends on a well written function. Here is my top ten list of Windows PowerShell function best practices.

A function should:

Use the standard Verb-Noun naming convention.
Do one thing and do it well.
Return an object.
Incorporate comment-based Help.
Expose parameters instead of using hard-coded values.
Accept piped input if it makes sense for the use-case scenario.
Run and return default information if it makes sense for the use-case scenario (instead of requiring input, or returning an error when it is run without parameters).
Offer parameter aliases for common parameters (for example, CN for ComputerName).
Name parameters in accordance with standard Windows PowerShell cmdlets (for example ComputerName instead of server, laptop, or machine).
Use parameter validation techniques to limit user input.

Note For more information about Windows PowerShell functions, see this collection of Hey, Scripting Guy! Blog posts.

Save the function into a .ps1 script file

So suppose you find a well-written function and you want to be able to use it in the Windows PowerShell console. A well-written Windows PowerShell function will, in fact, act and behave like a Windows PowerShell cmdlet. So bringing it into the Windows PowerShell console will enhance the interactive use experience of Windows PowerShell.

Let’s go back to the Set-ScreenResolution function that I used last week (written by Andy Schneider). I go to the Scripting Guys Script Repository, find the Set-ScreenResolution script and copy it to the clipboard. Now, I paste it into the Windows PowerShell ISE, and I save it with a file name like Set-ScreenResolutionFunction.ps1. Here is the script:

Dot source the script file

When I have the function stored in a script file, I can use the function in my Windows PowerShell console, or even in another Windows PowerShell script. The key to doing this is to store the script file that contains the function in an easily locatable folder. For me, that folder is off the root of drive C (C:\fso). I have used this folder for my scratch folder for over a decade.

Keys to success for using dot sourcing

Save the function into a script file with a similar name to the function.
Save the script file that contains the function in an easily accessed location.
Make sure that the script file contains only the function, and no “entry code” that will automatically launch the function.
Dot source functions into scripts that may have code that changes for ease of update.
Use the syntax: period, space, path to script (<.><space><path>).

To dot source the Set-ScreenResolutionFunction.ps1 script into the Windows PowerShell console, I use the syntax shown here:

. C:\fso\Set-ScreenResolutionFunction.ps1

To call the Set-ScreenResolution function, I type the function name, just like I would do with a regular Windows PowerShell cmdlet. In fact, tab expansion even works. This is shown here:

Set-ScreenResolution -Width 800 -Height 600

This technique is shown in the image that follows.

I can also use this technique in the Windows PowerShell ISE. In the image that follows, I dot source the Set-ScreenResolutionFunction.ps1 script into my script.

Well, that is about all for now. Now What Do I Do? Week will continue tomorrow when I will continue to talk about using Windows PowerShell functions.

Ed Wilson, Microsoft Scripting Guy

Named Arguments for PowerShell Functions: Best Practices

Anonymous — Thu, 11 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about using named arguments in Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. If I go to the trouble of writing a Windows PowerShell script, I generally do not use unnamed arguments (such as $args as I illustrated yesterday in Accepting Arguments for PowerShell Functions: Best Practices). Instead I create named arguments for my functions. It is just so much more powerful, and so much more flexible. Besides, I can still pass values appositionally in an unnamed fashion if I wish to do so.

Create a named argument in five easy steps

In yesterday's blog, I said that there are only three requirements to create a function in Windows PowerShell:

The Function keyword
The name of the function
A script block

To create a named argument in a Windows PowerShell function, I need only two additional things:

The Param keyword
A variable to hold the argument inside a pair of parentheses

The following script illustrates this technique:

Function myfunction

{

Param($myargument)

"This value of `$myargument is $myargument"

}

To use MyFunction, I first have to run the script. This loads the function into memory and makes it available via the function PSDrive. Because I have not saved the script containing the function, when I run the script, it appears in the Console pane below the Script pane. When the script runs, the Windows PowerShell prompt returns, and I can call the function by typing the name of the function. I then supply a value for the argument by typing it. This is shown in the image that follows.

Keep in mind that tab expansion works here. So I do not have to type the entire name of MyFunction, nor do I need to type the complete name of MyArgument. In fact, I only had to type my and press the Tab key to get the MyFunction command onto the command line. When I type the hyphen (–) for the named argument (parameter) a pop-up list appears, as shown in the following image.

The advantage of using named arguments (parameters) is that I do not need to name the parameter if I do not want to. I can use it as a positional parameter. In this manner, it behaves like an unnamed argument ($args). This is shown here.

PS C:\> myfunction "this is a string"

This value of $myargument is this is a string

Because creating named parameters in Windows PowerShell is so easy, and because using the Param keyword is the entry into the world of advanced functions, I never use $args in a Windows PowerShell script. Because it is an automatic variable that becomes available in certain circumstances, using $args is more difficult to understand because nothing has been created in the script. It is just there.

On the other hand, because the Param block is declared and available for inspection, it makes sense, and is easier to understand. If I begin with a script that uses $args and I later decide that I need to add functionality, I will have to add a Param block to get access to advanced features.

Join me tomorrow when I will welcome guest bloggers Yuri Diogenes and Tom Shinder back with the second installment in their security series. If you want to refresh your memory, check out their first installment in the series:

Security Series: Using PowerShell to Protect Your Private Cloud Infrastructure

Ed Wilson, Microsoft Scripting Guy

Accepting Arguments for PowerShell Functions: Best Practices

Anonymous — Wed, 10 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about the best practices surrounding accepting input for a Windows PowerShell function.

Microsoft Scripting Guy, Ed Wilson, is here. April in the Carolina’s is a special time. In fact, it is my favorite time of the year here. This is because the weather is invariably mild. This week, it has been sunny, moderate temperature, mild humidity, and clear skies. The Scripting Neighbors tell me it is perfect golf weather. It is also perfect “sit on the lanai and write Windows PowerShell scripts” weather. Although I have never had much luck with putting a small ball into an even smaller hole with equipment not designed for that purpose, I can compute the trajectory, and force necessary to accomplish the task with a one-line Windows PowerShell command.

Passing a value to a Windows PowerShell function

If I have a function that I need to pass a value to, I can use the automatic variable $args. This makes the function easy to write and easy to use. The following function uses three steps to create the function. It calls the function keyword, provides a name, and creates a script block that contains code.

function myfunction

{

"the computer name is $args"

}

In the Windows PowerShell ISE, I run the script (I do not have to save the code into a .ps1 file), and the function loads into memory. I can then call the function directly in the execution pane (the dark blue box that follows) and pass a value to the function when I call it. The command line is shown here:

myfunction $env:COMPUTERNAME

The image that follows illustrates creating the function, using $args in the script block, and calling the function from the execution pane.

Anything I add following the name of the function populates the $args variable. In the command that follows, I pass the value mred to the function. Interestingly, I do not have to supply quotation marks when passing the value.

PS C:\> myfunction mred

the computer name is mred

PS C:\> myfunction "mred"

the computer name is mred

I can also use the output from the Get-WmiObject cmdlet for input. Therefore, the following code uses WMI to return the computer name and to pass it to the MyFunction function.

PS C:\> myfunction (gwmi win32_computersystem).name

the computer name is EDLT

One thing to keep in mind, is that when I use the $args automatic variable as illustrated in the MyFunction function, I cannot pipe input to the function. This can actually be a bit of a problem, because it could be really hard to troubleshoot due to the fact that no error arises. This is shown here.

PS C:\> $env:COMPUTERNAME | myfunction

the computer name is

If I want to pipel input to my function, I use the $input automatic variable. The only change that is required to my function is to change $args to $input, as shown here.

function afunction

{

"the computer name is $input"

}

I then pipe the input to the function by using the command shown here.

PS C:\> $env:COMPUTERNAME | afunction

If I attempt to provide positional input to the function instead of piping the input, no error arises, but no value passes either.

The command and associated output are shown in the image here.

Best Practices Week will continue tomorrow when I will talk some more about Windows PowerShell functions.

Ed Wilson, Microsoft Scripting Guy

Using PowerShell Functions: Best Practices

Anonymous — Tue, 09 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about some best practices for using Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. Windows PowerShell functions are really powerful, and at the same time, they are incredibly simple to create. This makes Windows PowerShell functions flexible and functional. But this flexibility also means that there is a lot of misunderstanding.

A simple function

At the low end (in terms of readability, functionality, features, and so on), a Windows PowerShell function is creatable on a single line interactively at the Windows PowerShell console. The minimum number of elements required to create a function are:

The Function keyword
The name of the function
A script block

That is it. This means that the following is a legitimate function:

function a {}

It does not do anything, but it is legitimate. Running the code at a command prompt in the Windows PowerShell console creates the function. I can then pipe output to it, and even verify that it exists on the Windows PowerShell function PS drive. The following script illustrates these concepts.

PS C:\> function a {}

PS C:\> gps | a

PS C:\> dir function:a

CommandType Name ModuleName

----------- ---- ----------

Function a

Adding functionality to the function

I often need to get a view of data, or a snapshot of data, before I return all of the data. Typically, I pipe the data to the Select-Object cmdlet and pick the last three entries in the data. The following script illustrates this technique (gps is an alias for the Get-Process cmdlet, and select is an alias for the Select-Object cmdlet).

PS C:\> gps | select -Last 3

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ -- -----------

207 9 1340 3064 40 1848 WUDFHost

405 19 3636 10012 95 1904 WUDFHost

214 18 3336 7852 89 2880 ZeroConfigService

I use this type of code when I am troubleshooting or simply perusing the status of a computer. Because I have established a pattern that pipes data to the Select-Object cmdlet and chooses the last three items, I can put this into a function that accepts pipelined input and outputs the last three items.

Because I am writing the function interactively in the Windows PowerShell console, and because I will be using it a lot, I give it a really short name. Here I call it “l” (as in lower case letter “L”). Inside the script block, I use the automatic variable $input, which is the input piped into a function.

The $input variable only exists inside the context of a function, and only for the time the function is called. If I check the value of $input outside of the function, it is empty. So what I pass to the function is then piped to the Select-Object cmdlet, and the last three items are returned from the function. The function is shown here.

function l {$input | select -Last 3}

To use the function, I pipe results to the function. The following script selects the last three processes.

PS C:\> gps | l

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ -- -----------

207 9 1340 3064 40 1848 WUDFHost

405 19 3636 10012 95 1904 WUDFHost

214 18 3336 7852 89 2880 ZeroConfigService

I can select the last three services (gsv is an alias) as shown here.

gsv | l

Or maybe I want to look at the last three entries in the event log as shown here.

Get-EventLog application | l

I can even use the range operator and select the last three numbers. This command is shown here.

1..10 | l

These commands and their associated output are shown in the following image.

Best Practices Week will continue tomorrow when I will continue talking about functions.

Ed Wilson, Microsoft Scripting Guy

Weekend Scripter: Easily Add Whatif Support to Your PowerShell Functions

Anonymous — Sun, 08 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, shows how to easily add whatif support to your Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. I love demoing Windows PowerShell to people who have never seen it—and believe it or not, there are still IT Pros who have not seen or used Windows PowerShell. Most people have heard of it by now (if they are in the business), but there is still a surprisingly large number of people who do not use Windows PowerShell. One of the features that generally gets ooohs and ahhhhs (and at times even applause) is the whatif parameter.

I generally tell people that they no longer have to run a command to see what it will do. Often I ask for a show of hands to see how many people have run a command and they did not know what it would do. Not surprisingly, the number of hands that goes up is large. Scarier, is when I ask who has run a command on a production system, and they were not certain what it would do. This is not a sign of carelessness, but rather a sign of desperation—the server is down, you go to TechNet, and it says to fix the problem, run this cryptic command. You do it and hope for the best. But what if there was a type-o on that page? With Windows PowerShell, this is no longer a concern because you can use whatif.

Adding support for the whatif parameter

One of the great features of Windows PowerShell is using the whatif parameter on cmdlets that change the system state, such as the Stop-Service or the Stop-Process cmdlets. In fact, by consistently utilizing the whatif switched parameter, it is possible to avoid many inadvertent system outages. As a Windows PowerShell best practice, you should also implement the whatif parameter in your advanced functions. In the past, this meant creating special parameters, and adding lots of extra code to handle the output. Now, it requires a single line of code.

Note [cmdletbinding()] appears with empty parentheses because there are other things, such as SupportsShouldProcess, that can appear between the parentheses.

The following function illustrates setting SupportsShouldProcess to True inside the parentheses of the cmdletbinding attribute.

function my-function

{

[cmdletbinding(SupportsShouldProcess=$True)]

Param($path)

md $path

}

Now when you call the function with the whatif switched parameter, a message appears in the output detailing the exact behavior the cmdlet takes when run without the whatif parameter. This is shown in the image that follows.

Ed Wilson, Microsoft Scripting Guy

Weekend Scripter: Cmdletbinding Attribute Simplifies PowerShell Functions

Anonymous — Sat, 07 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about using the cmdletbinding attribute to simplify Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. This morning I was sitting around playing with Windows PowerShell, and I realized that I had not written much about the cmdletbinding attribute. So here goes…

The first step in creating an advanced function is to add the cmdletbinding attribute. This single addition adds several capabilities such as additional parameter checking, and the ability to easily use the Write-Verbose cmdlet.

To use the cmdletbinding attribute, you place the attribute in a square bracket attribute tag and include it in the first non-commented line in the function. In addition, the cmdletbinding attribute requires the use of param keyword. If your advanced function requires no parameters, you can use the keyword without specifying any parameters. This technique is shown here:

function my-function

{

[cmdletbinding()]

Param()

}

When you have the basic outline of the advanced function, you can begin to fill in the blanks. For example, to use the Write-Verbose cmdlet only requires adding the following command.

function my-function

{

[cmdletbinding()]

Param()

Write-Verbose "verbose stream"

}

Easy verbose messages

When loaded, the function permits the use of the verbose switched parameter. Use of this parameter causes each Write-Verbose statement to write to the Windows PowerShell console output. When the function runs without the verbose switch, no output displays from the verbose stream.

The great thing about using Write-Verbose is that detailed information (such as the progress in making remote connections, loading modules, and other operations that could cause a script to fail) outputs as events happen. This provides a built-in diagnostic mode for the advanced function with virtually no additional programing.

Automatic parameter checks

The default behavior for a Windows PowerShell function is that additional values specified to an unnamed argument are available in the automatic $args variable. This behavior, although potentially useful, easily becomes a source of errors for a script. The following function illustrates this behavior.

function my-function

{

#[cmdletbinding()]

Param($a)

#$args

}

When this function runs, any value supplied to the –a parameter appears in the output as shown here:

PS C:\Users\ed.IAMMRED> my-function -a 1,2,3,4

On the other hand, when you call the function, if you omit the first comma, no error generates, but the output displayed does not meet expectations. This is shown here:

PS C:\Users\ed.IAMMRED> my-function -a 1 2,3,4

The remaining parameters appear in the automatic $args variable. Placing the $args variable in the function illustrates this. First, add the $args automatic variable as shown here:

function my-function

{

#[cmdletbinding()]

Param($a)

$args

}

Now, when calling the function, whilst omitting the first comma, the following output appears.

PS C:\Users\ed.IAMMRED> my-function -a 1 2,3,4

Although interesting, you may not want this behavior. One way to correct it is to check the number of arguments that are supplied to the function. You can do this by monitoring the count property of the $args variable as shown here:

function my-function

{

#[cmdletbinding()]

Param($a)

$args.count

}

When passing multiple arguments to the function, the value of the count property increases. In the output that is shown here, the first number 1, returns from the –a position. The number 3 is the count of extra arguments (that is, those not supplied for the named argument).

PS C:\Users\ed.IAMMRED> my-function 1 2 3 4

By using this feature, and checking the count property of $args, one line of code prevents extra arguments coming to the function. This change is shown here:

function my-function

{

#[cmdletbinding()]

Param($a,$b)

if($args.count -gt 0) {Write-Error "unhandled arguments supplied"}

}

When run, as shown in the following code, the first two parameters supplied are accepted for the –a and the –b parameters. The two remaining parameters go into the $args automatic variable. This increases the count property of $args to a value greater than 0, and therefore an error occurs.

PS C:\Users\ed.IAMMRED> my-function 1 2 3 4

my-function : unhandled arguments supplied

At line:1 char:12

+ my-function <<<< 1 2 3 4

+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException

+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,my-

function

The easiest way to identify unhandled parameters supplied to a Windows PowerShell function is to use the cmdletbinding attribute. One of the features of using the cmdletbinding attribute is that it generates an error when unhandled parameter values appear on the command line. The following function illustrates the cmdletbinding attribute.

function my-function

{

[cmdletbinding()]

Param($a,$b)

}

When calling the above function with too many arguments, the following error appears:

PS C:\Users\ed.IAMMRED> my-function 1 2 3 4

my-function : A positional parameter cannot be found that accepts argument '3'.

At line:1 char:12

+ my-function <<<< 1 2 3 4

+ CategoryInfo : InvalidArgument: (:) [my-function], ParameterBindingE

xception

+ FullyQualifiedErrorId : PositionalParameterNotFound,my-function

Ed Wilson, Microsoft Scripting Guy

PowerShell Pie for Pi Day

Anonymous — Wed, 14 Mar 2012 05:00:00 GMT

Summary: Use the built in pi value in an impromptu function to get the circumference of a circle by using Windows PowerShell.

Microsoft Scripting Guy, Ed Wilson, is here. The Scripting Wife and I are still pretty geeked out from the first ever Windows PowerShell Saturday that was held in Columbus Ohio. Add that today will be the third live meeting in the PowerShell Essentials for the Busy Admin series, and the week is pretty complete. But, as they say on late night television (at least in the United States), “Wait! There is more!” I completed writing all the events for the 2012 Scripting Games, and I emailed them off to the 20 guest commentators. I completed the 2012 Scripting Games quiz and got it sent off to the people who will turn it into an online quiz. And in just a few days, it will be International PowerShell User Group day! Now that ought to be enough to make any geek or geekette jump up and down with excitement.

How to get pi in PowerShell

I know I wrote a blog about not using the .NET Framework classes—but I was talking about unless you need to do so. Well, the easy way to get access to pi is to use the .NET Framework Math class. Pi is available as a static property, which means it is always available. I know that pi is equal to 3.14, or 22/7, but that is about it. Beyond the first few digits, it starts to get fuzzy for me. But I do not need to remember it because I can use the static pi property from the Math class. The following example illustrates using the pi property from the Math class to obtain a more precise value than simply 3.14.

PS C:\> [math]::pi

3.14159265358979

The key to using a static property from a .NET Framework class is remembering to use the double colon symbol (::). If you are wondering how I found this property, it is easy—I used the Get-Member cmdlet. This technique is shown here.

[math] | Get-Member –Static

The command and the associated output are shown here.

Suppose I need to calculate the circumference of a circle. In fact, I do this quite often in my woodworking shop. I cut out a circle for a tabletop, and I want to add an edge band to the circle so that it does not display open-pored end grain. Well, I need to know the circumference of the circle so I know how long of a piece of wood to cut. I could use paper and pencil, and perform this calculation:

Circumference = 2πr

Creating an impromptu function that uses pi

One of the cool things I can do in Windows PowerShell is creating an impromptu function. I do not need to open the Windows PowerShell ISE, type out a long convoluted script containing a function, then save it and dot source it into my Windows PowerShell console. Instead, I can create the function on the fly and use it throughout my session.

function get-circumference { Param($r)2*[math]::pi*$r }

Instead of using the Function keyword, I can also create the function directly on the function drive. To do this, I use the New-Item cmdlet. The code to do this is shown here.

New-Item -path function:get-circumference -Value {Param($r)2*[math]::pi*$r}

The code to create the Get-Circumference function directly on the function drive and the associated output are shown in the image that follows.

Well, that is about all there is to using pi to get the circumference of a circle. I need to get to work on prepping for today’s live meeting. See you then. Join me tomorrow when I will talk about more cool Windows PowerShell stuff.

Ed Wilson, Microsoft Scripting Guy

Use a PowerShell Function to Find Specific WMI Classes

Anonymous — Sat, 22 Oct 2011 05:00:00 GMT

Summary: Use a Windows PowerShell function to find WMI classes with specific qualifiers.

Microsoft Scripting Guy Ed Wilson here. In Thursday’s article, I talked about using the Set-WmiInstance cmdlet to work with WMI classes. One of the parameters, the class parameter, works with WMI singleton objects. Now, it is certainly possible to use WBEMTest to find singleton WMI classes. Such a WMI class is shown in the following figure in the WBEMTest utility.

But with 1,085 WMI classes in Root\Cimv2, it is faster and more fun to use a WMI schema query. WMI schema queries are mentioned on MSDN, but there are no Windows PowerShell examples. I decided I needed to write a Windows PowerShell function that would query the schema to find the singleton classes for which I was looking. In addition, there are other class qualifiers I was interested in seeing as well. For example, there is a supportsupdate qualifier that lets me know that I can use that class to make modifications to a computer. There are other qualifiers that are even more important: abstract and dynamic. As an IT pro, I want to query dynamic WMI classes, and not the abstracts. For ease of use, I uploaded the script to the Scripting Guys Script Repository.

I ended up writing a function I could use to find classes with specific qualifiers. As shown in the following figure, there are a few singleton WMI classes. I opened the function in the Windows PowerShell ISE, ran the script once to load the function into memory, and then I went to the command pane and typed the following command:

Get-WMIClassesWithQualifiers -qualifier singleton

The command and associated output are shown in the following figure.

A WMI schema query queries the meta_class WMI class. It uses the isa keyword to specify from which WMI class I want to return the schema information. That part is rather simple. The difficult part was getting the quotation marks placed in the right position to enable automatic querying. Here is the query line I derived:

$query = "select * from meta_class where __this isa ""$($class.name)"" "

I am interested in the qualifiers; therefore, I choose only the name of the WMI class and the qualifiers. This line appears is shown here:

$a = gwmi -Query $query -Namespace $namespace |

select -Property __class, qualifiers

If the qualifiers contain the qualifier I am looking for, I return the WMI class name:

if($a.qualifiers | % { $_ | ? { $_.name -match "$qualifier" }})

{ $a.__class }

The core portion of the script, with the aliases removed is shown here:

Param([string]$qualifier = "dynamic",

[string]$namespace = "root\cimv2")

$classes = Get-WmiObject -list -namespace $namespace

foreach($class in $classes)

{

$query = "Select * from meta_class where __this isa ""$($class.name)"" "

$a = Get-WmiObject -Query $query -Namespace $namespace |

Select-Object -Property __class, qualifiers

if($a.qualifiers | ForEach-Object { $_ | Where-Object { $_.name -match "$qualifier" }})

{ $a.__class }

} #end foreach $class

Well, that is about it for today. I hope you enjoy the function, and have an awesome weekend.

Ed Wilson, Microsoft Scripting Guy