Writing PowerShell Advanced Functions

What Is an Advanced Function?

An advanced function is a PowerShell function written entirely in script that behaves like a compiled cmdlet. It accepts the common parameters every built-in cmdlet has, such as -Verbose, -ErrorAction, and -WhatIf, and PowerShell binds its parameters using the same strict rules used for compiled cmdlets, including rejecting unknown parameters.

Think of an advanced function as a homemade cmdlet. From the outside, whoever calls Get-Something cannot tell whether it is C# code shipped in a compiled module or a PowerShell script function, because CmdletBinding makes both participate in the same contract: predictable parameter binding, pipeline support, and self-documenting help.

A function becomes advanced once it has either the CmdletBinding attribute or a Parameter attribute on at least one of its parameters, or both. In practice almost every advanced function uses CmdletBinding, and most parameters also carry a Parameter attribute so they can declare things like Mandatory or ValueFromPipeline.

Why Write One Instead of a Basic Function?

A basic function with a bare param() block works fine for a one-off script run interactively. It stops being enough the moment the function is going to be reused, called from another script, or run unattended against more than one target.

None of this is decoration. A function that silently accepts $null, an empty string, or a mistyped computer name will fail somewhere downstream where the error message no longer points back to the actual mistake. Validation attributes move that failure to the one place where it is cheap to diagnose: the moment the parameter is bound.

Why Production Code Cares About This

Scripts that are only ever run once by the person who wrote them can get away with sloppy parameter handling. Scripts that get reused by other admins, scheduled as jobs, or called from other functions cannot.

SupportsShouldProcess is the clearest example. Any function that deletes files, restarts a service, or disables an account should support -WhatIf so it can be tested without making the change, and -Confirm so a destructive action prompts before it runs. Without it, the only way to know what a script will do is to read the code or run it for real.

Correct begin/process/end use is the other half of reliability. A function that accepts pipeline input but has no process block will silently run once instead of once per object, which is one of the most common bugs in hand-written PowerShell tools. Getting the block structure right the first time means the function keeps working correctly whether it is called with one computer name or piped a CSV of five hundred.

Anatomy of an Advanced Function

The example below deletes log files older than a given number of days. It touches the filesystem, so it is a good candidate to walk through CmdletBinding, parameter validation, and begin/process/end together.

function Remove-OldLogFile {
    <#
    .SYNOPSIS
        Deletes log files older than a specified number of days.
    .DESCRIPTION
        Removes files matching a given extension from one or more folders
        when their LastWriteTime is older than the specified threshold.
        Supports -WhatIf and -Confirm because it deletes data.
    .PARAMETER Path
        One or more folder paths to clean up. Accepts pipeline input.
    .PARAMETER OlderThanDays
        Minimum age, in days, before a file is eligible for deletion.
    .PARAMETER Extension
        The file extension to target, without the dot. Defaults to 'log'.
    .EXAMPLE
        PS> Remove-OldLogFile -Path C:\Logs\IIS -OlderThanDays 30
    .EXAMPLE
        PS> 'C:\Logs\App', 'C:\Logs\Web' | Remove-OldLogFile -OlderThanDays 90 -WhatIf
    #>
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
    param (
        [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)]
        [ValidateScript({ Test-Path -LiteralPath $_ -PathType Container })]
        [string[]]$Path,

        [Parameter()]
        [ValidateRange(1, 3650)]
        [int]$OlderThanDays = 30,

        [Parameter()]
        [ValidatePattern('^[A-Za-z0-9]{1,10}$')]
        [string]$Extension = 'log'
    )

    begin {
        Write-Verbose "Deleting .$Extension files older than $OlderThanDays day(s)"
        $cutoff = (Get-Date).AddDays(-$OlderThanDays)
        $removedCount = 0
    }

    process {
        foreach ($folder in $Path) {
            $files = Get-ChildItem -LiteralPath $folder -Filter "*.$Extension" -File -ErrorAction Stop |
                Where-Object { $_.LastWriteTime -lt $cutoff }

            foreach ($file in $files) {
                if ($PSCmdlet.ShouldProcess($file.FullName, 'Remove log file')) {
                    Remove-Item -LiteralPath $file.FullName -Force -ErrorAction Stop
                    $removedCount++
                }
            }
        }
    }

    end {
        Write-Verbose "Removed $removedCount file(s) older than $cutoff"
    }
}

Pipeline Input and Validation in Practice

ValueFromPipeline and ValueFromPipelineByPropertyName solve two different problems, and mixing them up is one of the most common reasons pipeline input silently fails to bind.

# ValueFromPipeline accepts the whole piped object, so bare strings bind directly
function Get-DiskUsageReport {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, ValueFromPipeline)]
        [string[]]$ComputerName
    )

    process {
        foreach ($computer in $ComputerName) {
            Write-Output "Checking disk usage on $computer"
        }
    }
}

# Works: bare strings bind to $ComputerName because the type matches
'SRV01', 'SRV02' | Get-DiskUsageReport

# ValueFromPipelineByPropertyName only binds when the piped object has a
# property with the exact same name as the parameter (or one of its aliases)
function Get-DiskUsageReportByProperty {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [Alias('CN')]
        [string[]]$ComputerName
    )

    process {
        foreach ($computer in $ComputerName) {
            Write-Output "Checking disk usage on $computer"
        }
    }
}

# servers.csv has a header row: ComputerName
# Works: Import-Csv produces objects with a ComputerName property
Import-Csv .\servers.csv | Get-DiskUsageReportByProperty

Validation attributes are just as easy to get wrong in the other direction: reaching for ValidateScript when a simpler, built-in attribute already covers the case. The table below lists the ones used most often.

Validation Attributes Cheat Sheet

Troubleshooting Cheat Sheet

Final Thoughts

None of this turns a script into something more complicated than it needs to be. A ten-line function with CmdletBinding, one or two validation attributes, and a correct process block is still a short script. What changes is where it fails: at the parameter, with a clear message, instead of three loops deep with a stack trace that no longer points at the real mistake.

That difference is what separates a function you use once and throw away from one that ends up in a shared module other people rely on. Once a function accepts pipeline input, supports -WhatIf, and validates its own parameters, it behaves exactly like the built-in cmdlets it sits next to.