DSC Resources

Overview

DSC Resources provide a standardized interface for managing the settings of a system. A DSC Resource defines properties you can manage and contains the PowerShell code that Invoke-DscResource calls to "make it so."

A DSC Resource can model something as generic as a file or as specific as an IIS server setting. Groups of related DSC Resources are combined into PowerShell modules. Modules provide a portable, versioned package for DSC Resources and include metadata and documentation about them.

Every DSC Resource has a schema that determines the syntax needed to use the DSC Resource with Invoke-DscResource or in a Configuration. A DSC Resource's schema is defined in the following ways:

• <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.
• Schema.Mof file: MOF-based DSC Resources define their schema in a schema.mof file, using Managed Object Format.

To retrieve the syntax for a DSC Resource, use the Get-DSCResource cmdlet with the Syntax parameter. This is like using Get-Command with the Syntax parameter to get cmdlet syntax. The output shows the template used for a DSC Resource block in a DSC Configuration.

Get-DscResource -Syntax Service

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

Like cmdlet syntax, the keys in square brackets are optional. The types specify the data type each key expects.

To ensure that the Spooler service is running:

$SharedDscParameters = @{
    Name = 'Service'
    ModuleName = 'PSDscResources'
    Property = @{
        Name  = 'Spooler'
        State = 'Running'
    }
}
$TestResult = Invoke-DscResource -Method Test @SharedDscParameters
if ($TestResult.InDesiredState) {
    Write-Host -ForegroundColor Cyan -Object 'Already in desired state.'
} else {
    Write-Host -ForegroundColor Magenta -Object 'Enforcing desired state.'
    Invoke-DscResource -Method Set @SharedDscParameters
}

The $SharedDscParameters variable is a hash table containing the parameters used when calling the Test and Set methods of the resource with Invoke-DscResource. The first call to Invoke-DscResource uses the Test method to verify whether the Spooler service is running and stores the result in the $TestResult variable.

The next step depends on whether the service is already in the desired state. It's best practice to always verify desired state before enforcing and to only call the Set method when required. In the example, the script writes a message to the console about whether the DSC Resource is in the desired state. Then, if the service isn't running, it calls Invoke-DscResource with the Set method to enforce the desired state.