Leanpub Header

Skip to main content
Go to Leanpub.com

Four-Phase Orchestration

Engineering Idempotent PowerShell for Windows Endpoint Automation

This book is 100% completeLast updated on 2026-07-26
Owen Heaume

A four-phase discipline for PowerShell automation that has to actually work, built around one real, escalating case study from cover to cover.

Minimum price

$24.99

$39.99

You pay

Author earns

$

Also available for 1 book credit with a Reader Membership

PDF
EPUB
342
Pages
87,319Words
About

About

About the Book

Most PowerShell automation starts as a script and ends as a liability: a long list of commands that either all succeed, or fail halfway through and leave a machine in some undocumented state nobody can diagnose afterward. This book teaches a different way to build it.

Four-Phase Orchestration is a practical, from-first-principles guide to structuring PowerShell 5.1 automation the way senior engineers structure production software: as four distinct phases, Discovery, Validation, Logic, and Execution, each with exactly one job and a strict rule about what it's never allowed to do. Discovery only ever observes. Logic only ever decides. Execution only ever commits, and never asks whether it should, only whether it can and whether it worked. Get that separation right, and an entire category of 3 AM failures, the ones where nobody can tell you what state the machine is actually in, stops being possible by design rather than by luck.

This isn't a set of tips bolted onto a script, and it isn't a framework you have to prove out yourself. The four-phase template and the instrument library behind it are real, working PowerShell 5.1 code, built and refined against a live Windows 11 environment throughout the book's own development, including several genuine bugs found and fixed along the way and kept in as the teaching moments they became. It's demonstrated end to end through a single, continuously developed scenario, a further-education college maintaining a fleet of classroom PCs against real, believable configuration drift, so you watch the architecture solve one escalating problem across the whole book rather than piecing it together from disconnected snippets. What you take away isn't a set of ideas to go test for the first time yourself, it's a working foundation you adapt.

What you'll actually build:

  • A four-phase script skeleton any engineer on your team can open and immediately understand, regardless of who wrote it
  • A library of atomic, single-purpose instruments that either observe safely or commit exactly one change, with a naming convention that tells a reviewer what a function is allowed to do before they read a line of it
  • A structured, JSON-ready forensic record of every run, detailed enough to reconstruct exactly what happened on a machine days or weeks later, without reproducing the problem
  • -WhatIf support that's a structural guarantee, not an if statement in the wrong place
  • Idempotent logic that only acts when something is actually wrong, calculated entirely before a single setting changes
  • A working Pester test suite for the framework itself, so you prove your logic is correct by mocking the environment, not by testing against a live machine

This is written for PowerShell practitioners already comfortable with functions, objects, and error handling, who are past writing one-off scripts and into the harder problem: building automation an entire team can maintain, trust, and hand off. If you're standardising how your department automates Windows 10/11 endpoints, or you're tired of being the only person who can debug last year's deployment script, this is the book that gets you there.

Share this book

Categories

PowerShellSoftware ArchitectureComputers and Programming

Feedback

Email the Author

Installments completed

27 / 27

Author

About the Author

Owen Heaume

Owen Heaume is a PowerShell automation engineer and technical author specialising in enterprise Windows endpoint management. He is the author of two previous books with Apress, Understanding Microsoft Intune and Getting Started with Pester 5, both written to help engineers get real, practical command of tools that are widely used in production but often thinly documented relative to how much actually depends on them.

Four-Phase Orchestration grew out of the same instinct that shaped those two books: that competence with a tool and confidence in the systems built with it are not the same thing, and that the gap between them is where most production incidents actually live. Years spent maintaining PowerShell automation across real, drifting Windows fleets convinced Owen that the biggest reliability problems weren't a missing cmdlet or a syntax mistake, they were architectural: scripts with no answer for what should happen when something goes wrong halfway through.

This book is the discipline he built in response to that problem, tested the way it's taught, against a real environment, not only reasoned about on paper.

Contents

Table of Contents

Preface

Who This Book Is For

How to Use This Book

  1. Part I: The Case for Deterministic Orchestration

