How to Pause a PowerShell Script

PowerShell has become a cornerstone for automating administrative tasks on Windows. Over 300,000 IT pros now utilize PowerShell for critical infrastructure management according to a recent survey. Its flexibility allows both simple everyday scripts as well as complex workflows with error handling, interactions, and orchestration.

However, uninterrupted execution is not always desired when scripting. Pauses within PowerShell scripts provide control over flow, add interactivity, and enable better resilience.

In this comprehensive guide, you‘ll explore several methods for pausing with examples to use within your own projects. You‘ll also learn guidelines around resilience, recoverability, and continuity when halting scripts to keep solutions robust and runtime safe.

Why Pause a Script?

First, let‘s explore some common reasons for needing pauses:

1. Wait for User Input

Prompting for input during execution enables interactively running scripts with human-in-the-loop oversight:

$username = Read-Host -Prompt ‘Enter admin username‘

This simple pause lets an admin provide credentials before continuing.

2. Checkpoint Execution State

Insert pause points to inspect variable values and output during debugging:

Write-Output "Users = $($users.count)"  

Pause

Write-Output "Policy checks passed"

These debug breakpoints pause to validate expected state before continuing.

3. Interact with External Services

Pauses allow for coordination across requests to backends, APIs, websites:

$resp = Invoke-RestMethod https://api.contoso.com/data

Pause

$status = Invoke-WebRequest -URI https://api.contoso.com/status

This enables our script to halt until the first call finishes before continuing.

4. Throttle Speed

Introduce delays to slow overly aggressive automation that could overload systems:

Get-Mailbox -ResultSize 50 | ForEach {

  Sync-MailboxStatistics $_.Identity 

  Start-Sleep -Seconds 1

}

Here we throttle syncing statistics for 50 mailboxes to 1 per second.

5. Handle Recoverable Errors

Wrap in retries with pauses to make scripts more resilient:

$attempts = 3
do {

  $connectFailed = $false
  Try {
    Connect-Service -ErrorAction Stop
  }
  Catch {
    $connectFailed = $true 
  }

  if ($connectFailed) { Start-Sleep -Seconds 5 } 

} while ($connectFailed -and $attempts-- -gt 0) 

This pauses 5 seconds after connection failures to retry connectivity.

These examples demonstrate the flexibility pause points provide in PowerShell scripts. Let‘s explore the various methods next.

PowerShell Pause Commands

PowerShell offers several ways to insert pauses into scripts:

Command	Description
Pause	Simple breakpoint prompting user to continue
Read-Host	Wait for user input
Start-Sleep	Pause execution for specified time
Wait-Event	Halt until specified event fires
Start-Job	Execute code asynchronously as background job

The simplest is Pause which displays a prompt until keypress. More advanced methods like Start-Job enable asynchronous background execution.

1. The Pause Command

The most straightforward approach is the Pause command. This displays a simple "Press Enter to continue…" prompt halting execution:

Write-Output "Preparing to start service"

Pause

Start-Service -Name "WorkFlowApp"

After the informational message, Pause acts as a breakpoint for inspection before allowing the service start.

Customize Pausing Behavior

You can wrap Pause to parameterize and standardize behavior:

Function Pause-WithMessage {

  param(
    [Parameter(Mandatory)]
    [string]$Message,

    [int]$Seconds = 0
  )

  if ($Seconds -gt 0) {
    Write-Output "$Message - Pausing for $Seconds seconds"  
    Start-Sleep $Seconds
  } 
  Else {
    Write-Output $Message
    Pause 
  }

}

Pause-WithMessage "About to start migration" -Seconds 10

# Rest of script...

Now reusable logic controls behavior like auto-continuing after timed intervals.

Nesting Pause Levels

It‘s also possible to nest pauses for additional checkpoints:

Write-Output "Audit pre-check complete"  

Pause

Write-Output "Security scanning..."  

Pause

Write-Output "Validation passed, proceeding"

# Rest of script...

This stepped inspection pauses twice – useful in complex flows needing incremental validation.

2. Capturing User Input with Read-Host

For interactive scripts, use Read-Host to prompt the user for input:

$username = Read-Host -Prompt "Enter admin username"

This simple prompt lets an admin provide credentials before action. The -Prompt parameter controls the message shown:

Prompting for runtime parameters with Read-Host

You can also validate and retry bad inputs:

do {

  $username = Read-Host -Prompt "Enter admin username"

  if (-not $username) {
    Write-Warning "Username required"  
  }

} while (-not $username)

This forces reentry until a non-blank username is captured.

3. Waiting with Start-Sleep

To pause execution for a defined duration, leverage the Start-Sleep cmdlet:

Write-Verbose "Pausing for 30 seconds"
Start-Sleep -Seconds 30
Write-Verbose "Continuing execution"

This inserts a 30 second system wait.

