Your first resource invocation

You have DSC installed and understand its purpose. Now it's time to put it to use.

This lesson teaches you to work with DSC resources. You'll explore the Microsoft.Windows/Registry resource. You'll discover its properties and understand the data types associated with them. Then, you'll invoke the resource directly from the command line.

Exploring resource schema

You need to know what a resource can do. The schema tells you this. The schema describes the properties and shows the relevant data types. It marks the required properties and the optional ones. It explains what each property does.

To examine the Microsoft.Windows/Registry schema, run the following command:

dsc resource schema --resource Microsoft.Windows/Registry

The command returns a YAML schema document. Here's a truncated version of the key properties:

$schema: https://json-schema.org/draft/2020-12/schema
title: Registry
type: object
properties:
  keyPath:
    description: The path to the registry key.
    type: string
  _metadata:
    description: The information from a config set --what-if operation.
    anyOf:
    - $ref: '#/$defs/Metadata'
    - type: 'null'
  valueName:
    description: The name of the registry value.
    type:
    - string
    - 'null'
  valueData:
    description: The data of the registry value.
    anyOf:
    - $ref: '#/$defs/RegistryValueData'
    - type: 'null'
  _exist:
    type:
    - boolean
    - 'null'
additionalProperties: false
required:
- keyPath

The schema shows you four things:

• keyPath is required. It must be a string. This is the registry path.
• valueName is optional. It can be a string or null. This is the value name within the key.
• valueData holds the actual data you want to set. It references the RegistryValueData definition.
• _exist determines if the key exists. It returns a boolean or null value.

Don't worry if the full schema seems overwhelming at first. The complete schema includes many technical details about type definitions and validation rules. You don't need to understand every line at this moment. The key is knowing which properties you can use and what they do. As you work with the resource, the schema will make more sense.

The best way to learn is through hands-on experience. Let's start using the resource.

Working with the dsc resource command

The dsc resource command works with individual resources. You don't need a full configuration document at this point. Running the dsc resource <operation> command is perfect for learning and testing.

The command supports several operations:

• list – List or find resources available on your system.
• get – Invoke the get operation to retrieve the current state.
• test – Invoke the test operation to check if state matches desired state.
• set – Invoke the set operation to apply the desired state.
• delete – Invoke the delete operation to remove a resource instance.
• export – Retrieves all resource instances from your system.

Each operation serves a purpose. This lesson will focus on the three most common operations, as well as a new one (delete). These form the core workflow for managing resources.

Get the current state

To check if a registry key exists and retrieve its current values, use the get operation. You provide the resource properties as JSON input.

Here's how to check the current state of a registry key:

# Build JSON from hashtable
$in = @{
    keyPath = 'HKLM\Software\Microsoft\Windows\CurrentVersion'
    valueName = 'ProgramFilesDir'
} | ConvertTo-Json -Compress
dsc resource get -r Microsoft.Windows/Registry -i $in

This command:

1. Creates a compressed JSON string with the registry path and value name.
2. Specifies the short alias resource type -r.
3. Adds the input content to the short alias -i.

The output shows the current state:

actualState:
  keyPath: HKLM\Software\Microsoft\Windows\CurrentVersion
  valueName: ProgramFilesDir
  valueData:
    String: C:\Program Files

Notice the valueData field. It includes the data type and the actual value.

Testing the desired state

Before making changes, you may want to check if the system is already in the desired state. Does a registry value already match what you want?

The test operation answers this question. To test if a custom registry value already exists, run the following:

$in = @{
    keyPath = 'HKCU\Software\MyApplication'
    valueName = 'ConfigPath'
    valueData = @{
        String = 'C:\MyApp\config.json'
    }
} | ConvertTo-Json -Depth 3 -Compress
dsc resource test -r Microsoft.Windows/Registry -i $in

The output tells you whether the current state matches the desired state:

desiredState:
  keyPath: HKCU\Software\MyApplication
  valueData:
    String: C:\MyApp\config.json
  valueName: ConfigPath
actualState:
  keyPath: HKCU\Software\MyApplication
  _exist: false
inDesiredState: false
differingProperties:
- valueData
- valueName
- _exist

The output shows you three important things:

