The Microsoft DSC Handbook

Foreword by Steve Lee

Foreword by Jason Helmick

Preface

1. Who is this book for?
2. Code listings and typographic conventions
3. What you need for this book
4. Feedback
5. Published book version information
6. About the author

Introduction

1. The manual configuration era
2. The rise of configuration management
3. Enter PowerShell DSC
4. Microsoft DSC: a new foundation
5. Why Microsoft DSC?
6. DevOps and configuration management
7. Other resources

Chapter 1 - Getting Started with Microsoft Desired State Configuration

1. From Windows PowerShell to command-line utility
2. Configuration as data
3. Installing Microsoft Desired State Configuration
4. Manual installation
5. Using PowerShell
6. Using WinGet (Windows)
7. Setting up your development environment
8. Installing Visual Studio Code
9. Configuring schema validation
10. Enabling (tab)-shell completions
11. Running your first commands
12. Using a resource directly
13. Creating your first configuration document
14. Understanding get, set, and test operations
15. Exploring resource schemas
16. Finding help with resources and commands
17. Built-in help
18. Official documentation
19. Summary

Chapter 2 - Understanding Microsoft Desired State Configuration

1. A new foundation for the next generation of DSC
2. When PowerShell DSC met Microsoft DSC
3. From scripts to documents: rethinking how we write configurations
4. Redefining what a DSC resource is
5. Bridging worlds: PowerShell DSC resources in Microsoft DSC
6. Working with the DSC command-line interface
7. Understanding DSC output formats
8. Logging and troubleshooting using trace levels
9. Monitoring progress with progress formats
10. Summary

Chapter 3 - DSC Configuration Documents

1. The belly of the beast
2. Working with the dsc config command
3. Real-world examples
4. Example 1: Windows development workstation
5. Example 2: Setup fresh SQL Server 2025
6. Summary

Chapter 4 - Inside Configuration Documents

1. Peeling back the layers
2. The schema: your contract with DSC
3. Providing runtime flexibility with parameters
4. Defining reusable variables
5. Building the working units
6. Declaring dependencies
7. Directives and context
8. Functions and expressions
9. Validation and debugging
10. Summary

Chapter 5 - Built-in Resources

1. The toolbox that ships with DSC
2. How resources get packaged
3. Cross-platform resources
4. Microsoft/OSInfo
5. Microsoft.DSC.Debug/Echo
6. Microsoft.DSC.Transitional/RunCommandOnSet
7. Microsoft/Process
8. Microsoft.OpenSSH.SSHD/sshd_config
9. Windows-specific resources
10. Microsoft.Windows/Registry
11. Microsoft.Windows/RegistryList
12. Microsoft.Windows/FirewallRuleList
13. Microsoft.Windows/UpdateList
14. Microsoft.Windows/RebootPending
15. Microsoft.OpenSSH.SSHD/Windows
16. Linux-specific resources
17. DSC.PackageManagement/Apt
18. macOS-specific resources
19. DSC.PackageManagement/Brew
20. Meta resources
21. Microsoft.DSC/Group
22. Microsoft.DSC/Assertion
23. Microsoft.DSC/Include
24. Summary

Chapter 6 - Adapters

1. The translation layer
2. What makes an adapter an adapter
3. The PowerShell adapters
4. From one process to many: the adapter evolution
5. Anatomy of the PowerShell adapter manifests
6. Inside the adapter script
7. Entry point and parameter handling
8. Trace logging
9. Environment detection and setup
10. Module path customization
11. The List operation
12. The cache and performance
13. The helper modules
14. The WMI adapter
15. Discovery: CIM classes as resources
16. Invoking WMI resources
17. The registry adapter and data-driven resources
18. A different kind of adapter
19. The adapted resource manifest
20. Why this pattern matters
21. Summary

Chapter 7 - Extensions

1. When configuration alone isn’t enough
2. Three kinds of building blocks
3. What extensions can do: three capabilities
4. Discover: finding resources
5. Secret: retrieving sensitive values
6. Import: translating configuration formats
7. The extension manifest
8. Building secret extensions
9. The Azure Key Vault extension
10. Windows Credential Manager extension
11. Building a discovery extension: PowerShell module resources
12. The discovery script and manifest
13. Schema for class-based DSC resources
14. PowerShell as first-class citizen to Microsoft DSC
15. Building an import extension: MOF to DSC
16. The import extension manifest
17. The wrapper script
18. Testing the import extension
19. Summary

Chapter 8 - Advanced Patterns

