Working with the Desired State Configuration Feature (Part 4)

If you would like to read the other parts in this article series please go to:

In the previous article in this series, I showed you how to create an example script that was designed to make sure that the Hyper-V role was installed onto a server named Lab4. In this article, I want to show you how to use the script that we created previously. After that I want to come back to the script and show you how to adapt it to make it more useful.

For the sake of reference, here is the script that we built in the previous article:

Configuration PoseyConfig
{
                Node “Lab4”
                                {
                                WindowsFeature HyperVExample
                                                {
                                                Ensure = “Present”
                                                Name = “Hyper-V”                                                }
                                }
}

The first thing that we need to do is to create a place on the server for our script to reside. For the purposes of this article, I am going to place the script in a folder named C:\DSC. I created the folder by opening PowerShell and entering the following commands:

CD\

MD DSC

You can see what this looks like in Figure A.

Figure A: I have created a folder named DSC.

Now, we need to copy the script to the folder that was just created. The easiest way to accomplish this is to type (or copy and paste) the script into Notepad and then save the Notepad document into the C:\DSC folder.

There are three important things that you must keep in mind as you create the script. First of all, if you copy and paste my script then you will need to slightly modify the script. Remember that Lab4 (which is referenced in the script) is the name of one of my lab servers. You will need to change this to match the name of your own server. As an alternative to specifying a server name, you can use localhost to make the script machine independent.

The second important thing to remember is that the script outlined above is really just a function. A function doesn’t do anything by itself. You can only invoke a function by calling it. The easiest way to accomplish this is to append the function name to the end of the script. Since my function name is PoseyConfig for instance, I would append PoseyConfig to the end of the script. The complete script would look like this:

Configuration PoseyConfig
{
                Node “Lab4”
                                {
                                WindowsFeature HyperVExample
                                                {
                                                Ensure = “Present”
                                                Name = “Hyper-V”
                                                }
                                }
}
PoseyConfig

The third thing that you need to know about the script is that you will need to save the file using the .PS1 extension. This identifies the code as a PowerShell script. I will be naming the file PoseyConfig.PS1.

Once you have created the script, you can go ahead and execute the script. In doing so, you will have to reference the name of the script. In my case, the script is named PoseyConfig.PS1. Therefore, I executed the script by using the following commands:

CD\

CD DSC

./PoseyConfig.ps1

You can see what this looks like in Figure B.

Figure B: This is what it looks like when you execute the script.

If you happen to receive an error message when running the script, it could be related to a restrictive execution policy. You can remove execution policy restrictions by entering the following command:

Set-ExecutionPolicy Unrestricted

Just keep in mind that execution policies exist for your protection, so it is a good idea to set the execution policy to Restricted or to RemoteSigned when you are done.

As you can see in the figure above, the script has created a .MOF file. The .MOF file is named Lab4.MOF and it exists in the C:\DSC\PoseyConfig folder.

So as I explained early on in this series, the script that we created really doesn’t do anything by itself. The script’s job is to generate a .MOF file, not to enforce a desired state. We have to use the .MOF file to generate a desired state.

A MOF file is really nothing more than a text file that contains configuration information. As a matter of fact, the .MOF file that we created can be open in Notepad. You can see the contents of the .MOF file in Figure C.

Figure C: This is what the .MOF file looks like.

Of course this brings up an interesting question. If the .MOF file is really just a text file then why do we have to generate it using a PowerShell configuration script? Why can’t we just build a .MOF file manually? It is actually possible to manually construct a .MOF file, but it is usually easier to use a PowerShell function to generate a .MOF file than it is to create a .MOF file from scratch. I realize that the file shown above isn’t very complicated, but remember that we are using the simplest possible Desired State Configuration. Most real world desired state configurations are far more complex and therefore generate much longer and more complicated .MOF files.

So now that we have a .MOF file, what do we do with it? We can invoke the .MOF file by using a PowerShell cmdlet called Start-DscConfiguration. This cmdlet reads the .MOF file and then determines which PowerShell cmdlets need to be run in order to achieve the configuration goals. For example, the script that we have been using is designed to test for the presence of the Hyper-V role. As such, one of the cmdlets that is run as a part of the testing process is Get-Windows Feature.

With that said, let’s go ahead and put our .MOF file to work. To do so, you will need to invoke the Start-DscConfiguration command from the C:\DSC folder that we created earlier. The command that we will be using is:

Start=DscConfiguration –Wait –Verbose –Path .\PoseyConfig

The –Wait parameter tells Windows that you want to run the command interactively. The –Verbose switch tells Windows that you want verbose output. That way, you can see what is really going on with the command.

You will also notice that we are using the –Path switch followed by .\PoseyConfig. The reason for this is that Windows placed my .MOF file into a folder named PoseyConfig that exists as a child of the DSC folder. The full path is C:\DSC\PoseyConfig.

You can see what happens when we run the command in Figure D. Because we ran the command in verbose mode, you can see the Get-WindowsFeature cmdlet that was used to verify that Hyper-V is installed on the server. You can also see that the command took 15.041 seconds to complete.

Figure D: Here is what happens when we run the command.

I realize that some of you might be wondering what happens if we run the command without verbose mode. You can see that result in Figure E.

Figure E: Here is the command without the –Verbose parameter being used.

As you can see in the figure above, there is no visible output without the Verbose parameter.

Conclusion

In the next article in this series, I want to do a couple of things. First, I am going to show you what happens when you run the script against a server that does not have the required role installed. Next, I want to spend some time showing you some other things that you can do with the script. That way, you will be able to build your script out to really achieve your desired configurations.

If you would like to read the other parts in this article series please go to: