Troubleshooting DSC
Applies To: Windows PowerShell 4.0, Windows PowerShell 5.1
This article provides troubleshooting instruction for common errors.
WinRM Dependency
Windows PowerShell Desired State Configuration (DSC) depends on WinRM. WinRM isn't enabled by
default on Windows Server 2008 R2 and Windows 7. Run Set-WSManQuickConfig, in a Windows
PowerShell elevated session, to enable WinRM.
Using Get-DscConfigurationStatus
The Get-DscConfigurationStatus cmdlet gets information about configuration status from a target node. The command returns a rich object that includes high-level information about whether the configuration run was successful or not. You can dig into the object to discover details about the configuration run such as:
- Every resource that failed.
- Any resource that requested a reboot.
- Meta-Configuration settings at time of configuration run.
The following parameter set returns the status information for the last configuration run:
Get-DscConfigurationStatus [-CimSession <CimSession[]>]
[-ThrottleLimit <int>]
[-AsJob]
[<CommonParameters>]
The following parameter set returns the status information for every configuration run:
Get-DscConfigurationStatus -All
[-CimSession <CimSession[]>]
[-ThrottleLimit <int>]
[-AsJob]
[<CommonParameters>]
Example
PS C:\> $Status = Get-DscConfigurationStatus
PS C:\> $Status
Status StartDate Type Mode RebootRequested NumberOfResources
------ --------- ---- ---- --------------- -----------------
Failure 11/24/2015 3:44:56 Consistency Push True 36
PS C:\> $Status.ResourcesNotInDesiredState
ConfigurationName : MyService
DependsOn :
ModuleName : PSDesiredStateConfiguration
ModuleVersion : 1.1
PsDscRunAsCredential :
ResourceID : [File]ServiceDll
SourceInfo : c:\git\CustomerService\Configs\MyCustomService.ps1::5::34::File
DurationInSeconds : 0.19
Error : SourcePath must be accessible for current configuration. The related file/directory is:
\\Server93\Shared\contosoApp.dll. The related ResourceID is [File]ServiceDll
FinalState :
InDesiredState : False
InitialState :
InstanceName : ServiceDll
RebootRequested : False
ResourceName : File
StartDate : 11/24/2015 3:44:56
PSComputerName :
My script won't run: Using DSC logs to diagnose script errors
Like all Windows software, DSC records errors and events in logs that are available for review in Event Viewer. Examining these logs can help you understand why a particular operation failed, and how to prevent failure in the future. To make tracking errors easier as you author, use the DSC Log resource to track the progress of your configuration in the DSC Analytic event log.
Where are DSC event logs?
In Event Viewer, DSC events are in: Applications and Services Logs/Microsoft/Windows/Desired State Configuration
You can run the corresponding PowerShell cmdlet, Get-WinEvent, to view the event logs:
PS C:\> Get-WinEvent -LogName "Microsoft-Windows-Dsc/Operational"
ProviderName: Microsoft-Windows-DSC
TimeCreated Id LevelDisplayName Message
----------- -- ---------------- -------
11/17/2014 10:27:23 PM 4102 Information Job {02C38626-D95A-47F1-9DA2-C1D44A7128E7} :
DSC's primary log name is Microsoft->Windows->DSC (other log names under Windows aren't shown here for brevity). The primary name appends to the channel name to create the complete log name.
The DSC engine writes mainly into three types of logs: Operational, Analytic, and Debug logs. Since the analytic and debug logs aren't enabled by default, you should enable them in Event Viewer. To do this:
Open Event Viewer by either:
- Typing
Show-EventLogin Windows PowerShell - Selecting the Start button, then Control Panel, then Administrative Tools, and then Event Viewer.
- Typing
On the View menu in Event viewer, select Show Analytic and Debug Logs.
The log name for the analytic channel is
Microsoft-Windows-Dsc/Analytic, and the debug channel isMicrosoft-Windows-Dsc/Debug.
You can also use the wevtutil utility to enable the logs, as shown in the following example.
wevtutil.exe set-log "Microsoft-Windows-Dsc/Analytic" /q:true /e:true
Or, use PowerShell and .NET to enable the logs as shown in the following example:
$logName = 'Microsoft-Windows-Dsc/Analytic'
$log = New-Object System.Diagnostics.Eventing.Reader.EventLogConfiguration $logName
$log.IsEnabled = $true
$log.SaveChanges()
What do DSC logs contain?
DSC logs to three different log channels based on the importance of the message. The operational log in DSC includes all error messages, and is useful for identifying a problem. The analytic log has a higher volume of events, and can identify where errors occurred. This channel also includes any emitted verbose messages. The debug log has logs that can help you understand how the errors occurred. DSC event messages begin with a job ID that uniquely represents a DSC operation. The following example attempts to get the message from the first event logged into the operational DSC log.
PS C:\> $AllDscOpEvents = Get-WinEvent -LogName "Microsoft-Windows-Dsc/Operational"
PS C:\> $FirstOperationalEvent = $AllDscOpEvents[0]
PS C:\> $FirstOperationalEvent.Message
Job {02C38626-D95A-47F1-9DA2-C1D44A7128E7} :
Consistency engine was run successfully.
DSC logs events with a structure that enables the user to collect events from one DSC job. The structure is as follows:
Job ID : <Guid>
<Event Message>
Gathering events from a single DSC operation
DSC event logs contain events generated by various DSC operations. However, usually you're concerned with the details for a specific operation. All DSC logs can be grouped by the job ID property that's unique for every DSC operation. The job ID shows as the first property value in all DSC events. The following steps explain how to accumulate all events in a grouped array structure.
<##########################################################################
Step 1 : Enable analytic and debug DSC channels (Operational channel is enabled by default)
###########################################################################>
wevtutil.exe set-log "Microsoft-Windows-Dsc/Analytic" /q:true /e:true
wevtutil.exe set-log "Microsoft-Windows-Dsc/Debug" /q:True /e:true
<##########################################################################
Step 2 : Perform the required DSC operation (Below is an example, you could run any DSC operation instead)
###########################################################################>
Get-DscLocalConfigurationManager
<##########################################################################
Step 3 : Collect all DSC Logs, from the Analytic, Debug and Operational channels
###########################################################################>
$DscEvents=[System.Array](Get-WinEvent "Microsoft-Windows-Dsc/Operational") `
+ [System.Array](Get-WinEvent "Microsoft-Windows-Dsc/Analytic" -Oldest) `
+ [System.Array](Get-WinEvent "Microsoft-Windows-Dsc/Debug" -Oldest)
<##########################################################################
Step 4 : Group all logs based on the job ID
###########################################################################>
$SeparateDscOperations = $DscEvents | Group {$_.Properties[0].value}
Here, the variable $SeparateDscOperations includes logs grouped by the job IDs. Each array
element of this variable represents a group of events logged by a different DSC operation, allowing
access to more information about the logs.
PS C:\> $SeparateDscOperations
Count Name Group
----- ---- -----
48 {1A776B6A-5BAC-11E3-BF... {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics....
40 {E557E999-5BA8-11E3-BF... {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics....
PS C:\> $SeparateDscOperations[0].Group
ProviderName: Microsoft-Windows-DSC
TimeCreated Id LevelDisplayName Message
----------- -- ---------------- -------
12/2/2013 3:47:29 PM 4115 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4198 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4114 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4102 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4098 Warning Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4098 Warning Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4176 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
12/2/2013 3:47:29 PM 4182 Information Job {1A776B6A-5BAC-11E3-BF41-00155D553612} : ...
You can extract the data in the variable $SeparateDscOperations using Where-Object.
Following are five scenarios where you might want to extract data for troubleshooting DSC:
1: Operations failures
All events have severity levels. This information is useful for identifying the error events:
PS C:\> $SeparateDscOperations | Where-Object {$_.Group.LevelDisplayName -contains "Error"}
Count Name Group
----- ---- -----
38 {5BCA8BE7-5BB6-11E3-BF... {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics....
2: Details of operations run in the last half hour
TimeCreated, a property of every Windows event, states the time the event was created. Comparing
this property with a particular date/time object is useful for filtering all events:
PS C:\> $DateLatest = (Get-Date).AddMinutes(-30)
PS C:\> $SeparateDscOperations | Where-Object {$_.Group.TimeCreated -gt $DateLatest}
Count Name Group
----- ---- -----
1 {6CEC5B09-5BB0-11E3-BF... {System.Diagnostics.Eventing.Reader.EventLogRecord}
3: Messages from the latest operation
The latest operation is stored in the first index of the array group $SeparateDscOperations.
Querying the group's messages for index 0 returns all messages for the latest operation:
PS C:\> $SeparateDscOperations[0].Group.Message
Job {5BCA8BE7-5BB6-11E3-BF41-00155D553612} :
Running consistency engine.
Job {1A776B6A-5BAC-11E3-BF41-00155D553612} :
Configuration is sent from computer NULL by user sid S-1-5-18.
Job {1A776B6A-5BAC-11E3-BF41-00155D553612} :
Displaying messages from built-in DSC resources:
WMI channel 1
ResourceID:
Message : [INCH-VM]: [] Starting consistency engine.
Job {1A776B6A-5BAC-11E3-BF41-00155D553612} :
Displaying messages from built-in DSC resources:
WMI channel 1
ResourceID:
Message : [INCH-VM]: [] Consistency check completed.
4: Error messages logged for recent failed operations
$SeparateDscOperations[0].Group has the set of events for the latest operation. Run the
Where-Object cmdlet to filter the events based on their level display name. Results are stored in
the $myFailedEvent variable, which can be further dissected to get the event message:
PS C:\> $myFailedEvent = ($SeparateDscOperations[0].Group |
Where-Object {$_.LevelDisplayName -eq "Error"})
PS C:\> $myFailedEvent.Message
Job {5BCA8BE7-5BB6-11E3-BF41-00155D553612} :
DSC Engine Error :
Error Message Current configuration does not exist. Execute Start-DscConfiguration command with
-Path parameter to specify a configuration file and create a current configuration first.
Error Code : 1
5: All events generated for a particular job ID.
$SeparateDscOperations is an array of groups, that each have the name as the unique job ID. By
running the Where-Object cmdlet, you can extract those groups of events that have a particular
job ID:
PS C:\> ($SeparateDscOperations | Where-Object {$_.Name -eq $jobX} ).Group
ProviderName: Microsoft-Windows-DSC
TimeCreated Id LevelDisplayName Message
----------- -- ---------------- -------
12/2/2013 4:33:24 PM 4102 Information Job {847A5619-5BB2-11E3-BF41-00155D553612} : ...
12/2/2013 4:33:24 PM 4168 Information Job {847A5619-5BB2-11E3-BF41-00155D553612} : ...
12/2/2013 4:33:24 PM 4146 Information Job {847A5619-5BB2-11E3-BF41-00155D553612} : ...
12/2/2013 4:33:24 PM 4120 Information Job {847A5619-5BB2-11E3-BF41-00155D553612} : ...
Using xDscDiagnostics to analyze DSC logs
xDscDiagnostics is a PowerShell module that consists of several functions that can help analyze
DSC failures on your machine. These functions can help you identify all local events from past DSC
operations, or DSC events on remote computers. Here, the term DSC operation defines a single unique
DSC execution from its start to its end. For example, Test-DscConfiguration would be a separate
DSC operation. Similarly, every other cmdlet in DSC, such as Get-DscConfiguration and
Start-DscConfiguration, are identifiable as separate DSC operations. For more information about
the diagnostics functions, see xDscDiagnostics.
Getting details of DSC operations
The Get-xDscOperation function lets you find the results of the DSC operations that run on one or
more computers. The function returns an object that has the collection of events produced by
each DSC operation. For example, in the following output, three commands were run. The first one
passed, and the other two failed. The output of Get-xDscOperation summarizes these results.
PS C:\DiagnosticsTest> Get-xDscOperation
ComputerName SequenceId TimeCreated Result JobID AllEvents
------------ ---------- ----------- ------ ----- ---------
SRV1 1 6/23/2016 9:37:52 AM Failure 9701aadf-395e-11e6-9165-00155d390509 {@{Message=; TimeC...
SRV1 2 6/23/2016 9:36:54 AM Failure 7e8e2d6e-395c-11e6-9165-00155d390509 {@{Message=; TimeC...
SRV1 3 6/23/2016 9:36:54 AM Success af72c6aa-3960-11e6-9165-00155d390509 {@{Message=Operati...
You can get results for only the most recent operations by specifying the Newest parameter:
PS C:\DiagnosticsTest> Get-xDscOperation -Newest 5
ComputerName SequenceId TimeCreated Result JobID AllEvents
------------ ---------- ----------- ------ ----- ---------
SRV1 1 6/23/2016 4:36:54 PM Success {@{Message=; TimeC...
SRV1 2 6/23/2016 4:36:54 PM Success 5c06402b-399b-11e6-9165-00155d390509 {@{Message=Operati...
SRV1 3 6/23/2016 4:36:54 PM Success {@{Message=; TimeC...
SRV1 4 6/23/2016 4:36:54 PM Success 5c06402a-399b-11e6-9165-00155d390509 {@{Message=Operati...
SRV1 5 6/23/2016 4:36:51 PM Success {@{Message=; TimeC...
Getting details of DSC events
The Trace-xDscOperation cmdlet returns an object containing a collection of events, their event
types, and the message output generated from a particular DSC operation. Typically, when you find a
failure in any of the operations using Get-xDscOperation, you would trace that operation to find
the events that caused a failure.
Use the SequenceID parameter to get the events for a specific operation for a specific computer.
For example, if you specify a SequenceID of 9, Trace-xDscOperation get the trace for the DSC
operation that was 9th from the last operation:
PS C:\DiagnosticsTest> Trace-xDscOperation -SequenceID 9
ComputerName EventType TimeCreated Message
------------ --------- ----------- -------
SRV1 OPERATIONAL 6/24/2016 10:51:52 AM Operation Consistency Check or Pull started by user sid S-1-5-20 from computer NULL.
SRV1 OPERATIONAL 6/24/2016 10:51:52 AM Running consistency engine.
SRV1 OPERATIONAL 6/24/2016 10:51:52 AM The local configuration manager is updating the PSModulePath to WindowsPowerShell\Modules;C:\Prog...
SRV1 OPERATIONAL 6/24/2016 10:51:53 AM Resource execution sequence :: [WindowsFeature]DSCServiceFeature, [xDSCWebService]PSDSCPullServer.
SRV1 OPERATIONAL 6/24/2016 10:51:54 AM Consistency engine was run successfully.
SRV1 OPERATIONAL 6/24/2016 10:51:54 AM Job runs under the following LCM setting. ...
SRV1 OPERATIONAL 6/24/2016 10:51:54 AM Operation Consistency Check or Pull completed successfully.
Pass the GUID assigned to a specific DSC operation (as returned by the Get-xDscOperation
cmdlet) to get the event details for that DSC operation:
PS C:\DiagnosticsTest> Trace-xDscOperation -JobID 9e0bfb6b-3a3a-11e6-9165-00155d390509
ComputerName EventType TimeCreated Message
------------ --------- ----------- -------
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Operation Consistency Check or Pull started by user sid S-1-5-20 from computer NULL.
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCache.mof
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Running consistency engine.
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [] Starting consistency engine.
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Applying configuration from C:\Windows\System32\Configuration\Current.mof.
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Parsing the configuration to apply.
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Resource execution sequence :: [WindowsFeature]DSCServiceFeature, [xDSCWebService]PSDSCPullServer.
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ Start Resource ] [[WindowsFeature]DSCServiceFeature]
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Executing operations for PS DSC resource MSFT_RoleResource with resource name [WindowsFeature]DSC...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ Start Test ] [[WindowsFeature]DSCServiceFeature]
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[WindowsFeature]DSCServiceFeature] The operation 'Get...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[WindowsFeature]DSCServiceFeature] The operation 'Get...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ End Test ] [[WindowsFeature]DSCServiceFeature] True in 0.3130 sec...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ End Resource ] [[WindowsFeature]DSCServiceFeature]
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ Start Resource ] [[xDSCWebService]PSDSCPullServer]
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Executing operations for PS DSC resource MSFT_xDSCWebService with resource name [xDSCWebService]P...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ Start Test ] [[xDSCWebService]PSDSCPullServer]
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[xDSCWebService]PSDSCPullServer] Check Ensure
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[xDSCWebService]PSDSCPullServer] Check Port
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[xDSCWebService]PSDSCPullServer] Check Physical Path ...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[xDSCWebService]PSDSCPullServer] Check State
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [[xDSCWebService]PSDSCPullServer] Get Full Path for We...
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ End Test ] [[xDSCWebService]PSDSCPullServer] True in 0.0160 seconds.
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: LCM: [ End Resource ] [[xDSCWebService]PSDSCPullServer]
SRV1 VERBOSE 6/24/2016 11:36:56 AM [SRV1]: [] Consistency check completed.
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCache.mof
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Consistency engine was run successfully.
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Job runs under the following LCM setting. ...
SRV1 OPERATIONAL 6/24/2016 11:36:56 AM Operation Consistency Check or Pull completed successfully.
SRV1 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCache.mof
Note that, since Trace-xDscOperation aggregates events from the Analytic, Debug, and Operational
logs, it prompts you to enable these logs.
Alternately, you can gather information on the events by saving the output of Trace-xDscOperation
into a variable. You can use the following commands to display all the events for a particular DSC
operation.
PS C:\DiagnosticsTest> $Trace = Trace-xDscOperation -SequenceID 4
PS C:\DiagnosticsTest> $Trace.Event
This displays the same results as the Get-WinEvent cmdlet, such as in the following output:
ProviderName: Microsoft-Windows-DSC
TimeCreated Id LevelDisplayName Message
----------- -- ---------------- -------
6/23/2016 1:36:53 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 1:36:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 2:07:00 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 2:07:01 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 2:36:55 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 2:36:56 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 3:06:55 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 3:06:55 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 3:36:55 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 3:36:55 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 4:06:53 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 4:06:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 4:36:52 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 4:36:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 5:06:52 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 5:06:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 5:36:54 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 5:36:54 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 6:06:52 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 6:06:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 6:36:56 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 6:36:57 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 7:06:52 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 7:06:53 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 7:36:53 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
6/23/2016 7:36:54 AM 4343 Information The DscTimer has successfully run LCM method PerformRequiredConfigurationChecks with flag 5.
6/23/2016 8:06:54 AM 4312 Information The DscTimer is running LCM method PerformRequiredConfigurationChecks with the flag set to 5.
Ideally, you would first use Get-xDscOperation to list out the last few DSC configuration runs on
your machines. Following this, you can examine any single operation by specifying its
SequenceID or JobID with Trace-xDscOperation to discover what it did behind the scenes.
Getting events for a remote computer
Use the ComputerName parameter of the Trace-xDscOperation cmdlet to get the event details on a
remote computer. Before you can do this, you have to create a firewall rule to allow remote
administration on the remote computer:
New-NetFirewallRule -Name "Service RemoteAdmin" -DisplayName "Remote" -Action Allow
Now you can specify that computer in your call to Trace-xDscOperation:
Trace-xDscOperation -ComputerName SRV2 -Credential Get-Credential -SequenceID 5
ComputerName EventType TimeCreated Message
------------ --------- ----------- -------
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Operation Consistency Check or Pull started by user sid S-1-5-20 f...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCach...
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Running consistency engine.
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [] Starting consistency...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Applying configuration from C:\Windows\System32\Configuration\Curr...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Parsing the configuration to apply.
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Resource execution sequence :: [WindowsFeature]DSCServiceFeature,...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ Start Resource ] [[WindowsFeature]DSCSer...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Executing operations for PS DSC resource MSFT_RoleResource with re...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ Start Test ] [[WindowsFeature]DSCSer...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[WindowsFeature]DSCSer...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[WindowsFeature]DSCSer...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ End Test ] [[WindowsFeature]DSCSer...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ End Resource ] [[WindowsFeature]DSCSer...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ Start Resource ] [[xDSCWebService]PSDSCP...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Executing operations for PS DSC resource MSFT_xDSCWebService with ...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ Start Test ] [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ End Test ] [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: LCM: [ End Resource ] [[xDSCWebService]PSDSCP...
SRV2 VERBOSE 6/24/2016 11:36:56 AM [SRV2]: [] Consistency check co...
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCach...
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Consistency engine was run successfully.
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Job runs under the following LCM setting. ...
SRV2 OPERATIONAL 6/24/2016 11:36:56 AM Operation Consistency Check or Pull completed successfully.
SRV2 ANALYTIC 6/24/2016 11:36:56 AM Deleting file from C:\Windows\System32\Configuration\DSCEngineCach...
My resources won't update: How to reset the cache
The DSC engine caches resources implemented as a PowerShell module for efficiency purposes. However, this can cause problems when you are authoring a resource and testing it simultaneously because DSC loads the cached version until the process restarts. The only way to make DSC load the newer version is to explicitly kill the process hosting the DSC engine.
Similarly, when you run Start-DscConfiguration, after adding and modifying a custom resource, the
modification may not execute unless, or until, the computer reboots. This is because DSC runs
in the WMI Provider Host Process (WmiPrvSE), and usually, there are many instances of WmiPrvSE
running at once. When you reboot, the host process restarts and clears the cache.
To successfully recycle the configuration and clear the cache without rebooting, you must stop and
then restart the host process. This can be on a per instance basis, whereby you identify the
process, stop it, and restart it. Or, you can use DebugMode, as demonstrated below, to reload the
PowerShell DSC resource.
To identify the process that's hosting the DSC engine, list the process ID of the WmiPrvSE, which
is hosting the DSC engine. Then, to update the provider, stop the WmiPrvSE process using the
commands below, and then run Start-DscConfiguration again.
###
### find the process that is hosting the DSC engine
###
$CimParameters = @{
ClassName = 'Msft_Providers'
Filter = "provider='dsctimer' OR provider='dsccore'"
}
$dscProcessID = Get-CimInstance @CimParameters |
Select-Object -ExpandProperty HostProcessIdentifier
###
### Stop the process
###
Get-Process -Id $dscProcessID | Stop-Process
Using DebugMode
You can configure the DSC Local Configuration Manager (LCM) to use DebugMode to always clear the
cache when the host process is restarted. When set to $true, it causes the engine to always
reload the PowerShell DSC resource. Once you're done writing your resource, you can set it back to
$false and the engine reverts to its behavior of caching the modules.
Following is a demonstration to show how DebugMode can automatically refresh the cache. First,
let's look at the default configuration:
Get-DscLocalConfigurationManager
AllowModuleOverwrite : False
CertificateID :
ConfigurationID :
ConfigurationMode : ApplyAndMonitor
ConfigurationModeFrequencyMins : 30
Credential :
DebugMode : {None}
DownloadManagerCustomData :
DownloadManagerName :
LocalConfigurationManagerState : Ready
RebootNodeIfNeeded : False
RefreshFrequencyMins : 15
RefreshMode : PUSH
PSComputerName :
You can see that DebugMode is None.
To set up the DebugMode demonstration, use the following PowerShell resource:
function Get-TargetResource {
param (
[Parameter(Mandatory)] $onlyProperty
)
$Path = "$env:SystemDrive\OutputFromTestProviderDebugMode.txt"
return @{
onlyProperty = Get-Content -Path $Path
}
}
function Set-TargetResource {
param (
[Parameter(Mandatory)] $onlyProperty
)
"1" | Out-File -PSPath "$env:SystemDrive\OutputFromTestProviderDebugMode.txt"
}
function Test-TargetResource {
param (
[Parameter(Mandatory)]
$onlyProperty
)
return $false
}
Now, author a configuration called TestProviderDebugMode:
Configuration ConfigTestDebugMode
{
Import-DscResource -Name TestProviderDebugMode
Node localhost
{
TestProviderDebugMode test
{
onlyProperty = "blah"
}
}
}
ConfigTestDebugMode
The content of the file $env:SystemDrive\OutputFromTestProviderDebugMode.txt is 1.
Now, update the provider code using the following script:
$newResourceOutput = Get-Random -Minimum 5 -Maximum 30
$OutputPath = "C:\Program Files\WindowsPowerShell\Modules\MyPowerShellModules\DSCResources\TestProviderDebugMode\TestProviderDebugMode.psm1"
$content = @"
function Get-TargetResource {
param (
[Parameter(Mandatory)] `$onlyProperty
)
`$Path = "$env:SystemDrive\OutputFromTestProviderDebugMode.txt"
return @{
onlyProperty = Get-Content -Path $Path
}
}
function Set-TargetResource {
param (
[Parameter(Mandatory)] `$onlyProperty
)
"$newResourceOutput" | Out-File -PSPath C:\OutputFromTestProviderDebugMode.txt
}
function Test-TargetResource {
param (
[Parameter(Mandatory)] `$onlyProperty
)
return `$false
}
"@ | Out-File -FilePath $OutputPath
This script generates a random number and updates the provider code. With DebugMode set to false,
the contents of the file $env:SystemDrive\OutputFromTestProviderDebugMode.txt are never changed.
Now, set DebugMode to ForceModuleImport in your configuration script:
LocalConfigurationManager
{
DebugMode = "ForceModuleImport"
}
When you run the script again, note that the content of the file is different every time. You can
run Get-DscConfiguration to check it. The snippet below shows the result of two more runs. Your
results may be different when you run the script.
PS C:\> Get-DscConfiguration -CimSession (New-CimSession localhost)
onlyProperty PSComputerName
------------ --------------
20 localhost
PS C:\> Get-DscConfiguration -CimSession (New-CimSession localhost)
onlyProperty PSComputerName
------------ --------------
14 localhost
DSC returns "unexpected response code InternalServerError" when registering with Windows Pull Server
When applying a metaconfiguration to a server to register it with an instance of Windows Pull Server, you might get the following error.
Registration of the Dsc Agent with the server https://<serverfqdn>:8080/PSDSCPullServer.svc failed. The underlying error is: The attempt to register Dsc Agent with AgentId <ID> with the server
https://<serverfqdn>:8080/PSDSCPullServer.svc/Nodes(AgentId='<ID>') returned unexpected response code InternalServerError. .
+ CategoryInfo : InvalidResult: (root/Microsoft/...gurationManager:String) [], CimException
+ FullyQualifiedErrorId : RegisterDscAgentUnsuccessful,Microsoft.PowerShell.DesiredStateConfiguration.Commands.RegisterDscAgentCommand
+ PSComputerName : <computername>
This can occur when the certificate used on the server to encrypt traffic has a common name (CN) that's different than the DNS name used by the node to resolve the URL. Update the Windows Pull Server instance to use a certificate with a corrected name.
Error when running Sysprep after applying a DSC Configuration
When attempting to run Sysprep to generalize a Windows Server after applying a DSC configuration, you might get the following error.
SYSPRP LaunchDll:Failure occurred while executing 'DscCore.dll,SysPrep_Cleanup', returned error code 0x2
Generalizing a server after it's configured using Windows PowerShell Desired State Configuration isn't a supported scenario. Instead, apply configurations to Windows after the Specialize phase of Windows Setup has completed.
See Also
Concepts
Other Resources
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for