Chapter 1: The Problem with Procedural Scripts

  1. 1.1 The Script That Worked, Until It Didn’t
  2. 1.2 Four Symptoms of Procedural Rot
  3. 1.3 Why This Matters at Fleet Scale
  4. 1.4 Introducing Ashfield College
  5. 1.5 What Solving This Properly Requires
  6. Chapter Summary

Chapter 2: The Four-Phase Contract

  1. 2.1 Four Questions, Not Four Steps
  2. 2.2 The Central Rule
  3. 2.3 One-Way Data Flow
  4. 2.4 Why Four, and Not Three or Five
  5. 2.5 Resolving Chapter 1, Symptom by Symptom
  6. 2.6 The Shape in 4-phase.ps1
  7. Chapter Summary

Chapter 3: The Atomic Instrument

  1. 3.1 The Instrument, Not the Orchestrator
  2. 3.2 The Discovery Contract
  3. 3.3 The Execution Contract
  4. 3.4 Execution Instruments Are Dumb On Purpose
  5. 3.5 Why Scalar, Not Iterative
  6. 3.6 The Naming Convention Is Part of the Contract
  7. Chapter Summary
  8. Part II: The Framework Chassis

Chapter 4: The Parameter Gate and the Metadata Block

  1. 4.1 A Parser-Level Guarantee, Not a Style Convention
  2. 4.2 Why This Bites Hardest at the Worst Possible Time
  3. 4.3 No CmdletBinding at the Top: A Deliberate Absence
  4. 4.4 The Metadata Block: Identity as a First-Class Citizen
  5. 4.5 Why Metadata Is Not a Parameter
  6. Chapter Summary

Chapter 5: Transcription as a Forensic Requirement

  1. 5.1 Two Kinds of Audit Trail
  2. 5.2 The IntuneManagementExtension\Logs Convention
  3. 5.3 The %TEMP% Fallback, and What It Actually Costs
  4. 5.4 Defensive by Necessity: Stop-Transcript Before Start-Transcript
  5. 5.5 Stop-fpTranscript and the Discipline of a finally Block
  6. 5.6 $CurrentLogFile: Why a Side Channel Was Never Necessary
  7. Chapter Summary

Chapter 6: Two Data Contracts, Config and Pipeline

  1. 6.1 Generated Output, Authored Input
  2. 6.2 New-fpPipelineObject: A Fixed Skeleton, Not a Growing Object
  3. 6.3 Get-fpStaticPipeline: Solving a Problem That No Longer Exists
  4. 6.4 $config: Desired State, Authored by a Human
  5. 6.5 A First Pass at the Ashfield $config
  6. Chapter Summary

Chapter 7: The Visual Grammar of the Console

  1. 7.1 Why Console Output Deserves Its Own Contract
  2. 7.2 Write-fpConsoleLog: Seven Types, One Grammar
  3. 7.3 What Actually Survives Into the Transcript
  4. 7.4 Write-fpObjectToLog: Deconstruction as a Console Convenience
  5. 7.5 Two Header Functions, Two Jobs
  6. Chapter Summary
  7. Part III: Phase 1, Discovery

Chapter 8: The Principle of Passive Interrogation

  1. 8.1 Read-Only Is Necessary. Passive Is the Actual Standard.
  2. 8.2 The Temptation to Test by Doing
  3. 8.3 Facts, Not Opinions: The Boundary Discovery Must Not Cross
  4. 8.4 Test-Path: An Audit of Every Call Site
  5. 8.5 What This Buys You When the System Is Actually on Fire
  6. Chapter Summary

Chapter 9: The Discovery Library, Read One Instrument at a Time

  1. 9.1 Get-fpService: The Simplest Case
  2. 9.2 Get-fpRegistryValue: The One That Nearly Broke the Contract
  3. 9.3 Get-fpFile: The Reference Pattern
  4. 9.4 Get-fpFileEncoding: Reading Bytes Without Reading the File
  5. 9.5 Get-fpShortcut: COM in Discovery, and Why That’s Fine Here
  6. 9.6 Test-fpPathExists: One Instrument, Two Providers
  7. Chapter Summary