1. Going beyond the basics
2. Resource capabilities: teaching DSC what your resource can do
3. implementsPretest: “I’ll check before I act”
4. handlesExist: “I know how to create and delete”
5. Building a Windows scheduled task resource
6. Assertions and conditions: validate before you act
7. How assertions and conditions work
8. Conditional execution
9. The if function
10. Combining conditions
11. Including external configurations
12. File-based includes
13. Parameterized includes
14. Building a configuration library
15. PowerShell adapter credential support
16. Faster discovery for PowerShell resources using adapted resource manifests
17. Anatomy of an adapted resource manifest
18. How DSC sends the path to the adapter
19. Creating your own adapted resource manifest
20. Adapted resources in manifest lists
21. The fast path under the hood
22. When and when not to use adapted resource manifests
23. Re-discovery of resources during deployment
24. How it works under the hood
25. A practical example: bootstrapping a dev environment
26. Performance trade-offs
27. Comparison with assertions
28. Previewing changes with what-if
29. How DSC handles what-if mode
30. Declaring native what-if support
31. Controlling return types with whatIfReturns
32. A real example: the Windows Registry resource
33. Implementing what-if in your own resource
34. The Bicep DSC extension: authoring DSC with Bicep
35. Bicep as a higher-order tool
36. What is bicep-types-dsc?
37. Authoring a configuration in Bicep
38. Running a configuration with local deploy
39. Summary

Chapter 9 - Integration

1. WinGet as higher-order tool
2. How WinGet hooks into dsc.exe
3. The WinGet configuration format
4. A graphical user interface above the configuration engine
5. How the GUI splits the work
6. Two tools, one authoring loop
7. OpenDSC: the missing enforcement layer
8. The enforcement engine
9. Local and pull operation
10. The server and its GUI
11. Getting started with OpenDSC
12. Summary

Chapter 10 - Building your own DSC resource

1. From consumer to creator
2. Choosing a language
3. The architecture: how a DSC resource CLI works
4. The command flow
5. Self-registration with init()
6. Defining the resource interface
7. Schema generation: teaching DSC about your properties
8. Schema overrides for special cases
9. Supporting lookup pattern for different inputs
10. When to omit test: letting DSC do the comparison
11. Manifest generation: making the build your source of truth
12. The bridge between your API and DSC
13. Logging to the DSC engine
14. Testing strategy: integration tests against the real API
15. Summary

Chapter 11 - Migrating from PowerShell DSC

1. The estate you already have
2. Why migrate at all?
3. Step one: inventory what you have
4. The four migration paths
5. Path A: adapt in place
6. Pinning versions during migration
7. Path B: import your compiled MOFs
8. Path C: from script-based to class-based
9. Path D: going native
10. Replacing the LCM: a feature-by-feature map
11. Migrating credentials
12. Exercise: migrate the BinderyOps estate end to end
13. Pitfalls from the field
14. Summary

Chapter 12 - DSC in DevOps pipelines

1. From loops you run to loops that run themselves
2. Why DSC fits pipelines so well
3. The five-stage pipeline model
4. Stage 1: validating documents
5. Stage 2: the drift gate
6. Stage 3: preview with what-if
7. Stage 4 and 5: apply, then prove it
8. Parameters as the environment boundary
9. A complete GitHub Actions workflow
10. The same shape in Azure DevOps
11. Making DSC observable in pipelines
12. Scheduled drift monitoring
13. Exercise: pipeline the registry configuration
14. Summary

Chapter 13 - Securing Your Configurations

1. The system that configures everything can break everything
2. A working threat model
3. Lever one: controlling the execution context
4. Lever two: secrets, done properly
5. Secure data types: controlling how values travel
6. Secret extensions: controlling where values live
7. Lever three: trusting the code you run
8. Trace hygiene
9. Lever four: evidence
10. Exercise: harden a configuration
11. Summary

Chapter 14 - AI-Assisted Configuration Management

1. A new kind of operator
2. Why DSC’s contract is AI-ready
3. AI-assisted authoring
4. Exercise A: grounded authoring
5. The MCP server: giving the model hands
6. Talking to the server without a client
7. The agentic loop
8. Guardrails for agents
9. Exercise B: drive the loop through MCP
10. What agents still can’t do
11. Summary

Chapter 15 - How DSC Compares

1. The architecture meeting question
2. First, know what DSC is (and isn’t)
3. DSC versus Terraform
4. DSC versus Ansible
5. DSC versus Puppet and Chef
6. DSC versus the Windows-native stack
7. The decision matrix
8. Summary

Closing thoughts

Appendix: A note on schema canonicalization

1. Two descriptions of the same contract
2. Why this matters
3. Where DSC is heading
4. What changes for a resource author
5. Why this belongs in an appendix
6. A final note

Release notes