PowerShell Scripting Basics

My First Production Script

I'll never forget my first "real" PowerShell script. Our team was manually provisioning user accounts - a 30-minute process per user involving Active Directory, Exchange, file share permissions, and group memberships. With 50 new hires starting next month, we were looking at 25 hours of repetitive work.

I spent an evening writing a PowerShell script:

.\New-UserAccount.ps1 -FirstName "John" -LastName "Doe" -Department "IT"

What took 30 minutes manually now took 90 seconds. More importantly, it was consistent - no missed steps, no typos in group names, no forgotten permissions. That script ran for 3 years, creating over 500 user accounts without a single error.

That's when I learned the difference between typing commands interactively and writing reusable scripts.

Creating PowerShell Scripts

Script Files (.ps1)

PowerShell scripts are text files with .ps1 extension:

# Save as: Get-SystemInfo.ps1
$computerName = $env:COMPUTERNAME
$osInfo = Get-CimInstance -ClassName Win32_OperatingSystem

Write-Host "Computer: $computerName"
Write-Host "OS: $($osInfo.Caption)"
Write-Host "Version: $($osInfo.Version)"

Running Scripts

# From current directory
.\Get-SystemInfo.ps1

# With full path
C:\Scripts\Get-SystemInfo.ps1

# From different directory (if in $env:PATH)
Get-SystemInfo.ps1

Dot Sourcing

Dot sourcing loads script content into current session:

# Run in new scope (variables not accessible after)
.\MyScript.ps1

# Dot source (variables accessible after)
. .\MyScript.ps1

Execution Policies

Windows PowerShell has execution policies to prevent accidental script execution.

Checking Execution Policy

Get-ExecutionPolicy

# Check all scopes
Get-ExecutionPolicy -List

Policy Levels

• Restricted: No scripts allowed (default on Windows client)

• AllSigned: Only signed scripts

• RemoteSigned: Local scripts ok, downloaded must be signed (recommended)

• Unrestricted: All scripts allowed (requires confirmation)

• Bypass: Nothing is blocked, no warnings

Setting Execution Policy

# For current user (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# For local machine (requires admin)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

# Bypass for single script
powershell.exe -ExecutionPolicy Bypass -File .\script.ps1

Note: Execution policies are not security features. They prevent accidental execution but can be easily bypassed by determined users.

Script Parameters

Parameters make scripts reusable.

Basic Parameters

# Save as: Greet-User.ps1
param(
    $Name
)

Write-Host "Hello, $Name!"

Usage:

.\Greet-User.ps1 -Name "John"

Typed Parameters

param(
    [string]$Name,
    [int]$Age,
    [bool]$IsActive
)

Write-Host "$Name is $Age years old"

Multiple Parameters

param(
    [string]$ServerName,
    [int]$Port = 8080,  # Default value
    [string]$Protocol = "HTTP"
)

Write-Host "Connecting to ${Protocol}://${ServerName}:${Port}"

Usage:

.\Connect-Server.ps1 -ServerName "WEB01"  # Uses defaults for Port and Protocol
.\Connect-Server.ps1 -ServerName "WEB01" -Port 443 -Protocol "HTTPS"

Mandatory Parameters

param(
    [Parameter(Mandatory=$true)]
    [string]$ComputerName,
    
    [Parameter(Mandatory=$false)]
    [int]$Timeout = 30
)

If mandatory parameter is missing, PowerShell prompts for it.

Parameter Validation

ValidateSet

Restrict to specific values:

param(
    [Parameter(Mandatory=$true)]
    [ValidateSet("Development", "Staging", "Production")]
    [string]$Environment
)

Write-Host "Deploying to $Environment"

ValidateRange

Numeric ranges:

param(
    [ValidateRange(1, 100)]
    [int]$Percentage
)

ValidatePattern

Regex validation:

param(
    [ValidatePattern('^\d{3}-\d{2}-\d{4}$')]
    [string]$SSN
)

ValidateLength

String length:

param(
    [ValidateLength(8, 20)]
    [string]$Password
)

ValidateScript

Custom validation:

param(
    [ValidateScript({Test-Path $_ -PathType 'Container'})]
    [string]$FolderPath
)

Real-World Example

param(
    [Parameter(Mandatory=$true, HelpMessage="Enter server name")]
    [ValidateNotNullOrEmpty()]
    [string]$ServerName,
    
    [Parameter(Mandatory=$true)]
    [ValidateSet("Web", "Database", "Application")]
    [string]$ServerType,
    
    [Parameter(Mandatory=$false)]
    [ValidateRange(1, 99)]
    [int]$InstanceNumber = 1,
    
    [Parameter(Mandatory=$false)]
    [ValidateSet("Development", "Staging", "Production")]
    [string]$Environment = "Development"
)

$fullServerName = "$ServerType$($InstanceNumber.ToString('00'))-$Environment"
Write-Host "Creating server: $fullServerName"

Comment-Based Help

Make your scripts self-documenting:

<#
.SYNOPSIS
    Creates a new user account with standard permissions.

.DESCRIPTION
    This script automates user account creation including Active Directory, 
    email, and file share permissions. It ensures consistent configuration 
    across all new users.

.PARAMETER FirstName
    User's first name

.PARAMETER LastName
    User's last name

.PARAMETER Department
    Department name (IT, HR, Finance, Sales)

.EXAMPLE
    .\New-UserAccount.ps1 -FirstName "John" -LastName "Doe" -Department "IT"
    Creates a new user account for John Doe in the IT department.

.EXAMPLE
    .\New-UserAccount.ps1 -FirstName "Jane" -LastName "Smith" -Department "HR" -Verbose
    Creates a new user with verbose output.

