Edit

DSC Resources

  • Article

Applies to Windows PowerShell 4.0 and up.

Overview

Desired State Configuration (DSC) Resources provide the building blocks for a DSC configuration. A resource exposes properties that can be configured (schema) and contains the PowerShell script functions that the Local Configuration Manager (LCM) calls to "make it so".

A resource can model something as generic as a file or as specific as an IIS server setting. Groups of like resources are combined in to a DSC Module, which organizes all the required files in to a structure that is portable and includes metadata to identify how the resources are intended to be used.

Each resource has a *schema that determines the syntax needed to use the resource in a Configuration. A resource's schema can be defined in the following ways:

  • Schema.Mof file: Most resources define their schema in a schema.mof file, using Managed Object Format.
  • <Resource Name>.schema.psm1 file: Composite Resources define their schema in a <ResourceName>.schema.psm1 file using a Parameter Block.
  • <Resource Name>.psm1 file: Class based DSC resources define their schema in the class definition. Syntax items are denoted as Class properties. For more information, see about_Classes.

To retrieve the syntax for a DSC resource, use the Get-DSCResource cmdlet with the Syntax parameter. This usage is similar to using Get-Command with the Syntax parameter to get cmdlet syntax. The output you see will show the template used for a resource block for the resource you specify.

Get-DscResource -Syntax Service

The output you see should be similar to the output below, though this resource's syntax could change in the future. Like cmdlet syntax, the keys seen in square brackets, are optional. The types specify the type of data each key expects.

Note

The Ensure key is optional because it defaults to "Present".

Service [String] #ResourceName
{
    Name = [string]
    [BuiltInAccount = [string]{ LocalService | LocalSystem | NetworkService }]
    [Credential = [PSCredential]]
    [Dependencies = [string[]]]
    [DependsOn = [string[]]]
    [Description = [string]]
    [DisplayName = [string]]
    [Ensure = [string]{ Absent | Present }]
    [Path = [string]]
    [PsDscRunAsCredential = [PSCredential]]
    [StartupType = [string]{ Automatic | Disabled | Manual }]
    [State = [string]{ Running | Stopped }]
}

Note

In PowerShell versions below 7.0, Get-DscResource does not find Class based DSC resources.

Inside a Configuration, a Service resource block might look like this to Ensure that the Spooler service is running.

Note

Before using a resource in a Configuration, you must import it using Import-DSCResource.

Configuration TestConfig
{
    # It is best practice to always directly import resources, even if the
    # resource is a built-in resource.
    Import-DSCResource -Name Service
    Node localhost
    {
        # The name of this resource block, can be anything you choose, as l
        # ong as it is of type [String] as indicated by the schema.
        Service "Spooler - Running"
        {
            Name = "Spooler"
            State = "Running"
        }
    }
}

Configurations can contain multiple instances of the same resource type. Each instance must be uniquely named. In the following example, a second Service resource block is added to configure the "DHCP" service.

Configuration TestConfig
{
    # It is best practice to always directly import resources, even if the
    # resource is a built-in resource.
    Import-DSCResource -Name Service
    Node localhost
    {
        # The name of this resource block, can be anything you choose, as
        # long as it is of type [String] as indicated by the schema.
        Service "Spooler - Running"
        {
            Name = "Spooler"
            State = "Running"
        }

        # To configure a second service resource block, add another Service
        # resource block and use a unique name.
        Service "DHCP - Running"
        {
            Name = "DHCP"
            State = "Running"
        }
    }
}

Note

Beginning in PowerShell 5.0, IntelliSense was added for DSC. This new feature allows you to use TAB and Ctr+Space to auto-complete key names.

Resource IntelliSense using Tab Completion

Types of resources

Windows comes with built in resources and Linux has OS specific resources. There are resources for cross-node dependencies, package management resources, as well as community owned and maintained resources. You can use the above steps to determine the syntax of these resources and how to use them. The pages that serve these resources have been archived under Reference.

Windows built-in resources

Cross-Node dependency resources

Package Management resources

Linux resources