The example workflow

At this point, a simple example of the workflow you will use will be helpful to explain what we just covered. We will first create an example DSC configuration file. Then, we will compile it to an MOF file and show an example execution using the push deployment model.

A short note about composing configuration files: if you use the built-in PowerShell Integrated Script Environment (ISE), then you will have IntelliSense provided as you type. This is useful as you start learning; the pop-up information can help you as you type things without having to look back at the documentation. The PowerShell ISE also provides on-demand syntax checking and will look for errors as you type.

The following text would be saved as a TestExample.ps1 file. You will notice that this is a standalone file and contains no configuration data. Let's look at the following code snippet, which is a complete example of a DSC configuration file:

    # First we declare the configuration
    Configuration TestExample
    {
      # Then we declare the node we are targeting
      Node "localhost"
      {
        # Then we declare the action we want to perform
        Log ImportantMessage
        {
          Message = "This has done something important"
        }
      }
    }
    # Compile the Configuration function
    TestExample

For the sake of simplicity, we have saved more advanced topics such as this for Chapter 3, DSC Configuration Files.

We can see the Configuration keyword, which holds all the node statements and DSC resources statements. Then, the Node keyword is used to declare the target node we are operating on. This can either be hardcoded like in the example, or it can be passed in using the configuration data. And finally, the resource declaration for the action we want to take is added. In this example, we will output a message to the DSC event log when this is run on the localhost.

We use the term keyword here to describe Configuration and Node. This is slightly inaccurate, as the actual definitions of Configuration and Node are PowerShell functions in the PSDesiredStateConfiguration module. PowerShell functions can also be defined as cmdlets. This interchangeability of terms here is partly due to PowerShell's naming flexibility and partly due to informal conventions. It's sometimes a hot topic of contention. For the purposes of this book, substitute your preferred word here.

To compile this DSC configuration file into an MOF, we execute the following script from the PowerShell console:

    PS C:\Examples> .\TestExample.ps1
    
        Directory: C:\Examples\TestExample
    
    Mode                LastWriteTime     Length Name
    ----                -------------     ------ ----
    -a---         5/20/2015   7:28 PM       1136 localhost.mof

As we can see from the result, compiling the configuration file to an MOF resulted in a folder with the name of the configuration block we just created and with one file called the localhost.mof file.

Let's examine the following snippet:

    /*
    @TargetNode='localhost'
    @GeneratedBy=James
    @GenerationDate=05/20/2015 19:28:50
    @GenerationHost=BLUEBOX
    */
    
    instance of MSFT_LogResource as $MSFT_LogResource1ref
    {
    SourceInfo = "C:\\Examples\\TestExample.ps1::8::9::Log";
     ModuleName = "PSDesiredStateConfiguration";
     ModuleVersion = "1.0";
     ResourceID = "[Log]ImportantMessage";
     Message = "This has done something important";
    
    };
    
    instance of OMI_ConfigurationDocument
    {
     Version="1.0.0";
     Author="James";
     GenerationDate="05/20/2015 19:28:50";
     GenerationHost="BLUEBOX";
    };

We can see from this MOF that not only do we programmatically state the intent of this configuration (log a message), but we also note the computer it was compiled on as well as the user that did it. This metadata is used by the DSC engine when applying configurations and reporting statuses back to a pull server.

Then, we execute this configuration on a target node using the push deployment model by calling the Start-DscConfiguration cmdlet :

    PS C:\Examples> Start-DscConfiguration -Path C:\Examples\TestExample -Wait -Verbose
    VERBOSE: Perform operation 'Invoke CimMethod' with following parameters, ''methodName' =
    SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = 
    root/Microsoft/Windows/DesiredStateConfiguration'.
    VERBOSE: An LCM method call arrived from computer BLUEBOX with user sid ************.
    VERBOSE: [BLUEBOX]: LCM:  [ Start  Set      ]
    VERBOSE: [BLUEBOX]: LCM:  [ Start  Resource ]  [[Log]ImportantMessage]
    VERBOSE: [BLUEBOX]: LCM:  [ Start  Test     ]  [[Log]ImportantMessage]
    VERBOSE: [BLUEBOX]: LCM:  [ End    Test     ]  [[Log]ImportantMessage]  in 0.0000 seconds.
    VERBOSE: [BLUEBOX]: LCM:  [ Start  Set      ]  [[Log]ImportantMessage]
    VERBOSE: [BLUEBOX]:                            [[Log]ImportantMessage] This has done something important
    VERBOSE: [BLUEBOX]: LCM:  [ End    Set      ]  [[Log]ImportantMessage]  in 0.0000 seconds.
    VERBOSE: [BLUEBOX]: LCM:  [ End    Resource ]  [[Log]ImportantMessage]
    VERBOSE: [BLUEBOX]: LCM:  [ End    Set      ]    in  0.3162 seconds.
    VERBOSE: Operation 'Invoke CimMethod' complete.
    VERBOSE: Time taken for configuration job to complete is 0.36 seconds

Notice the logging here. We used the Verbose parameter, so we see listed before us every step that DSC took. Each line represents an action DSC is executing, and each has a Start and End word in it, signifying the start and end of each execution even though an execution may span multiple lines. We will get into how to sort and use these logs more when we address troubleshooting DSC configurations later in this book.

Each INFO, VERBOSE, DEBUG, or ERROR parameter is written both to the console in front of us and also to the DSC event log. Everything done is logged for auditing and historical purposes. An important thing to note is that while everything is logged, not everything is logged to the same place. There are several DSC event logs: Microsoft-Windows-DSC/Operational, Microsoft-Windows-DSC/Analytical, and Microsoft-Windows-DSC/Debug. However, only the Microsoft-Windows-DSC/Operational event log is logged to by default; you have to enable the Microsoft-Windows-DSC/Analytical and Microsoft-Windows-DSC/Debug event log in order to see any events logged there. Any verbose messages are logged in Microsoft-Windows-DSC/Analytical, so beware if you use the Log DSC resource extensively and intend to find those messages in the logs.