.NOTES
    Author: Your Name
    Last Modified: 2024-01-15
    Version: 1.2
    
.LINK
    https://docs.company.com/user-provisioning
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$FirstName,
    
    [Parameter(Mandatory=$true)]
    [string]$LastName,
    
    [Parameter(Mandatory=$true)]
    [ValidateSet("IT", "HR", "Finance", "Sales")]
    [string]$Department
)

# Script content here

View help:

Get-Help .\New-UserAccount.ps1
Get-Help .\New-UserAccount.ps1 -Examples
Get-Help .\New-UserAccount.ps1 -Detailed

Script Structure Best Practices

Organized Script Template

<#
.SYNOPSIS
    Brief description
.DESCRIPTION
    Detailed description
.PARAMETER Name
    Parameter description
.EXAMPLE
    Example usage
#>

#Requires -Version 7.0
#Requires -Modules Az.Compute

[CmdletBinding()]
param(
    [Parameter(Mandatory=$true)]
    [string]$ResourceName
)

#region Variables
$logPath = "C:\Logs\script.log"
$maxRetries = 3
#endregion

#region Functions
function Write-Log {
    param([string]$Message)
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    "$timestamp - $Message" | Out-File -FilePath $logPath -Append
    Write-Verbose $Message
}
#endregion

#region Main Script
try {
    Write-Log "Script started"
    
    # Main logic here
    
    Write-Log "Script completed successfully"
}
catch {
    Write-Log "Error: $_"
    throw
}
#endregion

Using #Requires

Ensure prerequisites:

#Requires -Version 7.0
#Requires -Modules Az.Compute, Az.Storage
#Requires -RunAsAdministrator

Real-World Script Example

<#
.SYNOPSIS
    Performs health check on remote servers.

.DESCRIPTION
    Checks server connectivity, disk space, services, and CPU/memory usage.
    Generates detailed report in CSV format.

.PARAMETER ServerList
    Path to file containing server names (one per line)

.PARAMETER OutputPath
    Path for output CSV report

.EXAMPLE
    .\Invoke-HealthCheck.ps1 -ServerList "servers.txt" -OutputPath "health-report.csv"
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory=$true)]
    [ValidateScript({Test-Path $_})]
    [string]$ServerList,
    
    [Parameter(Mandatory=$false)]
    [string]$OutputPath = ".\health-check-$(Get-Date -Format 'yyyy-MM-dd').csv"
)

# Read server list
$servers = Get-Content -Path $ServerList

# Initialize results array
$results = @()

foreach ($server in $servers) {
    Write-Verbose "Checking $server..."
    
    # Test connectivity
    $pingResult = Test-Connection -ComputerName $server -Count 1 -Quiet
    
    $serverInfo = [PSCustomObject]@{
        ServerName = $server
        Online = $pingResult
        DiskSpaceCritical = $false
        ServicesDown = 0
        LastCheck = Get-Date
    }
    
    if ($pingResult) {
        try {
            # Check disk space
            $disk = Get-CimInstance -ComputerName $server -ClassName Win32_LogicalDisk -Filter "DeviceID='C:'" -ErrorAction Stop
            $freePercent = ($disk.FreeSpace / $disk.Size) * 100
            $serverInfo.DiskSpaceCritical = $freePercent -lt 10
            
            # Check critical services
            $criticalServices = @('wuauserv', 'W32Time', 'EventLog')
            $stoppedServices = Invoke-Command -ComputerName $server -ScriptBlock {
                param($services)
                Get-Service -Name $services | Where-Object {$_.Status -ne 'Running'}
            } -ArgumentList (,$criticalServices) -ErrorAction Stop
            
            $serverInfo.ServicesDown = $stoppedServices.Count
        }
        catch {
            Write-Warning "Error checking $server: $_"
        }
    }
    
    $results += $serverInfo
}

# Export results
$results | Export-Csv -Path $OutputPath -NoTypeInformation
Write-Host "Report saved to: $OutputPath"

# Display summary
Write-Host "`nSummary:"
Write-Host "Total servers: $($results.Count)"
Write-Host "Online: $(($results | Where-Object Online).Count)"
Write-Host "Offline: $(($results | Where-Object {-not $_.Online}).Count)"
Write-Host "Disk space critical: $(($results | Where-Object DiskSpaceCritical).Count)"

Common Pitfalls

1. Not Using Parameters

Problem: Hard-coded values make scripts inflexible Solution: Use parameters for anything that might change

2. Missing Parameter Validation

Problem: Scripts fail with cryptic errors Solution: Validate parameters at the start

3. No Error Handling

Problem: Scripts fail silently or with unclear messages Solution: We'll cover error handling in the next article

4. Forgetting Execution Policy

Problem: Scripts won't run on new systems Solution: Document execution policy requirements

Key Takeaways

• .ps1 files contain PowerShell scripts

• Execution policies prevent accidental execution

• Parameters make scripts reusable and flexible

• Validation attributes ensure correct input

• Comment-based help documents your scripts

• Organized structure improves maintainability

• #Requires ensures prerequisites are met

What You've Learned

✅ Creating and running PowerShell scripts ✅ Understanding and setting execution policies ✅ Using parameters with types and defaults ✅ Parameter validation techniques ✅ Comment-based help for documentation ✅ Script structure best practices ✅ Real-world script examples

Next Steps

Now that you can create scripts with parameters, you need control flow to make decisions. In Control Flow and Loops, you'll learn:

• If/ElseIf/Else statements

• Switch statements

• Loops (foreach, for, while)

• break and continue

• Processing collections efficiently

Control flow is what makes scripts intelligent - let's add decision-making to your scripts.

---

Ready to add logic to your scripts? Continue to Control Flow and Loops →