PowerShell Desired State Configuration (DSC) – Part 2: Setup

• Author
• Recent Posts

Timothy Warner

Timothy Warner is a Microsoft Cloud and Datacenter Management Most Valuable Professional (MVP) who is based in Nashville, TN. Check out his Azure and Windows Server video training at Pluralsight, and feel free to reach out to Tim via Twitter.

Latest posts by Timothy Warner (see all)

• Install Ansible on Windows - Thu, Jul 20 2023
• Use Azure Bastion as a jump host for RDP and SSH - Tue, Apr 18 2023
• Azure Virtual Desktop: Getting started - Fri, Apr 14 2023

What we’re going to do

In my lab environment, I have two Windows Server 2012 R2 computers:

• nashdc1.company.pri: domain controller, DSC administration node
• rodc1.company.pri: member server, DSC target node

For our DSC proof of concept, we’ll use the xChrome DSC module and its MSFT xChrome resource to install and manage Google Chrome on a remote node (rodc1 in my lab).

We’ll test DSC enforcement after we deploy Chrome by uninstalling the software from rodc1 and verifying that DSC reinstalls Chrome with no user intervention.

Meeting the PowerShell requirements

Because Desired State Configuration was introduced in Windows PowerShell v4, all nodes that will participate in DSC must run at least that version. Tap into the $PSVersionTable automatic variable to check, as follows:

PS C:\> $PSVersionTable.PSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
4      0      -1     -1

Windows Server 2012 R2 and Windows 8.1 both have PowerShell v4 installed out of the box. You can install the Windows Management Framework (WMF) v4 on Windows Server 2008 R2 and Windows 7 computers if you need to.

You also need to make sure PowerShell remoting is enabled on all DSC nodes. Windows Server 2012 R2 does have remoting enabled by default, but you’ll need to manually enable remoting on Windows 8.1, Windows Server 2008 R2, and Windows 7 computers.

PS C:\>Enable-PSRemoting –SkipNetworkProfileCheck -Force

Note that neither Windows 7 nor Windows Server 2008 R2 support the –SkipNetworkProfileCheck switch; this is a useful switch to use when one of your system’s network adapters is associated with the Public location profile.

Downloading and installing the resources

The DSC commands are all contained in the PSDesiredStateConfiguration module:

PS C:\> Get-Command -Module PSDesiredStateConfiguration | Select-Object -Property CommandType, Name

CommandType     Name
-----------     ----
Function        Configuration
Function        Get-DscConfiguration
Function        Get-DscLocalConfigurationManager
Function        Get-DscResource
Function        New-DSCCheckSum
Function        Restore-DscConfiguration
Function        Test-DscConfiguration
Cmdlet          Set-DscLocalConfigurationManager
Cmdlet          Start-DscConfiguration

A DSC resource is a DSC managed element. Let’s retrieve a list of the default DSC resources in Windows Server 2012 R2 and Windows 8.1:

PS C:\> Get-DscResource | Select-Object -Property Name, Properties