Start-Sleep accepts seconds, minutes, hours or timespans:

Start-Sleep -Seconds 10 # seconds 
Start-Sleep -Minutes 1 # minutes
Start-Sleep -Hours 1 # hours
Start-Sleep -TimeSpan (New-TimeSpan -Mins 30) # timespan 

Timespan allows calculations like pausing based on the call time of another operation without hardcoding.

Handling Outputs

Note when using Start-Sleep the underlying thread is blocked on resume so any screen outputs may not render immediately.

You can workaround this by appending newlines:

Write-Host "Pausing..."; Write-Host ""

Start-Sleep 5

Write-Host "Operation complete!"; Write-Host ""

The blank lines allow flush so status renders despite the blocked pipeline.

4. Waiting on Events with Wait-Event

To synchronize your script based on system events, leverage the Wait-Event cmdlet. This pauses execution until a matching event fires.

Events require a publishing source which emit notifications to subscribers. First enable object events on the source .NET object:

$timer = New-Object Timers.Timer 
Register-ObjectEvent -InputObject $timer -EventName Elapsed -SourceIdentifier Timer.Elapsed

Now scripts can wait up to 10 seconds on the Timer.Elapsed event:

Wait-Event -SourceIdentifier Timer.Elapsed -Timeout 10

If the time expires before the event fires, execution will continue. This avoids deadlocks.

Similarly, scripts could wait on custom PowerShell events published from other jobs:

Register-EngineEvent -SourceIdentifier Job.Complete

Start-Job -Name MyJob -ScriptBlock {

  # Long running task...

  $event = New-Object System.Management.Automation.PSEventArgs
  $event.SourceIdentifier = "Job.Complete"  
  $event.MessageData = "MyJob finished"

  $evt = New-Event -SourceIdentifier Job.Complete -MessageData "MyJob finished" -EventArguments $event
  Publish-Event -Event $evt  

}

Wait-Event -SourceIdentifier Job.Complete 

This demonstrates synchronizing script execution across asynchronous events.

5. Background Jobs with Start-Job

Start-Job initiates a PowerShell scriptblock in a background job. Jobs run asynchronously freeing the console for other interactions.

Here is an example executing a function as a fire-and-forget job:

Start-Job -Name "ArchiveReports" -ScriptBlock {

  param($logPath)

  . C:\Scripts\Utils.ps1

  Archive-Reports -Path $logPath

} -ArgumentList "C:\Logs\" 

We start the archive task as an unmamanged job by passing the reuseable logic as an inline script block. Runtime parameters get populated too.

This async approach prevents long running processes from blocking a workflow.

Coordinating Across Jobs

Coordination between the console thread and jobs can use events:

$archivedEvent = Register-ObjectEvent -InputObject $job  -EventName StateChanged –SourceIdentifier Job.Status

$result = Wait-Event -SourceIdentifier Job.Status

if ($result.MessageData -eq "Completed") {

  Write-Output "Success - reports archived!" 

} else  {

  Write-Warning "Job failed"

}

Here we subscribe to state changes of the job to synchronize, waiting until it finishes.

This demonstrates asynchronous orchestration patterns between scripts.

Guidelines for Pause Resilience

While pauses provide control over flow, take care to build resilent mechanisms that avoid deadlocks or unrunnable logic.

Follow these guidelines:

Use Timeout Parameters

For timed waits, specify -Timeout values prevent infinite pauses:

Wait-Event -SourceIdentifier JobComplete -Timeout 60

Omitting this risks halting forever if the event never fires.

Implement Retry Logic

To avoid single points of failure, implement try/catch blocks with retry:

$attempts = 3

while ($attempts -gt 0) {

  try {
    $reply = Invoke-WebService $payload 
    break
  }
  catch {
    $attempts -= 1
    Start-Sleep -Seconds 10
  }

}

if (-not $reply) {
  Throw " retries failed!$
}

This provides resilience for transient errors like network drops.

Plan Escape Routes

Design mechanisms to break out of paused state like keyboard interrupts:

try {

  Pause

} 
catch [System.Management.Automation.PipelineStoppedException] {

  # Broke out of Pause

}

Trapping terminations allows emergency exits.

Document Pause Points

Clearly call out pauses within scripts to avoid losing context:

# Pausing to validate service status before restart
Pause  

# Restart service
Restart-Service -Force

Annotations prevent confusion around halted logic.

Conclusion

Within PowerShell scripts, pauses provide control over execution flow while offering resilience. Use native commands like Pause, Read-Host, Start-Sleep, Wait-Event and Start-Job to insert delays or interactivity.

Follow best practices around timeouts, retries, planning exits, and documentation to keep solutions robust across pauses. Ultimately mastering methods to interrupt flows both empowers admins to interact as well enables coordinating PowerShell‘s automation capabilities across systems.