Validate PowerShell DSC Debug

This is part five of a blog series introduced in Validate the new features of PowerShell DSC.

New Capability

DSC has a new debugging mode that helps with troubleshooting by making it possible to interact with scripts being run by DSC, as they are being applied. When this mode is enabled, as the machine applies the configuration, progress will stop at the first script action to wait for a remote connection to open. Once connected, the person doing the troubleshooting can interact with the session as well as use breakpoints to debug.

What is the purpose of this feature?

Customers have requested additional tools for troubleshooting. The new debugging mode, combined with existing tools, provides an improved troubleshooting experience.

What is the easiest way to test it?

To test the new debug feature you will need to enable ResourceScriptBreakAll debug mode, apply a configuration, and then connect to the session and interact with it. The examples below provide a simple configuration for testing. It will be easier to test this with modules that are available from the gallery, rather than those built in to Windows.

This approach is compatible with the April 2015 WMF5 Preview. Set ResourceScriptBreakAll mode:

[DscLocalConfigurationManager()]\    Configuration ConfigureLCMForDebug\    {\        Settings\        {\            DebugMode = 'ResourceScriptBreakAll'\        }\    }\    ConfigureLCMForDebug -outputpath c:\\LCMDebug\    Set-DscLocalConfigurationManager -path c:\\LCMDebug -verbose

Add a module for configuring RDP. You will need to respond \”Yes\” to accepting the module from the online gallery.

    Install-Module xRemoteDesktopAdmin

Apply sample configuration:

   Configuration RDP\    {\    Import-DscResource -ModuleName 'PSDesiredStateConfiguration','xRemoteDesktopAdmin'\    xRemoteDesktopAdmin TestRDP\        {\            Ensure = 'Present'\        }\    }\    RDP -out c:\\RDP\    Start-DSCConfiguration -path c:\\RDP -verbose -wait -force

\\

What should I expect to see?

When a configuration is being applied it should halt and wait provide you with the commands you need to connect and interact.

    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 Server01 with user sid S-3-5-71-1845750\    65-758653677-1645149031-523543.\    VERBOSE: [Server01]: LCM:  [ Start  Set      ]\    WARNING: [Server01]:                            [DSCEngine] Warning LCM is in Debug 'Reso\    urceScriptBreakAll' mode.  Resource script processing will be stopped to wait for PowerSh\    ell script debugger to attach.\    VERBOSE: [Server01]:                            [DSCEngine] Importing the module C:\\Progr\    am Files\\WindowsPowerShell\\Modules\\xRemoteDesktopAdmin\\1.0.3.0\\DscResources\\xRemoteDeskto\    pAdmin\\xRemoteDesktopAdmin.psm1 in force mode.\    VERBOSE: [Server01]: LCM:  [ Start  Resource ]  [[xRemoteDesktopAdmin]TestRDP]\    VERBOSE: [Server01]: LCM:  [ Start  Test     ]  [[xRemoteDesktopAdmin]TestRDP]\    VERBOSE: [Server01]:                            [[xRemoteDesktopAdmin]TestRDP] Importing \    the module xRemoteDesktopAdmin in force mode.\n"); document.wri
te("    WARNING: [Server01]:                            [[xRemoteDesktopAdmin]TestRDP] Resource i\    s waiting for PowerShell script debugger to attach.  Use the following commands to begin \    debugging this resource script:\    Enter-PSSession -ComputerName Server01 -Credential <credentials>\    Enter-PSHostProcess -Id 10156 -AppDomainName DscPsPluginWkr_AppDomain\    Debug-Runspace -Id 4\

The last three lines in the output example above provide a reference to connect with the session from a new instance of PowerShell ISE. In the first line, replace with (Get-Credential) to get an interactive prompt for username and password. Make sure you log in with an account that is a local administrator.

Enter-PSSession -ComputerName Server01 -Credential (get-credential)\    Enter-PSHostProcess -Id 10156 -AppDomainName DscPsPluginWkr_AppDomain\    Debug-Runspace -Id 4

PS C:\\WINDOWS\\system32> Enter-PSSession -ComputerName Server01 -Credential (Get-Credential)\    Enter-PSHostProcess -Id 10156 -AppDomainName DscPsPluginWkr_AppDomain\\    [Process:10156]: PS C:\\WINDOWS\\system32> Debug-Runspace -Id 4\    Debugging Runspace: Runspace4\    To end the debugging session type the 'Detach' command at the debugger prompt, o\    r type 'Ctrl+C' otherwise.\    [DBG]: [Process:10156]: [Runspace4]: PS C:\\WINDOWS\\system32>> Test-TargetResource\\\    Command or script completed.\    To end the debugging session type the 'Detach' command at the debugger prompt, or type 'Ctrl+C' otherwise.\\\    Command or script completed.\    To end the debugging session type the 'Detach' command at the debugger prompt, or type 'Ctrl+C' otherwise.\\    [DBG]: [Process:10156]: [Runspace4]: PS C:\\WINDOWS\\system32>> $Ensure\    Present \

How to provide feedback

The introductory post lists a summary of options. The best option is to use Microsoft Connect. Thank you so much for your time! It is sincerely appreciated.

Michael Greene