Powershell Desired State Configuration(DSC):How to enforce a consistency check?

A few month ago I started digging into Powershell Desired State Configuration (DSC). I really had a steep learning curve. The outcome could be found here:

• Pull server
• Configure LCM on nodes
• Create and publish MOF files

In terms of scripts I published some, which helps you to stay on top of the whole topic:

• Get-NodeInformation.ps1
• Set-DSCLCMforPullServer.ps1
• New-DSCConfigsFromFiles.ps1

Today I’m writing about the topic how you can enforce/trigger a consistency check on your nodes. Besides this also something you should know when you are using the built-in DSC File Resource.

Trigger consistency check

If you want to trigger a consistency check you have several options. But before I explain some of those you need to understand where the DSC engine lives:

DSC runs in the process WmiPrvSE.exe. It also caches data in this process. That means when you are writing a DSC resource and test different versions you want to end those processes in order to have the latest version of your resource running. More info could be found in this article.

Scheduled Task

There are two scheduled task related to Desired State Configuration. You can find them in “\Microsoft\Windows\Desired State Configuration\”:

Get-ScheduledTask -TaskPath "\Microsoft\Windows\Desired State Configuration\" | fl

or in the GUI

You can trigger the check by running the scheduled task named Consistency.

Doing so you can see only that something happens when you examine the event log in Microsoft-Windows-Desired State Configuration/Operational.

Powershell Script

Besides the scheduled task you can also trigger the check using Invoke-CimMethod. When you look into the scheduled task you will find the Cmdlet and all used parameters:

Invoke-CimMethod -Namespace root/Microsoft/Windows/DesiredStateConfiguration -Cl MSFT_DSCLocalConfigurationManager -Method PerformRequiredConfigurationChecks -Arguments @{Flags = [System.UInt32]1}

If you want to see what’s going on you can use this and add the -Verbose switch:

Invoke-CimMethod -Namespace root/Microsoft/Windows/DesiredStateConfiguration -Cl MSFT_DSCLocalConfigurationManager -Method PerformRequiredConfigurationChecks -Arguments @{Flags = [System.UInt32]1} -Verbose

You can also run it against a remote computer by using the switch -ComputerName or -CimSession. This depends on your needs. To me the main difference is that you can define more properties in a CimSession using the Cmdlet New-CimSession.

Kill the correct WmiPrvSE process

Both options mentioned above will trigger the consistency check. But you may get an error like this:

This is caused by the fact that currently a check is already running. There are situations where you might want to stop this check or as mentioned before you are writing and testing a new DSC resource. But which process is the correct one? There could be multiple instances of the process WmiPrvSE.

As usual there is a solution for this:

###
### find the process that is hosting the DSC engine
###
$dscProcessID = Get-WmiObject msft_providers | 
Where-Object {$_.provider -like 'dsccore'} | 
Select-Object -ExpandProperty HostProcessIdentifier 

###
### Stop the process
###
Get-Process -Id $dscProcessID | Stop-Process

Note:This was taken from the article mentioned above.

Cache DSC File Resource

You can use the built-in DSC File Resource to copy data to your target nodes. A simple example would be something like this:

Configuration DemoConfig
{
    Node $AllNodes.NodeName
    {
        #copy sources
        File Sources
        {
            Ensure = 'Present'
            Force = $True
            Recurse = $True
            SourcePath = '\\FABPULLSRV.fabrikam.local\Sources\'
            Type = 'Directory'
            DestinationPath =  'C:\Sources\'
            MatchSource = $True
            Credential = $ShellCreds
        }
    }
}

This will copy the folder Sources and all subfolders. The important part is to set the property MatchSource to $True so each time you add files or folders to the root folder Sources, the engine will check each consistency check the directories.

Note: It will not use a cache! This might have an impact when you have a lot of files and folders to copy.

When you set the property to $False, the engine will create a cache. You can find them here:

Get-ChildItem $env:Windir\System32\Configuration\BuiltinProvCache -Filter *.cache -Recurse

The drawback now is that new files and folders will not be copied. Only when a node retrieves the configuration the very first time:

“If set to the default value of $false, then any files on the source (say, files A, B, and C) will be added to the destination the first time the configuration is applied. If a new file (D) is added to the source, it will not be added to the destination, even when the configuration is re-applied later. If the value is $true, then each time the configuration is applied, new files subsequently found on the source (such as file D in this example) are added to the destination.”

If you are using the cache mechanism and want to make sure newly added files and folders get copied, you need to remove those caches

Get-ChildItem $env:Windir\System32\Configuration\BuiltinProvCache -Filter *.cache -Recurse | Remove-Item -Force

Enforce-DSCConfiguration

In order to simplify the methodes mentioned above, I wrote a script, which could be downloaded here.

Parameter	Description
Computername	A single computer or an array of computernames. This parameter supports pipeline.
Credential	Credential to be used to connect to the remote computer
KillWmiPrvSE	This will try to stop the WmiPrvSE process, which is responsible for the DSC engine, before it triggers the consistency check
ClearCache	This will delete all cache files found in the subfolders of $env:Windir\System32\Configuration\BuiltinProvCache, before it triggers the consistency check
MultiThread	By default multiple computers will be processed sequential. Use this switch to process all computers in parallel.
OperationTimeoutSec	The time until the command Invoke-CimMethod runs into a timeout against the remote computer.
Threads	If MultiThread is used this defines the maximum number of parallel threads.
MaxResultTime	If MultiThread is used this defines the time a check must complete. Default is 240.

The script supports the common parameters like -Verbose. To enforce the consistency check against multiple computers you can run the following command:

.\Enforce-DSCConfiguration.ps1 -Computername fabex01,fabex02 -Verbose

To use multithreading, kill the WmiPrvSE process and clear the cache use the following:

.\Enforce-DSCConfiguration.ps1 -Computername fabex01,fabex02 -Verbose -MultiThread -KillWmiPrvSE -ClearCache

Pipelining objects into the script:

Get-ADComputer -Filter { msExchCapabilityIdentifiers -eq '1'} | select DNSHostName | .\Enforce-DSCConfiguration.ps1 -Verbose -MultiThread

I hope this post will help you to stay on top of your infrastructure! Feedback is always welcome!