Name                          Properties
----                          ----------
File                          {DestinationPath, Attributes, Checks...
Archive                       {Destination, Path, Checksum, Depend...
Environment                   {Name, DependsOn, Ensure, Path...}
Group                         {GroupName, Credential, DependsOn, D...
Log                           {Message, DependsOn}
Package                       {Name, Path, ProductId, Arguments...}
Registry                      {Key, ValueName, DependsOn, Ensure...}
Script                        {GetScript, SetScript, TestScript, C...
Service                       {Name, BuiltInAccount, Credential, D...
User                          {UserName, DependsOn, Description, D...
WindowsFeature                {Name, Credential, DependsOn, Ensure...
WindowsProcess                {Arguments, Path, Credential, Depend...

The names of the default DSC resources should give you a good idea as to what you can manage with DSC out of the box. For instance, we can use the File resource to, say, copy network resources to a local file system and ensure that the copied files remain in place.

The WindowsFeature resource is great for installing and enforcing Windows Server 2012 server roles and features, and so on.

The PowerShell team periodically releases additional DSC resource modules in what they call “waves.” You can download all the resources in waves 1 through 9 by visiting this TechNet Script Gallery page.

I’ll show you how to install downloaded resources in just a minute. In the meantime, you can run the following one-liner to filter the output to show only Script Gallery resources:

PS C:\> Get-DscResource | Where-Object { $_.name -like "x*" -or $_.name -like "MSFT*" } | Select-Object -Property Name | Format-Wide -Column 2

Wow—that’s a lot of functionality, right? Remember to unzip the additional DSC resources to the proper directory on all nodes (both authoring and target). In the following screenshot, you’ll see the contents of the xChrome resource and its Managed Object Format (MOF) source code:

DSC resources use the vendor-neutral MOF format.

Building your configuration script

The key to writing your DSC configuration script is understanding how to get at the properties of each resource. In this case study, we need the MSFT_xChrome resource module. Let’s create a variable and then tap into its Properties property:

PS C:\> $gc = Get-DscResource -Name MSFT_xChrome ; $gc.Properties

Name           PropertyType        IsMandatory      Values
----           ------------        -----------      ------
Language       [String]            False            {}
LocalPath      [String]            False            {}

The above output indicates that, to deploy Chrome, we need to specify (at the least) an interface language and a local directory path.

With PowerShell, there are always several ways to accomplish the same task. Let’s try this one-liner to get the full details of the File DSC resource’s properties:

PS C:\> Get-DscResource -name File | Select -ExpandProperty Properties

Name                     PropertyType      IsMandatory   Values
----                     ------------      -----------   ------
DestinationPath          [string]          True          {}
Attributes               [string[]]        False         {Archive, Hidden...
Checksum                 [string]          False         {CreatedDate...
Contents                 [string]          False         {}
Credential               [PSCredential]    False         {}
DependsOn                [string[]]        False         {}
Ensure                   [string]          False         {Absent, Present}
Force                    [bool]            False         {}
MatchSource              [bool]            False         {}
Recurse                  [bool]            False         {}
SourcePath               [string]          False         {}
Type                     [string]          False         {Directory, File}

Okay—it’s time to create the DSC configuration script. Start the Windows PowerShell ISE and save a new .ps1 script file named InstallGoogleChrome.ps1. Put the file in a new directory, C:\DSC.

Please study the following script and I’ll walk you through the most important lines.

Configuration InstallGoogleChrome {
	param (
    	[string[]]$MachineName = "localhost",
    	[Parameter(Mandatory)]$Language,
    	[Parameter(Mandatory)]$LocalPath
	)

	Import-DscResource -Module xChrome

	Node $MachineName {
		MSFT_xChrome chrome {
			Language = $Language
			LocalPath = $LocalPath
		}
	}
}

InstallGoogleChrome -MachineName "rodc1"  `
-Language "en" -LocalPath "C:\Windows\Temp\GoogleChromeStandaloneEnterprise.msi"

1. DSC configuration scripts use the Configuration container. Note that DSC configurations can’t have hyphens, which is weird to me because I’m accustomed to naming my functions using the standard format approvedverb-prefixsingularnoun.

3-5. These are input parameters. Two of them ($Language and $LocalPath) come directly from the MSFT_xChrome resource’s property list. I added $MachineName as a string array to make it easier to target more than one node at once.

8. Import-DscResource actually isn’t a cmdlet; it’s a special keyword that works only when you run it in the context of a Configuration data structure. Again, this usage is a bit wonky, and it frequently trips up DSC newcomers. At any rate, this import statement makes the xChrome properties available to our configuration.

10. The Node element is the data structure that contains our DSC directives. You can add directives from more than one resource; each one is placed in its own script block.

11. Specifically, xChrome is the name of the DSC module, and MSFT_xChrome refers to the resource. In this script block, we map our input parameters to resource directives.

18-19. This line invokes the new InstallGoogleChrome configuration on the authoring computer. You don’t have to add the invocation to the source script, but I like to add it so I can create my MOF file(s) simply by running the entire configuration file once. By the way, I used the backtick (`) line separator here to make the statement easier for you to read.

Generating MOF files

As you saw in lines 18 and 19 in our sample configuration script, we need to run our configuration file in order to generate the MOF files that perform the actual DSC configuration.

Note that I could have passed more than one computer name to the $MachineName variable because I created the parameter as a string array. For instance, if I had a text file named servers.txt that contained a list of server hostnames, I could re-run the script by using this line:

InstallGoogleChrome -MachineName (Get-Content -Path "c:\servers.txt") -Language "en" –LocalPath C:\Windows\Temp\GoogleChromeStandaloneEnterprise.msi"

The end result of running your configuration script is (a) a subdirectory of the current working directory with the same name as the script file name, and (b) one or more MOF files named after each target node.

PS C:\> C:\dsc\InstallGoogleChrome.ps1


    Directory: C:\InstallGoogleChrome


Mode                LastWriteTime     Length Name                                                               
----                -------------     ------ ----                                                               
-a---          2/6/2015   9:27 AM       3062 rodc1.mof

Next steps

We’ve set up our DSC authoring environment, created our configuration script, and generated a MOF file for our target node. In the next installment of this series, we’ll use Start-DscConfiguration to actually kick off the Desired State Configuration process. See you then!