Checks disk space, shows extra space needed to meet target free %

Get-DiskSpaceWithFreeGoal.ps1

<# 
.SYNOPSIS
Retrieves disk space info from remote computers and computes the
extra free space needed to meet target free space percentages.

.DESCRIPTION
This function serves as a wrapper around the dbatools.io Get-DbaDiskSpace cmdlet,
extending its functionality with additional calculations.

It queries remote systems for disk space details, filters the output by specified 
drive letters, and calculates how much additional free space is required to reach 
specified target percentages when the current free space is below those targets.

The underlying Get-DbaDiskSpace cmdlet from dbatools.io handles the actual 
server connections and disk space data collection.

.PARAMETER ComputerName
Array of computer names or IP addresses to query.

.PARAMETER Credential
(Optional) PSCredential for remote connections.

.PARAMETER Drives
(Optional) Array of drive letters to check. Accepts 'C', 'C:', or 'C:\' format.
Default includes C:\, D:\, L:\, Q:\, T:\, and Z:\.

.PARAMETER TargetPercent1
(Optional) First target percentage for free space.
Default is 17.

.PARAMETER TargetPercent2
(Optional) Second target percentage for free space.
Default is 19.

.PARAMETER Unit
(Optional) Unit for the disk size and free space values.
Default is 'GB'.

.EXAMPLE
# For a set of test servers:
$paramHash = @{
    ComputerName   = $instances
    Credential     = $yourCred
    Drives         = 'D:', 'L', 'T'
    TargetPercent1 = 17
    TargetPercent2 = 25
    Unit           = 'GB'
}
Get-DiskSpaceWithFreeGoal @paramHash

.EXAMPLE
# For production and development servers with different target percentages:
$prodServersParams = @{
    ComputerName    = $prodInstances
    Credential      = $prodCred
    TargetPercent1  = 20  # Higher target for prod servers
    TargetPercent2  = 30
}

$devServersParams = @{
    ComputerName    = $devInstances
    Credential      = $devCred
    TargetPercent1  = 10  # Lower target for dev servers
    TargetPercent2  = 15
}

Get-DiskSpaceWithFreeGoal @prodServersParams
Get-DiskSpaceWithFreeGoal @devServersParams

.NOTES
Author: Claude, @nanoDBA, GPT
Date:   2025-04-19
Filename: Get-DiskSpaceWithFreeGoal.ps1
Prerequisites: dbatools PowerShell module (https://dbatools.io)
#>
function Get-DiskSpaceWithFreeGoal {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string[]]$ComputerName,
        
        [Parameter(Mandatory = $false)]
        [PSCredential]$Credential,
        
        [Parameter(Mandatory = $false)]
        [string[]]$Drives = @('C:\', 'D:\', 'L:\', 'Q:\', 'T:\', 'Z:\'),
        
        [Parameter(Mandatory = $false)]
        [double]$TargetPercent1 = 17,
        
        [Parameter(Mandatory = $false)]
        [double]$TargetPercent2 = 19,
        
        [Parameter(Mandatory = $false)]
        [string]$Unit = 'GB'
    )
    
    # Credential handling
    $credParams = @{}
    if ($Credential) {
        $credParams['Credential'] = $Credential
    }
    
    # Normalize drive formats to ensure consistency
    $normalizedDrives = $Drives | ForEach-Object {
        $drive = $_.Trim()
        if ($drive -match '^[a-zA-Z]$') {
            return "${drive}:\"
        } elseif ($drive -match '^[a-zA-Z]:$') {
            return "${drive}\"
        } else {
            return $drive
        }
    }
    
    # Get the raw disk data
    $rawData = Get-DbaDiskSpace -ComputerName $ComputerName @credParams -Unit $Unit | 
               Where-Object { $_.Name -in $normalizedDrives }
    
    # Create property names for target columns based on the parameters
    $target1Name = "To$($TargetPercent1)%$Unit"
    $target2Name = "To$($TargetPercent2)%$Unit"
    
    # Transform the data to include additional calculations
    $rawData | Select-Object ComputerName, Name, Label, SizeInGB,
        # Custom property for UsedInGB
        @{Name = 'UsedInGB'; Expression = { [math]::Round($_.SizeInGB - $_.FreeInGB, 2) }},
        @{Name = 'PercentUsed'; Expression = { [math]::Round(100 - $_.PercentFree, 2) }},
        # omitting BlockSize due to Format-Table limiting the default number of columns
        <#BlockSize,#>FreeInGB, PercentFree,
        @{
            Name = $target1Name
            Expression = {
                if ($_.PercentFree -lt $TargetPercent1) {
                    # Calculate needed space to reach TargetPercent1
                    $targetSpace = $_.SizeInGB * ($TargetPercent1/100)
                    $currentFree = $_.FreeInGB
                    $neededExtra = $targetSpace - $currentFree
                    
                    # Return rounded value
                    [math]::Round($neededExtra, 2)
                } else {
                    # Return empty if already above target
                    return [string]::Empty
                }
            }
        },
        @{
            Name = $target2Name
            Expression = {
                if ($_.PercentFree -lt $TargetPercent2) {
                    # Calculate needed space to reach TargetPercent2
                    $targetSpace = $_.SizeInGB * ($TargetPercent2/100)
                    $currentFree = $_.FreeInGB
                    $neededExtra = $targetSpace - $currentFree
                    
                    # Return rounded value
                    [math]::Round($neededExtra, 2)
                } else {
                    # Return empty if already above target
                    return [string]::Empty
                }
            }
        }
}