• inDesiredState: false tells you the truth. The registry value doesn't match your desired configuration
• differingProperties list exactly which properties don't match. In this case, valueData, valueName, and _exist all differ. This helps you understand what needs to change.

The key doesn't exist yet. That's why _exist is false, and the other properties are missing from the actual state.

Setting the desired state

You've tested the configuration. You know it doesn't match, so you want to fix that. The set operation applies your desired state. It makes the changes happen.

To set the previous example, change the test operation to set:

$in = @{
    keyPath = 'HKCU\Software\MyApplication'
    valueName = 'ConfigPath'
    valueData = @{
        String = 'C:\MyApp\config.json'
    }
} | ConvertTo-Json -Depth 3 -Compress
dsc resource set -r Microsoft.Windows/Registry -i $in

The command will create the registry key if needed. It sets the value. The output shows two states. Before and after:

beforeState:
  keyPath: HKCU\Software\MyApplication
  _exist: false
afterState:
  keyPath: HKCU\Software\MyApplication
  valueName: ConfigPath
  valueData:
    String: C:\MyApp\config.json
changedProperties:
- valueName
- valueData
- _exist

The output confirms the change. The beforeState shows the key didn't exist. The afterState shows it now exists with the correct values. The changedProperties array lists exactly what changed. You have now successfully created a registry key.

Before closing the lesson, let's review the registry value types and examine one more practical example.

Understanding registry value types

When you've worked with the registry before, you know it supports multiple value types. When you work with the valueData property, you need to specify the correct type. This type matters; otherwise, the underlying DSC Resource fails.

Here's a table representing each value type:

So, let's say you want to use a DWord value. Here is an example using a DWord value type:

$in = @{
    keyPath = 'HKCU\Software\MyApplication'
    valueName = 'MaxConnections'
    valueData = @{
        DWord = 100
    }
} | ConvertTo-Json -Depth 3
dsc resource set -r Microsoft.Windows/Registry -i $in

Practical example: Application configuration

Imagine the following. You deploy an application. It stores configuration data in the registry. You need three things:

1. Check if the configuration already exists.
2. Create it if it doesn't.
3. Verify if it was created correctly.

Let's go through the steps once again.

Step 1 – Check the current state

First, you'll fetch the current state to check if the configuration already exists:

$check = @{
    keyPath = 'HKCU\Software\MyApp\Settings'
    valueName = 'DatabasePath'
} | ConvertTo-Json -Compress
dsc resource get -r Microsoft.Windows/Registry -i $check

If _exist equals false, the valueName does not exist.

Step 2 – Set the configuration

When you verified that the current state does not exist, you can set the configuration:

$config = @{
    keyPath = 'HKCU\Software\MyApp\Settings'
    valueName = 'DatabasePath'
    valueData = @{
        String = 'C:\ProgramData\MyApp\database.db'
    }
} | ConvertTo-Json -Depth 3 -Compress
dsc resource set -r Microsoft.Windows/Registry -i $config

This will create the registry key DatabasePath with the value data provided to the registry.

Step 3 – Verify the configuration

Now that the configuration is set, you can verify it by running dsc resource test:

$verify = @{
    keyPath = 'HKCU\Software\MyApp\Settings'
    valueName = 'DatabasePath'
    valueData = @{
        String = 'C:\ProgramData\MyApp\database.db'
    }
} | ConvertTo-Json -Depth 3 -Compress

$result = dsc resource test -r Microsoft.Windows/Registry -i $verify
$result | ConvertFrom-Json | Select-Object -ExpandProperty inDesiredState

In the above snippet, we transform the result into rich PowerShell objects, allowing us to search through the properties. We know that the inDesiredState tells us if the system is in its desired state. Because you've run the set, this result should be True.

Key takeaways

Before you proceed further in the course, remember the following concepts:

• Use dsc resource list to discover resources on your system.
• Use dsc resource schema to understand resource properties.
• Use dsc resource get to check the current state without making changes.
• Use dsc resource test to verify if the current state matches the desired state.
• Use dsc resource set to apply the desired state.

Always pay attention to what data types are expected for the properties.

Wrap up

You now understand how to work with individual resources. The skills you've learned here matter. Discovering schemas. Understanding properties. Using the dsc resource command. These form the foundation. Everything you do with dsc builds on this.

Before you finish up this module, it's time to practice and explore in the next lesson.