This post is a continuation of my previous post on Windows PowerShell Desired State Configuration. In that post, I gave you the architectural overview of DSC. Today, we’ll take the next step and set up our lab environment.

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

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!

5 Comments
  1. Wessun007 6 years ago

    Hi there, I'm trying to run this cmd

    PS C:\> $gc = Get-DscResource -Name MSFT_xChrome ; $gc.Properties
    CheckResourceFound : The term 'MSFT_xChrome' is not recognized as the name of a Resource.
    At
    C:\Windows\system32\WindowsPowerShell\v1.0\Modules\PSDesiredStateConfiguration\PSDesiredStateConfiguration.ps
    char:13
    + CheckResourceFound $name $resources
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,CheckResourceFound

    but of course being a powershell novice it keeps erroring relating to theCheckResourceFound $name $resources

  2. Author

    Hi Wessun007. Did you verify that you have the xChrome module installed? If not, head over to the PowerShell Gallery (powershellgallery.org) and download it. There's the off chance that Microsoft renamed the resource as well. Finally, you can get rid of my "; $gc.Properties part and just run the first part of that command. The semicolon is a statement separator, and perhaps when you copied and pasted the code something went wonky. Let us know, Tim W.

  3. Michael 6 years ago

    I loved the MVA (Snover and Hemlick) PoSh sessions. However, the DSC sessions were confusing. Your walkthrough is what I needed.

    Thanks,

     

    Michael

    • Author

      We aim to please, Michael! Coincidentally,  I attended Jason's live DSC presentation at PowerShell Summit today. Thanks, Tim W.

  4. Pradip 4 years ago

    How to build Desired State Configuration (DSC) configuration for windows 7 and windows 10

Leave a reply

Please enclose code in pre tags

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2022

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account