{"id":17832,"date":"2008-12-23T07:55:07","date_gmt":"2008-12-23T15:55:07","guid":{"rendered":"http:\/\/devblogs.microsoft.com\/powershell\/?p=17832"},"modified":"2019-06-07T07:56:30","modified_gmt":"2019-06-07T15:56:30","slug":"advanced-functions-and-test-leapyear-ps1","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/advanced-functions-and-test-leapyear-ps1\/","title":{"rendered":"Advanced Functions and Test-LeapYear.ps1"},"content":{"rendered":"

Welcome to CTP3!  There are just an amazing amount of really important features in V2 but the one I want everyone to start using ASAP is Advanced Functions.  In CTP2 we called this cmdlets.  We dropped that term in favor of taking the idea of a FUNCTION and just making it more and more capable.  It is a bit of a misnomer in that you can have an “Advanced function” by just adding a single line to your script.  You’ll be amazed what that single line gives you; but we’ll explore that later.  This entry recaps where we are with functions and then begins to give you a feel for some of the great benefits you have with advanced functions.  There is a LOT more to advanced functions than I’ll show you here.  You get an incredible amount for just a tiny amount of additional code. <\/P>\n

Going forward, I think that the community should\/will establish the norm that the functions you share with other people and blog about should be Advanced Functions.<\/P>\n

This post is a bit of mouthful but I encourage you to follow it and get on the Advanced Function bandwagon.  This is a gamechanger.  Alternatively, you can just start messing with them.  I’ve attached a ZIP file containing both Test-LeapYear.ps1 and a demo-test-leapyear.txt file that you can run using my Start-Demo script.<\/A>   Either way – invest and you will be rewarded!<\/P>\n

Jeffrey Snover [MSFT]
Windows Management Partner Architect
Visit the Windows PowerShell Team blog at:    http:\/\/blogs.msdn.com\/PowerShell<\/A>
Visit the Windows PowerShell ScriptCenter at:  http:\/\/www.microsoft.com\/technet\/scriptcenter\/hubs\/msh.mspx<\/A><\/P>\n

<\/FONT><\/FONT><\/FONT> <\/P>\n

[0]PS> #Functions can be simple<\/FONT>
<\/FONT>[1]PS> function Test-LeapYear {[DateTime]::IsLeapYear($args[0])} <\/FONT><\/P>\n

[2]PS> Test-LeapYear 2008
True <\/FONT><\/P>\n

<\/FONT><\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT><\/FONT> <\/P>\n

[3]PS> # But there are issues with simplicity
[4]PS> # The obvious one is that you have readability issues.
[5]PS> # What is $args[0] anyway?
[6]PS> # Also you have no type checking on the parameter.<\/FONT>
<\/FONT>[7]PS> Test-LeapYear ThisYear
Start-Demo : Cannot convert argument “0”, with value: “ThisYear”, for “IsLe
apYear” to type “System.Int32”: “Cannot convert value “ThisYear” to type “S
ystem.Int32″. Error: “Input string was not in a correct format.””
At line:1 char:11
+ start-demo <<<<  .\\demo-Test-LeapYear.ps1
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorE
   xception
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExce
   ption,Start-Demo <\/FONT><\/FONT><\/P>\n

<\/FONT><\/P>\n

[8]PS> # There is no checking on the # of arguments<\/FONT>
<\/FONT>[9]PS> Test-LeapYear 2008 2009 2010 2011
True <\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[10]PS> ##############################################
[11]PS> # In V1 you could remedy these issues with Named parameters:<\/FONT>
[12]PS> function Test-LeapYear {param([Int]$Year=[DateTime]::Now.Year)  [Dat
eTime]::IsLeapYear($Year)} <\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[13]PS> # Now you use variables whose names are self-documenting
[14]PS> # You get the same functions you got before<\/FONT>
[15]PS> Test-LeapYear 2008
True <\/FONT><\/P>\n

<\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[16]PS> # But now you also get NAMED parameters which makes it
[17]PS> # even more self-documenting<\/FONT>
[18]PS> Test-LeapYear -Year 2008
True <\/FONT><\/P>\n

<\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[19]PS> # You now have type checking on the parameter.<\/FONT>
[20]PS> Test-LeapYear ThisYear
Start-Demo : Cannot process argument transformation on parameter ‘Year’. Ca
nnot convert value “ThisYear” to type “System.Int32”. Error: “Input string
was not in a correct format.”
At line:1 char:11
+ start-demo <<<<  .\\demo-Test-LeapYear.ps1
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorE
   xception
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExce
   ption,Start-Demo <\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[21]PS> # But there is still no checking on the # of arguments<\/FONT>
[22]PS> Test-LeapYear 2008 2009 2010 2011
True <\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P>\n

[23]PS> # Of course you were on your own for help as well.
<\/FONT><\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

<\/FONT><\/FONT> <\/P>\n

 <\/P><\/FONT><\/FONT>\n

[24]PS> ##########################################
[25]PS> #
[26]PS> # But now you have Advanced Functions:
<\/FONT>[27]PS> Get-Content .\\Test-LeapYear.ps1
<#
.Synopsis
    Determines whether a year is a leapyear or not.
.Description
    This is a simple function to demonstrate the capabilities of PowerShell
    V2 Advanced Functions by telling whether a year is a leap year or not.
.Parameter Year
    Which year would you like tested?
.Example
    PS> Test-LeapYear 2008 <\/FONT><\/P>\n

.ReturnValue
    [Boolean] <\/FONT><\/P>\n

.Link
    about_functions
    about_functions_advanced
    about_functions_advanced_methods
    about_functions_advanced_parameters <\/FONT><\/P>\n

.Notes
NAME:      Verb-Noun
AUTHOR:    NTDEV\\jsnover
LASTEDIT:  12\/22\/2008 20:39:07
#Requires -Version 2.0
#> <\/FONT><\/P>\n

param(
[Parameter(Position=0, Mandatory=$true, ValueFromPipeline=$true)]
[Int]$Year
) <\/FONT><\/P>\n

Process
{
    [DateTime]::IsLeapYear($Year)
}#Process <\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT> <\/P>\n

<\/FONT> <\/P>\n

[28]PS> # You have all the stuff you had before but now look what you get:
<\/FONT>[29]PS> # It ensures that you send it the right number of parameters:
<\/FONT>[30]PS> .\\Test-LeapYear 2008 2009 2010 2011
Start-Demo : A positional parameter cannot be found that accepts argument ‘
2009′.
At line:1 char:11
+ start-demo <<<<  .\\demo-Test-LeapYear.ps1
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorE
   xception
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExce
   ption,Start-Demo<\/FONT> <\/FONT><\/P>\n

<\/FONT><\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[31]PS> # It supports pipelining<\/FONT>
<\/FONT>[32]PS> 2008,2009,2010,2011 | .\\Test-LeapYear
True
False
False
False<\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[33]PS> # I can’t demo it year but it also supports Tab-Completion of paramete
rnames
[34]PS> # Best of all, it supports HELP
<\/FONT>[35]PS> Get-Help .\\Test-LeapYear -full <\/FONT><\/P>\n

NAME
    C:\\temp\\Test-LeapYear.ps1 <\/FONT><\/P>\n

SYNOPSIS
    Determines whether a year is a leapyear or not. <\/FONT><\/P>\n

SYNTAX
    C:\\temp\\Test-LeapYear.ps1 [-Year] [<Int32>] [-Verbose] [-Debug] [-Error
    Action [<ActionPreference>]] [-WarningAction [<ActionPreference>]] [-Er
    rorVariable [<String>]] [-WarningVariable [<String>]] [-OutVariable [<S
    tring>]] [-OutBuffer [<Int32>]] [<CommonParameters>] <\/FONT><\/P>\n

DETAILED DESCRIPTION
    This is a simple function to demonstrate the capabilities of PowerShell
    V2 Advanced Functions by telling whether a year is a leap year or not. <\/FONT><\/P>\n

PARAMETERS
    -Year
        Which year would you like tested? <\/FONT><\/P>\n

        Required?                    true
        Position?                    0
        Default value
        Accept pipeline input?       true (ByValue)
        Accept wildcard characters? <\/FONT><\/P>\n

    <CommonParameters>
        This cmdlet supports the common parameters: -Verbose, -Debug,
        -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
        -OutBuffer and -OutVariable. For more information, type,
        “get-help about_commonparameters”. <\/FONT><\/P>\n

INPUT TYPE <\/FONT><\/P>\n

RETURN TYPE
    [Boolean] <\/FONT><\/P>\n

NOTES <\/FONT><\/P>\n

        NAME:      Verb-Noun
        AUTHOR:    NTDEV\\jsnover
        LASTEDIT:  12\/22\/2008 20:39:07
        #Requires -Version 2.0 <\/FONT><\/P>\n

    ————————– EXAMPLE 1 ————————– <\/FONT><\/P>\n

    PS> Test-LeapYear 2008 <\/FONT><\/P>\n

RELATED LINKS
    about_functions
    about_functions_advanced
    about_functions_advanced_methods
    about_functions_advanced_parameters <\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[36]PS> # Notice that while we only declared one parameter,
[37]PS> # it actually has 9!
[38]PS> # These are provided by the PowerShell engine.
<\/FONT>[39]PS> (Get-Command .\\Test-LeapYear.ps1).Parameters <\/FONT><\/P>\n

Key                                   Value
—                                   —–
Year                                  System.Management.Automation.Param…
Verbose                               System.Management.Automation.Param…
Debug                                 System.Management.Automation.Param…
ErrorAction                           System.Management.Automation.Param…
WarningAction                         System.Management.Automation.Param…
ErrorVariable                         System.Management.Automation.Param…
WarningVariable                       System.Management.Automation.Param…
OutVariable                           System.Management.Automation.Param…
OutBuffer                             System.Management.Automation.Param… <\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/P>\n

<\/FONT><\/FONT> <\/P>\n

[40]PS> # Let’s see them in action
<\/FONT>[41]PS> 2008,2009,2010 |.\\Test-LeapYear.ps1 -OutVariable Results
True
False
False <\/FONT><\/P>\n

[42]PS> $results
True
False
False <\/FONT><\/P>\n

<\/FONT> <\/P>\n

<\/FONT> <\/P>\n

[43]PS> 2008,”Burp”,2010 |.\\Test-LeapYear.ps1 -ErrorAction Stop
True
Start-Demo : Command execution stopped because the preference variable “Err
orActionPreference” or common parameter is set to Stop: The input object ca
nnot be bound to any parameters for the command either because the command
does not take pipeline input or the input and its properties do not match a
ny of the parameters that take pipeline input.
At line:1 char:11
+ start-demo <<<<  .\\demo-Test-LeapYear.ps1
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorE
   xception
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorExce
   ption,Start-Demo <\/FONT><\/FONT><\/P>\n

[44]PS> 2008,”Burp”,2010 |.\\Test-LeapYear.ps1 -ErrorAction SilentlyContinue <\/FONT><\/P>\n

True 
 False<\/FONT><\/P><\/p>\n

Test-LeapYear.zip<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

Welcome to CTP3!  There are just an amazing amount of really important features in V2 but the one I want everyone to start using ASAP is Advanced Functions.  In CTP2 we called this cmdlets.  We dropped that term in favor of taking the idea of a FUNCTION and just making it more and more capable.  […]<\/p>\n","protected":false},"author":600,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[97,137,328],"class_list":["post-17832","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-advanced-functions","tag-ctp3","tag-test-leapyear"],"acf":[],"blog_post_summary":"

Welcome to CTP3!  There are just an amazing amount of really important features in V2 but the one I want everyone to start using ASAP is Advanced Functions.  In CTP2 we called this cmdlets.  We dropped that term in favor of taking the idea of a FUNCTION and just making it more and more capable.  […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17832","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/600"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=17832"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17832\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=17832"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=17832"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=17832"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}