How to Write Advanced PowerShell Scripts for Windows Server 2012 R2 Administration
PowerShell is the cornerstone of modern Windows Server administration. On Windows Server 2012 R2, PowerShell 4.0 ships by default, bringing with it Desired State Configuration, enhanced remoting, workflow capabilities, and a mature scripting ecosystem. For sysadmins managing dozens or hundreds of servers, mastering advanced PowerShell scripting techniques is not optional — it is essential. This guide walks through writing production-quality scripts that are robust, reusable, and safe to run in enterprise environments.
Prerequisites
Before proceeding, confirm your environment meets these requirements:
– Windows Server 2012 R2 with PowerShell 4.0 (verify with $PSVersionTable.PSVersion)
– Execution policy set appropriately: RemoteSigned or AllSigned for production
– Administrative credentials on target systems
– WinRM enabled for remoting scenarios
– Familiarity with basic PowerShell syntax, cmdlets, and the pipeline
Step 1: Script Structure and Best Practices
Every production-grade script should follow a consistent structure. Begin with a comment-based help block, declare parameters using the [CmdletBinding()] decorator, handle errors explicitly, and produce structured output. This makes scripts self-documenting and compatible with Get-Help.
#Requires -Version 4.0
#Requires -RunAsAdministrator
[CmdletBinding(SupportsShouldProcess = $true)]
param(
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[string[]]$ComputerName,
[Parameter(Mandatory = $false)]
[string]$OutputPath = "C:TempAdminAudit.csv"
)
BEGIN {
$results = [System.Collections.Generic.List[PSCustomObject]]::new()
Write-Verbose "Starting admin audit at $(Get-Date)"
}
PROCESS {
foreach ($computer in $ComputerName) {
try {
$admins = Invoke-Command -ComputerName $computer -ScriptBlock {
$group = [ADSI]"WinNT://$env:COMPUTERNAME/Administrators,group"
$group.Invoke("Members") | ForEach-Object {
$_.GetType().InvokeMember("Name", 'GetProperty', $null, $_, $null)
}
} -ErrorAction Stop
foreach ($admin in $admins) {
$results.Add([PSCustomObject]@{
ComputerName = $computer
AdminMember = $admin
Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
})
}
Write-Verbose "Processed $computer successfully"
}
catch {
Write-Warning "Failed to query $computer`: $($_.Exception.Message)"
$results.Add([PSCustomObject]@{
ComputerName = $computer
AdminMember = "ERROR: $($_.Exception.Message)"
Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
})
}
}
}
END {
if ($PSCmdlet.ShouldProcess($OutputPath, "Export CSV")) {
$results | Export-Csv -Path $OutputPath -NoTypeInformation -Encoding UTF8
Write-Output "Audit complete. Results saved to $OutputPath"
}
Write-Verbose "Total records: $($results.Count)"
}
Step 2: Advanced Error Handling and Logging
Production scripts require comprehensive error handling. Use $ErrorActionPreference, try/catch/finally blocks, and custom logging functions to capture all failure modes. The following logging function writes timestamped entries to both the console and a log file:
function Write-Log {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[string]$Message,
[ValidateSet('INFO','WARN','ERROR')]
[string]$Level = 'INFO',
[string]$LogFile = "C:Logsscript_$(Get-Date -Format yyyyMMdd).log"
)
$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
$logEntry = "[$timestamp] [$Level] $Message"
# Ensure log directory exists
$logDir = Split-Path $LogFile -Parent
if (-not (Test-Path $logDir)) {
New-Item -ItemType Directory -Path $logDir -Force | Out-Null
}
Add-Content -Path $LogFile -Value $logEntry
switch ($Level) {
'INFO' { Write-Host $logEntry -ForegroundColor Cyan }
'WARN' { Write-Host $logEntry -ForegroundColor Yellow }
'ERROR' { Write-Host $logEntry -ForegroundColor Red }
}
}
# Usage with error trapping
$ErrorActionPreference = 'Stop'
try {
Write-Log -Message "Starting service restart on $env:COMPUTERNAME"
Restart-Service -Name Spooler
Write-Log -Message "Spooler restarted successfully"
}
catch {
Write-Log -Message "Failed to restart Spooler: $($_.Exception.Message)" -Level ERROR
# Re-throw if the script should halt
throw
}
finally {
Write-Log -Message "Script block completed"
}
Step 3: Working with PowerShell Jobs and Runspaces
For parallelizing work across many servers, PowerShell jobs and runspaces provide significant performance gains. Background jobs are simpler but carry overhead; runspaces are faster for high-volume operations:
# Parallel disk space check using runspaces
$servers = Get-Content "C:Scriptsservers.txt"
$maxThreads = 20
$runspacePool = [RunspaceFactory]::CreateRunspacePool(1, $maxThreads)
$runspacePool.Open()
$jobs = [System.Collections.Generic.List[hashtable]]::new()
foreach ($server in $servers) {
$ps = [PowerShell]::Create().AddScript({
param($ComputerName)
try {
$disk = Get-WmiObject -Class Win32_LogicalDisk `
-ComputerName $ComputerName `
-Filter "DeviceID='C:'" -ErrorAction Stop
[PSCustomObject]@{
Server = $ComputerName
FreeGB = [math]::Round($disk.FreeSpace / 1GB, 2)
TotalGB = [math]::Round($disk.Size / 1GB, 2)
PctFree = [math]::Round(($disk.FreeSpace / $disk.Size) * 100, 1)
Status = 'OK'
}
}
catch {
[PSCustomObject]@{
Server = $ComputerName
FreeGB = 0
TotalGB = 0
PctFree = 0
Status = "Error: $($_.Exception.Message)"
}
}
}).AddArgument($server)
$ps.RunspacePool = $runspacePool
$jobs.Add(@{ PS = $ps; Handle = $ps.BeginInvoke() })
}
$results = foreach ($job in $jobs) {
$job.PS.EndInvoke($job.Handle)
$job.PS.Dispose()
}
$runspacePool.Close()
$results | Sort-Object PctFree | Format-Table -AutoSize
Step 4: Modules — Packaging Reusable Functions
Organize related functions into PowerShell modules so they can be imported across scripts and shared with team members. A module consists of a .psm1 file containing functions and a .psd1 manifest:
# Create module directory
$modulePath = "$env:ProgramFilesWindowsPowerShellModulesServerOps"
New-Item -ItemType Directory -Path $modulePath -Force
# ServerOps.psm1 - place in $modulePath
# Export only the public functions listed in the manifest
function Get-DiskHealth {
param([string[]]$ComputerName = $env:COMPUTERNAME)
foreach ($c in $ComputerName) {
Get-WmiObject -Class Win32_LogicalDisk -ComputerName $c |
Select-Object @{n='Server';e={$c}}, DeviceID,
@{n='FreeGB';e={[math]::Round($_.FreeSpace/1GB,2)}},
@{n='TotalGB';e={[math]::Round($_.Size/1GB,2)}}
}
}
function Test-ServerConnectivity {
param([string[]]$ComputerName)
$ComputerName | ForEach-Object {
[PSCustomObject]@{
Server = $_
Ping = (Test-Connection $_ -Count 1 -Quiet)
WinRM = (Test-WSMan $_ -ErrorAction SilentlyContinue) -ne $null
}
}
}
Export-ModuleMember -Function Get-DiskHealth, Test-ServerConnectivity
# Generate the module manifest
New-ModuleManifest -Path "$modulePathServerOps.psd1" `
-RootModule "ServerOps.psm1" `
-ModuleVersion "1.0.0" `
-Author "YourName" `
-Description "Server Operations Utility Functions" `
-FunctionsToExport @('Get-DiskHealth','Test-ServerConnectivity') `
-PowerShellVersion "4.0"
# Import and use
Import-Module ServerOps
Get-DiskHealth -ComputerName Server01,Server02
Step 5: Pipeline-Optimized Functions and OutputType
Well-written functions leverage the pipeline, declare their output types, and support -WhatIf. This enables chaining and testing without side effects:
[CmdletBinding(SupportsShouldProcess)]
[OutputType([PSCustomObject])]
function Set-ServiceStartupType {
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string]$ComputerName,
[Parameter(Mandatory)]
[string]$ServiceName,
[ValidateSet('Automatic','Manual','Disabled')]
[string]$StartupType
)
PROCESS {
if ($PSCmdlet.ShouldProcess("$ComputerName$ServiceName", "Set startup to $StartupType")) {
try {
$svc = Get-WmiObject Win32_Service -ComputerName $ComputerName `
-Filter "Name='$ServiceName'" -ErrorAction Stop
$result = $svc.ChangeStartMode($StartupType)
[PSCustomObject]@{
ComputerName = $ComputerName
Service = $ServiceName
NewStartType = $StartupType
ReturnCode = $result.ReturnValue
Success = ($result.ReturnValue -eq 0)
}
}
catch {
Write-Error "Failed on $ComputerName`: $_"
}
}
}
}
# Chain with pipeline
Import-Csv servers.csv | Set-ServiceStartupType -ServiceName "W32Time" -StartupType Automatic
Step 6: Script Signing for Production Deployment
Before deploying scripts across an enterprise, sign them with a code-signing certificate. This ensures integrity and satisfies AllSigned execution policies:
# Request a code-signing certificate from your internal CA
$cert = Get-ChildItem Cert:CurrentUserMy -CodeSigningCert | Select-Object -First 1
# Sign the script
Set-AuthenticodeSignature -FilePath "C:ScriptsInvoke-AdminAudit.ps1" -Certificate $cert
# Verify the signature
Get-AuthenticodeSignature -FilePath "C:ScriptsInvoke-AdminAudit.ps1" |
Select-Object Status, SignerCertificate
# Set execution policy for the machine
Set-ExecutionPolicy AllSigned -Scope LocalMachine -Force
Verification and Testing
Validate scripts using Pester, the PowerShell testing framework available from the PowerShell Gallery:
# Install Pester
Install-Module Pester -Force
# Example test file: ServerOps.Tests.ps1
Describe "Get-DiskHealth" {
It "Returns objects with required properties" {
$result = Get-DiskHealth -ComputerName localhost
$result | Should Not BeNullOrEmpty
$result[0].PSObject.Properties.Name | Should Contain 'FreeGB'
}
It "Handles unreachable servers gracefully" {
{ Get-DiskHealth -ComputerName "nonexistent.local" } | Should Throw
}
}
# Run tests
Invoke-Pester -Path "C:ScriptsServerOps.Tests.ps1" -Verbose
Summary
Advanced PowerShell scripting on Windows Server 2012 R2 requires discipline in structure, error handling, parallelism, and modularity. Using comment-based help, [CmdletBinding()], proper logging, runspace pools for parallelism, signed modules, and Pester tests transforms ad hoc scripts into enterprise-grade automation tools. These practices reduce risk, improve maintainability, and form the foundation for infrastructure-as-code approaches on the Windows platform.
