Skip to content

Resource Properties and Parameters

In PowerShell Desired State Configuration (DSC), resources are the building blocks for defining and enforcing system configurations. Each resource has parameters that specify the desired state and properties that represent the current state of the system. Understanding how to use these elements effectively is critical for creating robust DSC configurations.

Parameters: Defining the Desired State

Parameters are the inputs you provide to a DSC resource to define what the system should look like. They determine the target configuration and are typically set during resource instantiation. Parameters can be simple (e.g., strings, booleans) or complex (e.g., script blocks, arrays).

Example: File Resource

File ExampleFile
{
    Ensure = "Present"  # Parameter: Desired state (Present/Absent)
    DestinationPath = "C:\Example.txt"  # Parameter: File path
    Contents = "This is a test."  # Parameter: File content
}
  • Ensure: Specifies whether the file should exist (Present) or not (Absent).
  • DestinationPath: The path where the file must be located.
  • Contents: The text content the file must contain.

These parameters collectively define the desired state of the file resource.

Properties: Representing the Current State

Properties are the attributes of the system that the DSC resource checks to determine if the current state matches the desired state. They are often derived from the system's actual state (e.g., file existence, registry values, service status).

For example, the File resource checks the following properties: - Does the file exist at C:\Example.txt? - Does it contain the specified content?

If the current state (properties) matches the desired state (parameters), the resource reports success. Otherwise, it applies corrective actions.

Using Parameters in DSC Configurations

When writing DSC configurations, parameters are used to explicitly define the target state. Parameters can be: - Required: Mandatory for the resource to function (e.g., Ensure in the File resource). - Optional: Provide additional details (e.g., DependsOn to enforce resource order).

Example: Service Resource

Service MyService
{
    Name = "w3svc"  # Parameter: Service name
    StartupType = "Automatic"  # Parameter: Startup type
    State = "Running"  # Parameter: Desired state
}
  • Name: Required parameter to identify the service.
  • StartupType: Defines how the service starts (e.g., Automatic, Manual).
  • State: Ensures the service is running.

Key Considerations

  1. Parameter Types: Parameters can be simple or complex. For example, the Registry resource's Key parameter accepts a string path, while ValueData can take strings, integers, or binary data.
  2. Validation: DSC resources validate parameters during configuration. Invalid values (e.g., non-existent paths) trigger errors.
  3. Dynamic Parameters: Some resources use dynamic parameters (e.g., Script resource) to execute custom logic for state enforcement.

Key Takeaways

  • Parameters define the desired state of a system (e.g., file content, service status).
  • Properties represent the current state that DSC resources check against the desired state.
  • Use parameters to explicitly configure resources, ensuring the system meets your requirements.
  • Always validate parameters to avoid configuration errors and ensure compatibility with the target system.