Chapter 10: The Conductor and the Predicate

  1. 10.1 What a Conductor Actually Does
  2. 10.2 Which Facts Earn Their Own Instrument
  3. 10.3 Test-fpIsAdmin: Discovery’s Interrogation, Not Validation’s Verdict
  4. 10.4 Which Direction Elevation Actually Needs to Run
  5. 10.5 What Happens When Composition Itself Fails
  6. 10.6 An Aggregation Idiom Worth Retiring
  7. Chapter Summary
  8. Part IV: Phase 2, Validation

Chapter 11: Hard Stops vs Soft Exits

  1. 11.1 Two Ways For a Run To Stop
  2. 11.2 Why Elevation Never Gets to Be a Soft Exit
  3. 11.3 The General Principle, For Checks This Book Has Not Written Yet
  4. Chapter Summary

Chapter 12: Building Get-fpValidation

  1. 12.1 What Runs Before Any Check Does
  2. 12.2 Why a Check Cannot Be Anything but a Predicate
  3. 12.3 Why the Function Returns a Dictionary, Not Just a Verdict
  4. Chapter Summary
  5. Part V: Phase 3, Logic

Chapter 13: The Brain of the Orchestrator

  1. 13.1 A Different Shape of Comparison
  2. 13.2 Reading Discovery, Never Re-Asking It
  3. 13.3 What Logic Decides, and What It Refuses to Touch
  4. 13.4 An Empty List Is Still a Complete Answer
  5. 13.5 Why Execution Never Has to Ask
  6. Chapter Summary

Chapter 14: Constructing the Work Order

  1. 14.1 The Initialisation That Isn’t Optional
  2. 14.2 Returning Without Losing the Shape
  3. 14.3 A Second Guard at the Call Site, and Why It Isn’t the Same Mistake
  4. 14.4 Reason Exists for a Reader, Not for the Machine
  5. Chapter Summary

Chapter 15: Case Study, the Ashfield Work Order Matrix

  1. 15.1 What Discovery Has to Have Gathered First
  2. 15.2 Extending Ashfield’s Config
  3. 15.3 Six Requirements, Seven Comparisons, Two Prerequisites
  4. 15.4 Three Machines, One Function, Zero Code Changes
  5. Chapter Summary
  6. Part VI: Phase 4, Execution

Chapter 16: The Task Dispatcher Pattern

  1. 16.1 The One Loop in the Whole Framework
  2. 16.2 Why the Switch Lives in the Dispatcher, Not the Instruments
  3. 16.3 The Default Case Is Not Decoration
  4. 16.4 The Same Lesson, a Second Time
  5. 16.5 WhatIf Passes Through, It Doesn’t Originate Here
  6. Chapter Summary

Chapter 17: Building the Execution Library

  1. 17.1 The Shape Every Instrument Shares
  2. 17.2 The Refactor: Start-fpService and Set-fpService
  3. 17.3 Set-fpRegistryValue: No Exception Needed Anymore
  4. 17.4 Set-fpIniValue: The Same Simplification, Applied to a File
  5. 17.5 New-fpRegistryKey and New-fpFileStructure: Where the Exception Went
  6. 17.6 Remove-fpIniValue: Removal Is Mechanical, Not Judgment
  7. 17.7 Set-fpShortcut and Set-fpFileEncoding
  8. Chapter Summary

Chapter 18: WhatIf as a First-Class Citizen

  1. 18.1 The Automatic Way and the Manual Way
  2. 18.2 The Automatic Message Doesn’t Speak This Transcript’s Language
  3. 18.3 Every Instrument Has to Return a Real Result Object, Even in Simulation
  4. 18.4 Determinism Over Convention
  5. 18.5 What This Trade Gives Up
  6. Chapter Summary

Chapter 19: The Result Object and Forensic Capture

  1. 19.1 Four Fields, Every Time
  2. 19.2 Why the Contract Doesn’t Need to Say What Was Attempted
  3. 19.3 Turning a List of Results Into One Verdict
  4. 19.4 A Gap in the Contract’s Own Enforcement
  5. 19.5 One Assignment, One Exit
  6. Chapter Summary
  7. Part VII: The Ashfield College Scenario, End to End

