Functions and Modules

The Function Library That Saved My Team

I noticed our team was copying the same PowerShell code across dozens of scripts: logging functions, error handling, configuration loading. Every script had its own slightly different version, making maintenance a nightmare.

I spent a weekend creating a shared module with all our common functions:

Import-Module CompanyTools

Write-CompanyLog "Starting deployment"
$config = Get-CompanyConfig -Environment "Production"
Test-CompanyConnectivity -ServerList $config.Servers

One module, 200+ scripts now using it. A bug fix in the module fixed it everywhere. That's the power of functions and modules.

Functions

Functions are reusable code blocks.

Basic Function

function Get-ServerUptime {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    $uptime = (Get-Date) - $os.LastBootUpTime
    Write-Host "Server uptime: $($uptime.Days) days, $($uptime.Hours) hours"
}

# Call it
Get-ServerUptime

Functions with Parameters

function Test-ServerConnection {
    param(
        [string]$ServerName,
        [int]$Count = 1
    )
    
    Test-Connection -ComputerName $ServerName -Count $Count -Quiet
}

# Usage
Test-ServerConnection -ServerName "SERVER01"
Test-ServerConnection -ServerName "SERVER01" -Count 5

Return Values

function Get-DiskSpacePercent {
    param([string]$Drive = "C:")
    
    $disk = Get-PSDrive $Drive.TrimEnd(':')
    $percent = ($disk.Free / ($disk.Used + $disk.Free)) * 100
    return [math]::Round($percent, 2)
}

$freeSpace = Get-DiskSpacePercent -Drive "C:"
Write-Host "Free space: $freeSpace%"

Advanced Functions

Add cmdlet-like features with [CmdletBinding()].

CmdletBinding

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Message,
        
        [Parameter(Mandatory=$false)]
        [ValidateSet("INFO", "WARNING", "ERROR")]
        [string]$Level = "INFO"
    )
    
    Write-Verbose "Logging message with level: $Level"
    
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    "$timestamp [$Level] $Message" | Out-File -FilePath "app.log" -Append
}

# Now supports -Verbose, -Debug, etc.
Write-Log -Message "Operation started" -Verbose

Pipeline Input

function Get-FileSize {
    [CmdletBinding()]
    param(
        [Parameter(ValueFromPipeline=$true)]
        [System.IO.FileInfo]$File
    )
    
    process {
        [PSCustomObject]@{
            Name = $File.Name
            SizeMB = [math]::Round($File.Length / 1MB, 2)
        }
    }
}

# Usage
Get-ChildItem -File | Get-FileSize

Parameter Sets

function Get-ServiceInfo {
    [CmdletBinding(DefaultParameterSetName='Name')]
    param(
        [Parameter(ParameterSetName='Name', Position=0)]
        [string]$Name,
        
        [Parameter(ParameterSetName='Status')]
        [ValidateSet("Running", "Stopped")]
        [string]$Status
    )
    
    if ($PSCmdlet.ParameterSetName -eq 'Name') {
        Get-Service -Name $Name
    } else {
        Get-Service | Where-Object {$_.Status -eq $Status}
    }
}

# Usage
Get-ServiceInfo -Name "wuauserv"
Get-ServiceInfo -Status "Running"

Creating Modules

Modules package related functions.

Script Module (.psm1)

# Save as: ServerTools.psm1

function Test-ServerHealth {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$ComputerName
    )
    
    $result = [PSCustomObject]@{
        Server = $ComputerName
        Online = Test-Connection -ComputerName $ComputerName -Count 1 -Quiet
        DiskSpace = $null
        Services = $null
    }
    
    if ($result.Online) {
        $disk = Get-CimInstance -ComputerName $ComputerName -ClassName Win32_LogicalDisk -Filter "DeviceID='C:'"
        $result.DiskSpace = [math]::Round($disk.FreeSpace / 1GB, 2)
        
        $result.Services = (Get-Service -ComputerName $ComputerName | 
            Where-Object {$_.Status -eq 'Running'}).Count
    }
    
    return $result
}

function Get-ServerUptime {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$ComputerName
    )
    
    $os = Get-CimInstance -ComputerName $ComputerName -ClassName Win32_OperatingSystem
    (Get-Date) - $os.LastBootUpTime
}

# Export functions (what's available to users)
Export-ModuleMember -Function Test-ServerHealth, Get-ServerUptime

Using the Module

# Import module
Import-Module .\ServerTools.psm1

# Use functions
Test-ServerHealth -ComputerName "SERVER01"
Get-ServerUptime -ComputerName "SERVER01"

# Remove module
Remove-Module ServerTools

Module Manifest (.psd1)

# Create manifest
New-ModuleManifest -Path ServerTools.psd1 `
    -Author "Your Name" `
    -Description "Server management tools" `
    -ModuleVersion "1.0.0" `
    -RootModule "ServerTools.psm1" `
    -FunctionsToExport @('Test-ServerHealth', 'Get-ServerUptime')

Installing Modules

Module Paths

PowerShell looks for modules in these paths:

# View module paths
$env:PSModulePath -split ';'

# Common locations:
# C:\Users\<user>\Documents\PowerShell\Modules  (user)
# C:\Program Files\PowerShell\Modules           (all users)

Installing from PowerShell Gallery

# Find module
Find-Module -Name Az

# Install module
Install-Module -Name Az -Scope CurrentUser

# Update module
Update-Module -Name Az

# List installed modules
Get-InstalledModule

Real-World Module Example

# CompanyTools.psm1

function Write-CompanyLog {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Message,
        
        [ValidateSet("INFO", "WARNING", "ERROR")]
        [string]$Level = "INFO"
    )
    
    $logPath = "C:\Logs\company-$(Get-Date -Format 'yyyy-MM-dd').log"
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    "$timestamp [$env:USERNAME] [$Level] $Message" | 
        Out-File -FilePath $logPath -Append
}

function Get-CompanyConfig {
    [CmdletBinding()]
    param(
        [ValidateSet("Development", "Staging", "Production")]
        [string]$Environment = "Development"
    )
    
    $configPath = "C:\Config\$Environment-config.json"
    if (-not (Test-Path $configPath)) {
        throw "Configuration not found: $configPath"
    }
    
    Get-Content $configPath | ConvertFrom-Json
}

function Test-CompanyConnectivity {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string[]]$ServerList
    )
    
    $results = foreach ($server in $ServerList) {
        [PSCustomObject]@{
            Server = $server
            Online = Test-Connection -ComputerName $server -Count 1 -Quiet
            Timestamp = Get-Date
        }
    }
    
    return $results
}

Export-ModuleMember -Function Write-CompanyLog, Get-CompanyConfig, Test-CompanyConnectivity

Key Takeaways

• Functions encapsulate reusable code

• [CmdletBinding()] adds cmdlet features

• Modules (.psm1) package related functions

• Manifests (.psd1) describe modules

• PowerShell Gallery hosts public modules

• Export-ModuleMember controls visibility

What You've Learned

✅ Creating basic and advanced functions ✅ Using CmdletBinding for cmdlet-like features ✅ Building script modules (.psm1) ✅ Creating module manifests (.psd1) ✅ Installing modules from PowerShell Gallery ✅ Real-world module patterns

Next Steps

Now you can create reusable code. Let's scale up. In PowerShell Remoting and Automation, you'll learn:

• PowerShell remoting (WinRM, SSH)

• Managing multiple servers

• Background jobs

• Parallel execution

Manage hundreds of systems from one console.

---

Ready for remoting? Continue to PowerShell Remoting and Automation →