Anatomy of a Powershell Advanced Function

This is the template I'm using for my Powershell 301: Anatomy of a Powershell Advanced Function class. In this online virtual class, I'll be discussing the Powershell Advanced Function feature line by line. Hopefully this will help instill good scripting techniques for scripters who are new to Advanced Functions or Powershell in general.

 

#Requires -Version 3
#Requires -Module ActiveDirectory
Function New-Cmdlet
{
<#
.SYNOPSIS
	This Cmdlet uses an approved verb from Get-Verb, comment-based help, #Requires
    statements, and it follows the format of an advanced Powershell function.
.DESCRIPTION
	This Cmdlet uses an approved verb from Get-Verb, comment-based help, #Requires
    statements, and it follows the format of an advanced Powershell function.
    This Cmdlet is designed only as a teaching tool to show good form for 
    writing Powershell v3 Cmdlets, also known as "Advanced Functions."
.PARAMETER ComputerName
    This describes the ComputerName parameter. If there are any defaults or extra
    attributes of the parameter as listed in the Param() block below, they will
    automatically be populated here. Notice that we use ComputerName here, and not
    ComputerNames or Hostname. That's because every other Cmdlet uses the parameter
    ComputerName with no S, even if we intend to supply multiple names, so we should
    stay consistent with that. Make it feel as much like an official Powershell
    Cmdlet as you can.
.EXAMPLE
    Get-Content C:\Hosts.txt | New-Cmdlet -Verbose

    This runs New-Cmdlet on each hostname in the Hosts.txt file.
.EXAMPLE
    "Server1","Server2","Server3" | New-Cmdlet

    This runs New-Cmdlet on Server1, Server2 and Server3.
.EXAMPLE
    New-Cmdlet -ComputerName Server1,Server2 -WhatIf -Verbose

    This tells what would happen if you ran New-Cmdlet on Server1 and Server2.
.INPUTS
    System.String[]

    This should be an array (a list) of one or more computer hostnames that you
    want to run this Cmdlet on. Pipeline input is accepted.
.OUTPUTS
    Nothing... yet!
.LINK
    If any relevant links, put 'em here.
.NOTES
    Notes. Author, date, whatever. You don't have to include every single one of 
    these event-based help categories, but it never hurts.
#>
	[CmdletBinding(SupportsShouldProcess=$True)]
	Param([Parameter(Mandatory=$True,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)][ValidateLength(3,30)][String[]]$ComputerName)

    BEGIN
    {
        # Run one-time set-up tasks here, like defining variables, etc.
        Set-StrictMode -Version Latest
        Write-Verbose -Message "Cmdlet is starting. You won't see this message unless you used -Verbose."
    }
    PROCESS
    {
        # The process block can be executed multiple times as objects are passed through the pipeline into it.
        ForEach($computer In $ComputerName)
        {
            If($PSCmdlet.ShouldProcess($computer))
            {
                Write-Verbose -Message "Beginning Process block on $computer"          
                $computer
            }        
        }
    }
    END
    {        
        # Finally, run one-time tear-down tasks here.
        Write-Verbose -Message "Running End block."
    }
}
Comments are closed