Summary: Ed Wilson, Microsoft Scripting Guy, talks about Windows PowerShell advanced functions.

 Hey, Scripting Guy! I keep hearing about advanced functions, but to be honest, I am not really sure what they are talking about. I mean, I can do a function, but when does it become advanced? Only when it is really long? Or when it does complicated stuff? I don’t know if I have ever written an advanced function, do you?

—BB

 Hello BB,

Microsoft Scripting Guy, Ed Wilson, is here. Awesome day! I just received my copy of Blain Barton’s new book, Microsoft Public Cloud Services: Setting up your business in the cloud.  I wrote a couple of sidebars for the book, so I was able to score a free copy. It looks really awesome, and the couple of chapters I read this morning should help eliminate some of the confusion surrounding “the cloud.” In fact, the Scripting Wife and I are heading to the book launch at the Microsoft Office in a few days. It should be awesome.

You ask why some functions are advanced and others are not. After all, they are basically the same, right? Well, they are written the same way, and the both use the Function keyword, but advanced functions take advantage of the internal workings of Windows PowerShell that make Windows PowerShell cmdlets so cool.

For example, when I create an advanced function, I gain access to common Windows PowerShell parameters and other stuff that makes the function work like a Windows PowerShell cmdlet. The secret? It is the use of the [cmdletbinding] tag.

But I don’t need to know all of that because there is a Windows PowerShell code snippet called Cmdlet (advanced function). That is the one I use on a normal basis. There is also a code snippet called Cmdlet (advanced function) – complete, which offers every option available to add to a Windows PowerShell cmdlet. If I want to take complete advantage of Windows PowerShell, that is the snippet I use.

How do I do it?

I open a blank script page in the Windows PowerShell ISE, and I select Start Snippets from the Edit menu. It opens a page that offers all of the available snippets. This is shown in the following image:

When I have the template for the function, I edit it as required. I add information, for example, for the comment-based Help, and I change my parameter information.

Note  The comment-based Help is outside the actual function in the templates, and that is pretty cool. This relies on a little known feature that if the comment-based Help has no lines (spaces) between the comment block and the function declaration, the comment block is interpreted as being associated with that function.

I normally move my comment-based Help section into the Function declaration. Because, to me, it makes the whole thing easier to move around as a unit.

Here is my really quick advanced function based on the script snippet template:

<#

.Synopsis

   Adds two numbers

.DESCRIPTION

   This function adds two numbers together and returns the sum

.EXAMPLE

   Add-TwoNumbers -a 2 -b 3

   Returns the number 5

.EXAMPLE

   Add-TwoNumbers 2 4

   Returns the number 6

#>

function Add-TwoNumbers

{

    [CmdletBinding()]

    [OutputType([int])]

    Param

    (

        # a is the first number

        [Parameter(Mandatory=$true,

                   ValueFromPipelineByPropertyName=$true,

                   Position=0)]

        [int]  

        $a,

        # b is the second number

        [Parameter(Mandatory=$true,

                   ValueFromPipelineByPropertyName=$true,

                   Position=1)]

        [int]

        $b

    )

    $a + $b

}

I copied the parameter declaration from the first parameter ($A) to the second parameter ($B) so that I would be able to pass two parameters to the function when I call it. This calling of the function is shown here:

BB, now you have a good understanding of advanced functions in Windows PowerShell. To Script or Not to Script Week will continue tomorrow when I will talk about Windows PowerShell modules.

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