Chapter 20: Defining the Scenario

  1. 20.1 A Requirements Document Is Not a Config File
  2. 20.2 Why Now
  3. 20.3 The Ashfield Classroom PC: Six Requirements
  4. 20.4 What This Document Doesn’t Decide
  5. 20.5 The Complete Config
  6. Chapter Summary

Chapter 21: Discovery Implementation

  1. 21.1 Filling the Extension Point
  2. 21.2 Two Facts, One Node: What IniPolicy Reports
  3. 21.3 Assembling the Extended Host Object
  4. 21.4 Extending MAIN’s Reporting Block
  5. Chapter Summary

Chapter 22: Validation Implementation

  1. 22.1 Why This Phase Needed No Extension Point
  2. 22.2 PRE-1: Administrative Context
  3. 22.3 PRE-2: Available Disk Space
  4. 22.4 What the Transcript Actually Shows
  5. Chapter Summary

Chapter 23: Execution and Dispatch

  1. 23.1 Wiring Logic Into the Template
  2. 23.2 The Dispatcher Learns Nine New Words
  3. 23.3 Why Service State No Longer Composes Two Calls Into One
  4. 23.4 A Dry Run for the Whole Estate
  5. Chapter Summary

Chapter 24: Reading the Forensics

  1. 24.1 Two Artifacts, One Underlying Object
  2. 24.2 A Coarse Status Hides a Story Worth Reading Further
  3. 24.3 Matching a Result Back to the Item That Staged It
  4. 24.4 Reading a Run That Never Reached Execution
  5. Chapter Summary
  6. Part VIII: Hardening the Framework

Chapter 25: Unit Testing the Framework with Pester

  1. 25.1 The Tests Appendix E Already Asked For
  2. 25.2 Mocking Get-Service: What Discovery Needs That Logic Didn’t
  3. 25.3 Testing the Post-Flight Check: Proving a Lying Cmdlet Gets Caught
  4. 25.4 What Mocking Can’t Give You
  5. Chapter Summary

Chapter 26: Extending the Instrument Library

  1. 26.1 Get-fpFirewallRule: Filling In the Discovery Template
  2. 26.2 Set-fpFirewallRule: Filling In the Execution Template, and Earning Its Post-Flight Check
  3. 26.3 A Short Note on Where Discovery Is Allowed to Look
  4. 26.4 Closing the Loop: What Comes After Writing the Pair
  5. 26.5 Looking Up What Already Exists
  6. 26.6 One Dependency Worth Knowing About Before You Test in Isolation
  7. Chapter Summary

Chapter 27: Anti-Patterns and Common Failures

  1. 27.1 A Discovery Instrument That Mutates “Just This Once”
  2. 27.2 A Logic Comparison That Calls Get-Service Directly
  3. 27.3 An Execution Instrument That Re-Implements Discovery’s Own Check
  4. 27.4 An Execution Instrument Whose -WhatIf Check Arrives Too Late
  5. 27.5 A Pipeline Object Serialised Before EndTime Is Set
  6. Chapter Summary

Appendix A: Full Annotated Listing

Appendix B: Atomic Instrument Library Reference

  1. Discovery Instruments
  2. Execution Instruments
  3. The Template’s Own Placeholder

Appendix C: Troubleshooting Guide

  1. The Transcript Won’t Start
  2. JSON Serialisation: Slow, Truncated, or Silently Wrong, Not Actually Hanging
  3. COM Object Leak: Get-fpShortcut, Not Set-fpShortcut

Appendix D: Pester Test Suite for the Ashfield Scenario

  1. Logic: All Nine Comparisons
  2. Discovery: Confirming the $null-on-Absence Contract
  3. Execution: Happy Path and the WhatIf Short-Circuit
  4. What This Suite Does and Doesn’t Prove

Appendix E: Recommended Build Order for a New Orchestration

Get the free sample chapters

Click the buttons to get the free sample in PDF or EPUB, or read the sample online here

Download Sample PDFDownload Sample EPUB

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub