NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

Introduction

The xDscDiagnostics module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC related artifacts produced by the PowerShell Team. This module contains two cmdlets: Get-xDscOperation and Trace-xDscOperation. These cmdlets help in reading the DSC event logs for any particular DSC operation. This further helps in identifying the causes of any failure in a DSC operation.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xDscDiagnostics stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xDscDiagnostics module, feel free. When modifying, please update the module name and cmdlet names (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xDscDiagnostics module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-Module -ListAvailable to see that xDscDiagnostics is among the modules listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xDscDiagnostics module exposes two main functions - Get-xDscOperation and Trace-xDscOperation and one helper function - Update-xDscEventLogStatus that aid in diagnosing DSC errors. Here, we use the term DSC operation to indicate an execution of any DSC cmdlet from the start to its end. For instance, Start-DscConfiguration and Test-DscConfiguration would form two separate DSC operations. The cmdlets also let you diagnose operations run on other computers. More details about their usage is given below in the Details section.

Details

The functions and their parameters exposed by the module xDscDiagnostics are given below:

  • Get-xDscOperation:  This cmdlet helps you to list out the status of the last few run DSC operations. It returns an object that has information about the Time that operation was created, whether the operation was successful or not, a handle to all the events generated by that operation, and the unique job identifier for that operation (Read this blog to understand the role of the job ID in Dsc events) The parameters that this cmdlet accepts are as below:
    • Newest:        Number of past operations you want to output. By default, it will display details of the last 10 operations
    • ComputerName:   Name of the computer from which you'd like to collect the event diagnostic details. The input can be an array of strings. You would need to execute the command New-NetFirewallRule -Name "Service RemoteAdmin" -Action Allow on the remote computer in order to execute this operations on it.
    • Credential:      Credentials required to access the computer given in the ComputerName property
  • Trace-xDscOperation:  Once we run the Get-xDscOperation, we can see which of the operations were a failure/success. Also, we can notice there is a corresponding SequenceID and JobID corresponding to each operation. Trace-xDscOperation cmdlet takes either of these values as parameters and gives you a readable list of events generated by the respective DSC operation. By default, Trace-xDscOperation will list all the events generated by the recentmost DSC operation. This cmdlet returns an object that contains properties such as the event type, the event message, and time of creation of each event. The parameters accepted are listed below:
    • SequenceID:      This is a field present in the object returned from running Get-xDscOperation cmdlet. It identifies an operation run in the computer. By specifying the sequence ID, all the events pertaining to the corresponding operation are returned.
    • JobID:        This is a GUID that is a prefix to all the events published by DSC, which uniquely identifies each operation. It is also a field present in the object returned from running Get-xDscOperation cmdlet. By specifying a JobID, this cmdlet will extract and display all events pertaining to the corresponding DSC operation.
    • ComputerName:   Name of the computer from which you'd like to collect the event diagnostic details. The input can be an array of strings. You would need to execute the command New-NetFirewallRule -Name "Service RemoteAdmin" -Action Allow on the remote computer(s) in order to execute this operations on it.
    • Credential:      Credentials required to access the computer given in the ComputerName property
  • Update-xDscEventLogStatus:  This cmdlet helps us enable or disable any of the DSC event logs. When the cmdlets Get-xDscOperation and Set-xDscOperation are used, they will output details from events generated in the enabled channels. If the channel is disabled, a warning is issued on the PowerShell console. By using the cmdlet Update-xDscEventLogStatus, you could enable the channel required to collect DSC events.
    • Channel:          This parameter accepts values among the set "Analytic", "Debug" and "Operational". It is a mandatory parameter that indicates which DSC channel status needs to be updated
    • Status:       This is a mandatory parameter that indicates what the final state of the channel should be. The possible values are Enabled (when you'd want to enable a channel) and Disabled (When the channel needs to be disabled)
    • ComputerName:   Name of the computer on which you would like to set the log status. You would need to execute the command New-NetFirewallRule -Name "Service RemoteAdmin" -Action Allow on the remote computer(s) in order to execute this operations on it.
    • Credential:      Credentials required to access the computer given in the ComputerName property

Renaming Requirements

When making changes to this module, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xDscDiagnostics becomes cDscDiagnostics)
    • Function Name (ex: Get-xDscOperation becomes Get-cDscOperation)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve function and module names without prefixes ("x" or "c") for future use (e.g. DscDiagnostics or Get-DscOperation). If the next version of Windows Server ships with a "DscDiagnostics" module, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.0.0

  • Initial release with the following cmdlets
    • Get-xDscOperation
    • Trace-xDscOperation

2.0.0.0

  • Release with bug fixes and the following cmdlets
    • Get-xDscOperation
    • Trace-xDscOperation
    • Update-xDscEventLogStatus

Example: Display the status of last 20 DSC operations

This example will show how the last 20 DSC operations can be listed, to see if any of them failed . 
PowerShell
Edit|Remove
Get-xDscOperation -Newest 20

Example: Display the status of last 2 operations in computer XXYY after passing Credential $cred

This example lets you find the status of DSC operations run in another computer. 
Note: this requires a credential.
PowerShell
Edit|Remove
Get-xDscOperation -ComputerName Temp-Computer.domain.com -Credential $cred -Newest 2

Example: Trace a DSC operation that has a specific job ID

This example will display all events generated by the DSC operation that was assigned a particular unique job ID .
PowerShell
Edit|Remove
Trace-xDscOperation -JobId aa6b4f3e-53f9-4f02-a502-26028e7531ca

Example: Get events of the second to last operation run on the localhost machine

This example will display the list of events and their messages published by the DSC operation run second to last, which means, the sequence ID assigned to it is 2.
PowerShell
Edit|Remove
Trace-xDscOperation -SequenceId 2 -ComputerName localhost

Example: Get diagnostic events of operations run on multiple computers that use the same credential

This example will display the list of events and their messages from multiple computers, as long as the credential passed works for all of them
PowerShell
Edit|Remove
Get-xDscOperation -ComputerName localhost, tempcomputer.domain.com -Credential $cred

Example: Enable the DSC Analytic event log

This example will show how you could enable the DSC analytic channel event log. By default, this channel is disabled. By using this cmdlet, you can enable the channel to help collect all DSC events using the other 2 xDscDiagnostics cmdlets.
PowerShell
Edit|Remove
Update-xDscEventLogStatus -Channel Analytic -Status Enabled