How powershell/dsc works
Project Type and Purpose
• DSCv3 is an open-source, cross-platform command-line tool for Desired State Configuration. It uses Rust and JSON schemas to declaratively author, discover, and invoke “resources” that enforce system state, without depending on PowerShell (though it can interoperate with PowerShell-based DSC resources).
• It’s structured as a Rust workspace comprising:
• A core CLI (dsc)
• A core library (dsc_lib) implementing parsing, schema validation, discovery, and configuration logic
• Multiple resource/extension crates (e.g., registry, osinfo, runcommandonset, dscecho, plus PowerShell adapters)
• A large schemas/ directory housing JSON schema definitions for config documents, resources, and outputs
• Documentation and examples under docs/ and dsc/examples/
High-Level Architecture Components
A. User Interface
• dsc CLI binary: entry point, parses command-line args, selects subcommands (config, resource, schema, completer)
B. Core Library
• dsc_lib:
– Parser (configuration documents, expression AST)
– Function evaluator (base64, concat, envvar, arithmetic, etc.)
– Discovery and dependency resolver (builds execution order)
– Configuration engine (invokes resources via resource_command module)
– Schema loader/validator (loads JSON schemas from schemas/)
C. Resource Plugins / Extensions
• Rust-based resource crates (e.g., registry, osinfo, runcommandonset, brew, apt, experimental, community resources)
• PowerShell adapter (invokes PS cmdlets or scripts)
• Each plugin exposes a CLI interface or JSON-over-stdout protocol and a manifest (*.dsc.resource.json)
D. Schemas & Metadata
• schemas/: JSON files defining request/response contracts for config docs, resource operations, CLI outputs
• Used by CLI and library for validation and documentation
E. Tests & Examples
• PowerShell integration tests (dsc/tests/*.ps1)
• Rust unit/integration tests per crate
• Example config documents under dsc/examples/
Component Interactions and Data Flow
1. User runs: dsc <subcommand> [options]
2. CLI (dsc) → Core library (dsc_lib): parse args, load JSON/YAML config document
3. Core library:
a. Validate document against JSON schema
b. Build resource dependency graph via discovery
c. Evaluate expressions and parameters
4. For each resource in graph:
a. Launch resource plugin process (Rust binary or PowerShell script)
b. Pass operation (Get/Set/Test) and parameters as JSON over stdin or args
c. Plugin executes idempotent logic, returns JSON status and outputs
5. Core library collects results, formats according to schema, CLI prints to console or returns exit code
6. CLI may also expose schema & help via built-in subcommands (e.g., dsc schema config.document)
Architectural Patterns & Principles
• Modular plugin architecture (Extension/Adapter pattern): new resources can be added as separate crates or scripts
• Schema-driven design: JSON Schema files act as source of truth for validation and tooling
• Layered structure: CLI layer → library layer → plugin layer
• Process isolation: each resource runs in its own process for fault isolation
• Workspaces & crates: clear separation of concerns via Rust workspace and dedicated crates
Checklist
• [ ] Group plugin crates under a “Resource Plugins” cluster
• [ ] Include schema repository as a shared service
• [ ] Annotate processes and interfaces (stdin/stdout, command-line args)