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/UpdateList
12. Microsoft.Windows/RebootPending
13. Microsoft.OpenSSH.SSHD/Windows
14. Linux-specific resources
15. DSC.PackageManagement/Apt
16. macOS-specific resources
17. DSC.PackageManagement/Brew
18. Meta resources
19. Microsoft.DSC/Group
20. Microsoft.DSC/Assertion
21. Microsoft.DSC/Include
22. Summary

Chapter 6 - PowerShell adapters

1. The translation layer
2. From one process to many: the adapter evolution
3. Anatomy of the adapter manifests
4. Inside the adapter script
5. Entry point and parameter handling
6. Trace logging
7. Environment detection and setup
8. Module path customization
9. The List operation
10. The cache and performance
11. The helper modules
12. 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

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