PowerShell: Desired State Configuration – Getting started.


By now most people will have heard about the Windows PowerShell Desired State Configuration(DSC), the incredibly powerful configuration management platform that comes with PowerShell 4.0. This post will describe the feature in its most basic form and assume you’re new to the topic(or have been living under a rock). This should give you an overview and basic understanding of how PowerShell DSC fundamentally works. From then, I’ll post further and share how I’ve been using DSC to control my Lab environments.

What’s it all about then?

DSC is a management platform in Windows PowerShell that essentially just runs PowerShell scripts in a very clever manner, allowing you to push a configuration to a computer. You can do pretty much anything in PowerShell and as DSC runs on top of PowerShell you have even more power with DSC. Also, the amazing thing is you don’t even need to learn scripting to use it, you just edit a text file.

PowerShell DSC is really cool and the next big thing in the world of deployment. Moving forward I can see DSC replacing (or augmenting) Group Policy, building local and cloud based servers/hydration kits, removing malware/deploying software, etc.

Today’s post will demonstrate how to use PowerShell DSC in ‘Push’ mode by authoring a DSC Configuration using ‘Declarative Syntax’ to create a text file with the words “Hello World” and then ensure that the file and its content will remain compliant.

The same basic process will be used in further posts to build an entire server and domain PoC testlab. The power of PowerShell Desired State Configuration(DSC) is practically limitless.

So is there a script coming any time soon?

Indeed! Enough talk, here’s the Hello World Script. It’s written in DSC declarative syntax and uses a DSC Resource called File to create a text file.

configuration HelloWorld {
 param ()
 Node Localhost 
   # Create a Test File
   File CreateTestFile
     Ensure          = "Present"
     DestinationPath = "C:\ScriptimusExMachina\example.txt"
     Contents        = "Hello World."
     Type            = "File"

# Create MOF Files
HelloWorld -OutputPath C:\ScriptimusExMachina\HelloWorld

# Start DSC Configuration
Start-DscConfiguration -Path C:\ScriptimusExMachina\HelloWorld -ComputerName Localhost -Verbose -Wait

I still don’t get it?

What we’re trying to do here is generate a folder that contains a configuration file in MOF format.

Erm , I’m still not getting it. This MOFF fellow, is this the guy Darth Vader choked or the old guy played by Peter Cushing?

Grand Moff Tarkin. (Not to be confused with a MOF file in PowerShell DSC)

Erm, neither. A MOF is just a text file in Managed Object Format (MOF). We’re going to use this MOF file to apply a configuration to our host computer. We don’t actually need to learn how to write a complex MOF file. We’re going to use the Configuration in the script above to create the MOF file for us.

For demo purposes we paste the Configuration into the console.


The Configuration works like a Function and has 3 parameters InstanceName, OutputPath and ConfigurationData. Ed Wilson (The Scripting Guy) does a great job of describing these here.


We now run our HelloWorld Configuration in its simplest form.

HelloWorld -OutputPath C:\ScriptimusExMachina\HelloWorld


As you can see, it creates a folder with the same name as our Configuration with a .MOF file inside. The MOF filename is the same as the target hostname specified in the Hello world configuration earlier. If you had multiple hostnames in your configuration then you would have one for each host.


What this means is that when the configuration is applied, each MOF (one for each machine) file will be applied. In this case however, we’re just using Localhost.

Just do it already!

We use this command to start the DSC configuration.

Start-DscConfiguration -Path C:\ScriptimusExMachina\HelloWorld -ComputerName Localhost -Verbose -Wait

The Configuration is applied using the Start-DscConfiguration cmdlet, pointing it to the folder path of our MOF files. If you had multiple hosts configured then you could just apply one by name by using the ComputerName parameter as shown in the example. Using the Verbose and Wait Parameters causes DSC to output its data in real time as shown below.


Walking through the syntax used in the script earlier. First we ensure that our configuration is present. We could use Absent to delete a file or folder.

Ensure          = "Present"

We specify the name and path of the file that we’re going to create. The type could also be a folder instead.

DestinationPath = "C:\ScriptimusExMachina\example.txt"
Type            = "File"

Here we ensure that its contents are a specific string.

Contents        = "Hello World."

Looking in the folder, we have a new text file with the desired content.


Now that’s PowerShell DSC in its simplest form.

We can test that our Configuration is compliant using the Test-DSCConfiguration CmdLet. This will return a Boolean response.


Watch what happens when I change the content of the file.


Now I can use Restore-DscConfiguration to re-apply the configuration.


This is made possible because the MOF file that was applied last has been copied to C:\Windows\System32\Configuration\Current.mof. You could use Restore-DscConfiguration to re-apply the configuration without the source.Configuration

By using the source I could also re-apply the configuration by using the Start-DscConfiguration cmdlet again.


You’ll see that this time, by not using the Verbose and Wait Parameters that DSC is showing me that the process is running as background Job.

You can retrieve the job as usual.


Finally, you can use the Get-DscConfiguration cmdlet to view the current configuration.


In future posts I’ll be discussing more complex configurations so keep reading.


About Andrew Barnes

A Scripting and Deployment Specialist.
This entry was posted in Desired State Configuration, PowerShell and tagged , . Bookmark the permalink.

2 Responses to PowerShell: Desired State Configuration – Getting started.

  1. CLParker says:

    Nice One! Good to see you posting again man! Keep up the good work! Powershell Por Vida!


  2. Pingback: Creating my very first DSC Resource | pshirwin

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s