NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

Introduction

The xDSCResourceDesigner module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a tool to author PowerShell DSC Resources and produced by the PowerShell Team.This tool makes writing resources a breeze and ensure that all the rules which a DSC resource must conform to are met.

All of the functions/cmdlets in the Resource Designer Tool are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xDSCResourceDesigner stands for experimental, which means that this tool will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xDSCResourceDesigner module, feel free. When modifying, please update the module name and the function names (instructions below). As specified in the license, you may copy or modify this tool as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xDSCResourceDesigner module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-Module -ListAvailable to see that xDSCResourceDesigner is among the modules listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xDSCResourceDesigner module exposes 6 functions: New-xDscResourceProperty, New-xDscResource, Update-xDscResource, Test-xDscResource, Test-xDscSchema and Import-xDscSchema . These uses of these functions are given below.

Details

xDSCResourceDesigner module exposes the following functions:

  • New-xDscResourceProperty:                      For creating a property for the resource
  • New-xDscResource:        for creating the actual resource containing the schema and module skeleton
  • Update-xDscResource: for updating an existing resource with new properties
  • Test-xDscResource:               for testing whether an existing resource conforms to the rules required by DSC
  • Test-xDscSchema:               for testing whether an existing schema (schema.mof) conforms to the rules required by DSC
  • Import-xDscSchema:               for getting the properties in a schema returned as a hashtable

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xDSCResourceDesigner becomes cDSCResourceDesigner)
    • Function name (ex: New-xDscResource becomes New-cDscResource)
  2. Update module and metadata information in the module manifest
  3. Update any scripts that uses this module

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "xDSCResourceDesigner" or "DSCResourceDesigner"). If the next version of Windows Server ships with a "DSCResourceDesigner" module, we don't want to break any scripts that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.0.0

  • Initial release with the following module
    • xDSCResourceDesigner

1.1.1.1

  • Metadata updates.

1.1.2

  • Ignore -WhatIf and -Confirm internal parameters to suppress false errors when Set-TargetResource declares [CmdletBinding(SupportsShouldProcess=$true)]

 

 

Example: Create a Sample DSC ADUser Resource

This example creates a ADUser DSC resource.

PowerShell
Edit|Remove
<# 
Create a ADUser DSC Resource with following properties 
UserName: Name of the ADUser. This is a  key property for the resource that uniquely identify an instance. 
Password: Password of the user. Can be used to update an existing user password. 
DomainAdminstratorCredential: Credential of the Domain Administrator in which user account will be created. 
Ensure: Whether an user account should be created or deleted. This can only take two values: ‘Present’ and ‘Absent’. 
#> 
 
$UserName = New-xDscResourceProperty -Name UserName -Type String -Attribute Key 
$Password = New-xDscResourceProperty -Name Password -Type PSCredential -Attribute Write  
$DomainCredential = New-xDscResourceProperty -Name DomainAdministratorCredential -Type PSCredential -Attribute Write  
$Ensure = New-xDscResourceProperty -Name Ensure -Type String -Attribute Write -ValidateSet "Present""Absent"  
 
#Now create the resource 
New-xDscResource -Name Contoso_cADUser -Property $UserName$Password$DomainCredential$Ensure  -Path 'C:\Program Files\WindowsPowerShell\Modules\xActiveDirectory'   

Example: Test an Incorrect Resource Definition

This example will use Test-xDscSchema function to check if the resource definition is correct or not
PowerShell
Edit|Remove
<# 
Suppose you have the following schema (named buggy.schema.mof): 
[ClassVersion("1.0.0.0"), FriendlyName("")] 
class Contoso_cADUser : OMI_BaseResource 
{ 
       [Key] String UserName; 
       [Write, ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure; 
}; 
#> 
 
# This reports that the schema is buggy. 
Test-xDscSchema -Path .\buggy.schema.mof

Example: Updates an Existing Resource

This example will use Update-xDscResource function to update an already existing resource properties
PowerShell
Edit|Remove
#Assume, you want to add an additional property called LastLogOn on existing Constoso_cADUser resource 
 
$lastLogOn = New-xDscResourceProperty -Name LastLogOn -Type Hashtable -Attribute Read -Description "Returns the user last log on time"  
 
#Update the existing resource 
Update-xDscResource -Name 'Contoso_cADUser' -Property $UserName$Password$DomainCredential$Ensure$lastLogOn -Force