Examples

Contents

1. Overview
2. Generate manifests for one module
3. Generate manifests for multiple modules
4. Override schema descriptions
5. Add JSON schema constraints
6. Generate read-only properties
7. Publish manifests with a module

Overview

These examples show common authoring tasks for PowerShell class-based DSC resources and Microsoft DSC v3 manifests. Adapted resource manifests provide dsc.exe with resource metadata and schema context before execution, which improves discovery speed and enables commands such as dsc resource schema --resource <resource-type>.

Generate manifests for one module

Generate adapted resource manifests from a module manifest and write one JSON file per resource:

New-DscAdaptedResourceManifest -Path ./MyModule/MyModule.psd1 |
    ForEach-Object {
        $fileName = '{0}.dsc.adaptedResource.json' -f ($_.Type -replace '/', '.')
        $_.ToJson() | Set-Content -Path $fileName
    }

Generate manifests for multiple modules

Discover module manifests below a folder and generate adapted resource manifests for every class-based DSC resource:

Get-ChildItem -Path ./Modules -Filter *.psd1 -Recurse |
    New-DscAdaptedResourceManifest |
    New-DscResourceManifest |
    ForEach-Object {
        $_.ToJson() | Set-Content -Path ./resources.dsc.manifests.json
    }

Override schema descriptions

Use New-DscPropertyOverride and Update-DscAdaptedResourceManifest when the generated schema needs more specific text:

$overrides = @(
    New-DscPropertyOverride -Name 'Name' `
        -Description 'The unique name of the resource instance.'
)

New-DscAdaptedResourceManifest -Path ./MyModule/MyModule.psd1 |
    Update-DscAdaptedResourceManifest -PropertyOverride $overrides |
    ForEach-Object {
        $_.ToJson() | Set-Content -Path ./MyResource.dsc.adaptedResource.json
    }

Add JSON schema constraints

Add JSON schema keywords that cannot be inferred from PowerShell type metadata:

$override = New-DscPropertyOverride -Name 'Count' -JsonSchema @{
    minimum = 0
    maximum = 100
    default = 1
}

$manifest = New-DscAdaptedResourceManifest -Path ./MyModule/MyModule.psd1
$manifest = $manifest | Update-DscAdaptedResourceManifest -PropertyOverride $override
$manifest.ToJson() | Set-Content -Path ./MyResource.dsc.adaptedResource.json

Generate read-only properties

Mark a property with [DscProperty(NotConfigurable)] in the class-based DSC resource:

[DscProperty(NotConfigurable)]
[string] $Status

DscResource.Authoring emits the property as read-only in the embedded JSON schema:

{
  "Status": {
    "type": "string",
    "title": "Status",
    "readOnly": true,
    "description": "The current status returned by the resource."
  }
}

Publish manifests with a module

Place adapted resource manifest files in the module that you publish to PowerShell Gallery. The PowerShell discovery extension searches paths from $env:PSModulePath for DSC manifest files. When the module is installed, DSC can discover those manifests from the installed module path.

Example module layout:

ExampleModule/
    ExampleModule.psd1
    ExampleModule.psm1
    ExampleModule.ExampleResource.dsc.adaptedResource.json

After installation, DSC can use the manifest metadata for schema lookup:

dsc resource schema --resource ExampleModule/ExampleResource