DSCv3 Documentation

DSCv3 is an open-source command-line application that provides a declarative and idempotent way to manage software components. Unlike its predecessor, DSCv3 is platform-agnostic and does not require PowerShell to run.

Key Capabilities:

• Multi-language Resource Authoring: Author resources in any language (e.g., Bash, Python, C#, Go).
• Resource Invocation: Invoke individual resources directly via the CLI.
• Configuration Documents: Create documents that define the desired state of a system using JSON or YAML.

Core Differences from PowerShell DSC:

• No PowerShell Dependency: Can run without PowerShell installed.
• No Local Configuration Manager (LCM): DSCv3 is invoked as a command rather than running as a background service.
• Schema Format: Non-PowerShell resources use JSON files for schemas instead of MOF files.
• Configuration Format: Configuration documents use JSON or YAML instead of PowerShell script files.
• Resource Compatibility: While configuration documents are not compatible, DSCv3 can still invoke existing PowerShell DSC Resources (script-based and class-based) on both Windows PowerShell and PowerShell.

DSCv3 includes several built-in resources available immediately after installation. These resources are categorized by their primary function: asserting state, adapting existing tools, changing machine state, debugging, or managing resource groups.

Resource Categories

• Assertion Resources: Used to query the current state of a machine without modifying it. Examples include Microsoft/OSInfo, Microsoft.DSC/Assertion, and Microsoft.Windows/RebootPending.
• Adapter Resources: Used to leverage existing tools that do not have a native DSC Resource Manifest. Examples include Microsoft.Adapter/PowerShell, Microsoft.Adapter/WindowsPowerShell, and Microsoft.Windows/WMI.
• Configurable Resources: Used to directly change the state of a machine. Examples include Microsoft.DSC.Transitional/RunCommandOnSet and Microsoft.Windows/Registry.
• Debugging Resources: Used for exploring or debugging DSC configurations without affecting the machine state. Example: Microsoft.DSC.Debug/Echo.
• Group Resources: Used to control how DSC processes groups of nested resource instances. Examples include Microsoft.DSC/Assertion, Microsoft.DSC/Group, and Microsoft.DSC/Include.

The Microsoft.Windows/Registry resource allows you to idempotently manage Windows Registry keys and values. You can use it to add, update, or remove registry keys and values.

IMPORTANT

The registry command and Microsoft.Windows/Registry resource are a proof-of-concept example for use with DSC. Don't use it in production.

Capabilities

• get: Retrieve the actual state of an instance.
• set: Enforce the desired state.
• whatIf: Report how changes would be made without applying them.
• delete: Directly remove an instance from the system.

Requirements

• Must be run on a Windows system.
• The process must have sufficient permissions to manage the keys in the hive specified by keyPath.

resources:
  - name: <instance name>
    type: Microsoft.Windows/Registry
    properties:
      keyPath: string
      _exist: <boolean>
      valueName: <string>
      valueData: <object>

The Microsoft.Windows/FirewallRuleList resource allows for idempotent management of Windows Firewall rules via the netfw.h COM APIs. A single resource instance manages an array of rules, enabling you to create, update, or remove multiple rules in a single operation.

Key Capabilities

• Retrieve State: Get the current configuration of specific named firewall rules.
• Manage Rules: Create new rules, update existing ones, or remove rules by setting _exist: false.
• Export Rules: Export all registered firewall rules on the system, with optional filtering by rule properties.

Requirements

• Platform: Windows only.
• Privileges: Both set and export operations require an elevated (administrator) process context. Running these in a non-elevated context will result in an error.

Important: The _exist Property Behavior

The _exist property behaves differently than standard DSC resources:

• If a rule exists in the Windows Firewall store, the _exist field is omitted from the returned state (meaning the rule is present).
• If a rule is not found, _exist: false will appear in the response.
• Therefore, a missing _exist field in the actual state indicates the rule exists.

resources:
  - name: <instance name>
    type: Microsoft.Windows/FirewallRuleList
    properties:
      rules:
        - name: string
          action:
          applicationName:
          description:
          direction:
          edgeTraversal:
          enabled:
          grouping:
          interfaceTypes:
          localAddresses:
          localPorts:
          profiles:
          protocol:
          remoteAddresses:
          remotePorts:
          serviceName:
          _exist: false # Use to remove a rule

The Microsoft.Windows/FeatureOnDemandList resource allows you to idempotently manage Windows features on demand (capabilities) using the DISM API. This is useful for managing optional components like language packs, OpenSSH, or RSAT tools.

Key Operations

• Get: Retrieve the current state of capabilities by their identity.
• Set: Enforce a desired state (Installed or NotPresent) for specific capabilities.
• Export: Enumerate all capabilities on the system, with optional filtering by identity, state, displayName, or description (supports wildcards).

Requirements

• Must be run on a Windows system.
• Requires an elevated (administrator) process context.
• Installing capabilities may require internet access or a configured Windows Update / WSUS source.

Installation Note

This resource is installed automatically with DSC on Windows systems. To update the resource, update DSC itself.

resources:
  - name: <instance name>
    type: Microsoft.Windows/FeatureOnDemandList
    properties:
      capabilities:
        - identity: string
          state: Installed | NotPresent