03 / RELIABLE ADMINISTRATION TOOLS · LESSON 09

Build a parameterised capacity check

Turn a one-off calculation into a reusable function with a validated policy parameter.

15 min · learn at your pace

Let callers supply the policy

A useful capacity function accepts observations and a threshold instead of reading one hardcoded file. Define Get-CapacityStatus -Disks -MinimumFreePercent using the calculation from the earlier capacity lesson. The caller decides where observations come from and what threshold is appropriate.

Use an integer percentage parameter with a default of 20 and [ValidateRange(0,100)]. Invalid supplied thresholds must fail before processing, even when the input collection is empty. Validation applies to arguments; choose a valid default deliberately.

function Show-Threshold {
    param([ValidateRange(0,100)][int]$MinimumFreePercent = 20)
    $MinimumFreePercent
}
Show-Threshold -MinimumFreePercent 25

Preserve the data contract

Return one object per disk with VolumeId, Computer, Mount, FreePercent, and State. Invalid capacity stays Unknown with a null percentage. A valid full disk is still a measurement, and the raw ratio determines whether it falls strictly below the supplied threshold.

Accept an empty array and emit no objects. If you make Disks mandatory, add [AllowEmptyCollection()] so the parameter binder permits that intentional empty input.

Keep status chatter off the success pipeline. Callers should receive only result objects; mixing in strings such as “Checking disks…” breaks downstream exports. The checks invoke your function on new observations, alternate thresholds, and empty input, so hardcoded findings will not work.

Go deeper

Read the official reference.

Try an example.ps1

[pscustomobject]@{ VolumeId='DEMO'; Computer='srv-demo'; Mount='C:'; TotalBytes=100; FreeBytes=25 }

YOUR TURN

Put it into practice.

Define Get-CapacityStatus -Disks <objects> -MinimumFreePercent <integer> (default 20; valid range 0–100). Return the same five-field capacity results as the earlier lesson. Accept empty input, classify invalid capacity as Unknown/null, use the raw ratio for the strict-below decision, and round only the output percentage. Throw for thresholds outside the range.

See an explained solution

One way to solve it.ps1

function Get-CapacityStatus {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Disks,
        [ValidateRange(0,100)][int]$MinimumFreePercent = 20
    )
    foreach ($disk in $Disks) {
        $total = [double]$disk.TotalBytes
        $free = [double]$disk.FreeBytes
        $percent = $null
        $state = 'Unknown'
        if ($total -gt 0 -and $free -ge 0 -and $free -le $total) {
            $ratio = 100 * $free / $total
            $state = if ($ratio -lt $MinimumFreePercent) { 'Low' } else { 'OK' }
            $percent = [math]::Round($ratio, 2)
        }
        [pscustomobject]@{ VolumeId=$disk.VolumeId; Computer=$disk.Computer; Mount=$disk.Mount; FreePercent=$percent; State=$state }
    }
}
Get-CapacityStatus -Disks @(Import-Csv '/home/user/disks.csv')

Parameter validation rejects invalid policy values before the body runs. The function keeps the original result contract while working with any supplied observations instead of one fixed import.