NOTE: For information on OS support, and other features, please refer to our release history.

Overview

In order to improve the quality of the DSC Extension, the DSC Extension will start automatically sending information to Microsoft containing operational and reliability data about the DSC Extension in a future version of the DSC Extension. While we strongly encourage you to participate in improving the quality of our software, participation is voluntary, so we are adding the ability to disable it through the Azure PowerShell SDK and Azure Resource Manager (ARM) templates. We encourage you to leave this feature enabled.

1. How to disable DSC Extension Data Collection using the Azure PowerShell SDK
2. How to disable DSC Extension Data Collection using ARM JSON

Disabling Data Collection using the Azure PowerShell SDK

This option was added in version 1.2 of the Azure PowerShell SDK, previous versions of the SDK do not have a way to disable Data Collection, therefore ensure that you are running that version or a newer one.

Starting with version 2.9 of the extension, you can disable Data Collection, when you call Set-AzureVMDscExtension (see our introduction blog for how to use this) add the parameter -DataCollection with the value Disable. On version 2.9 and higher, the extension will remember this setting for the VM. Using the Data Collection parameter will have no effect if you are using DSC Extension version prior to 2.9. See the examples below:

$vm = Set-AzureVMDSCExtension  -DataCollection Disable -VM $vm -ConfigurationArchive "IISInstall.ps1.zip" -ConfigurationName "IISInstall"

If you have never set DataCollection on a VM, the default is Enable.

Disabling Data Collection using ARM JSON

The previous ARM blog, described how to use visual studio to create an ARM Template to disable data collection. The following example starts with the DSC Resource JSON snippet from Git Hub from that blog to demonstrate how to disable Data Collection in the ARM JSON.

{
    "name": "Microsoft.Powershell.DSC",
    "type": "extensions",
    "location": "[variables('location')]",
    "apiVersion": "2015-05-01-preview",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'))]"
    ],
    "tags": {
        "displayName": "Microsoft.Powershell.DSC"
    },
    "properties": {
        "publisher": "Microsoft.Powershell",
        "type": "DSC",
        "typeHandlerVersion": "2.9",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "modulesUrl": "[concat(parameters('_artifactsLocation'), '/', 'dsc.zip')]",
            "sasToken": "[parameters('_artifactsLocationSasToken')]",
            "wmfVersion": "[parameters('wmfVersion')]",
            "configurationFunction": "[variables('Microsoft.Powershell.DSCConfigurationFunction')]",
            "properties": {
                "nodeName": "[variables('vmName')]"
            }
        },
        "protectedSettings": { }
    }
}

To that we will add the following JSON after modulesUrl.

    "privacy":  {
        "DataCollection": "Disable"
    },

This will result in the following JSON.

{
    "name": "Microsoft.Powershell.DSC",
    "type": "extensions",
    "location": "[variables('location')]",
    "apiVersion": "2015-05-01-preview",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'))]"
    ],
    "tags": {
        "displayName": "Microsoft.Powershell.DSC"
    },
    "properties": {
        "publisher": "Microsoft.Powershell",
        "type": "DSC",
        "typeHandlerVersion": "2.9",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "modulesUrl": "[concat(parameters('_artifactsLocation'), '/', 'dsc.zip')]",
            "privacy":  {
                "DataCollection": "Disable"
            },
            "sasToken": "[parameters('_artifactsLocationSasToken')]",
            "wmfVersion": "[parameters('wmfVersion')]",
            "configurationFunction": "[variables('Microsoft.Powershell.DSCConfigurationFunction')]",
            "properties": {
                "nodeName": "[variables('vmName')]"
            }
        },
        "protectedSettings": { }
    }
}

In order to deploy this ARM JSON, follow the instruction from the previous blog.

Enabling Data Collection

If you have previously disabled Data Collection, and would like to re-enable it, then remove the existing extension and while re-installing change the value of DataCollection from Disable to Enable. Again, this will follow the same persistence rule for Datacollection on the VM.

Feedback

Please feel free to reach to us posting comments to this post, or by posting feedback on Connect.

Resources

Privacy Statement

End User License Agreement

Today we are glad to release a Preview of platyPS.

platyPS is a PowerShell module that converts PowerShell help files written as Markdown to other formats starting with MAML XML.

What’s the problem

Traditionally PowerShell external help files have been authored as MAML XML.MAML is cumbersome to edit by hand, and traditional tools and editors don’t support it for complex scenarios like they do with Markdown. And while comment-based help is nice for writing scripts and functions, especially where the source is available, for more complex scenarios (e.g. very large and/or C#/binary modules), it can be desirable to have documentation abstracted away from the codebase.

For example, in the future, we would like to have our cmdlet documentation easily accessible from the PowerShell-Docs repo,so that we can update it more easily and frequently. Furthermore, public documentation means that you, our community, can more easily contribute to any low-hanging fruit you see in our documentation as well.Lastly, we can track Issues and in progress work on this documentation from a single, public location.

Markdown

Markdown is widely adopted by the Open-Source community to author documentation.For example, the PowerShell team uses Markdown for DSC documentation.

Markdown was designed to be human-readable without rendering which makes it easy to write and edit. Many editors support it (Visual Studio Code, Sublime Text, and others), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.

platyPS markdown schema

Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a particular way.We have defined a schema to determine how parameters are described, where scripts examples are shown and, so on.

Any authoring must not break this formatting or the MAML will not be generated correctly.The schema closely resembles the existing output format of Get-Help.

Legend

• {string} – single-line string value
• {{text}} – multi-line text
• // – line comment in schema
• tabs show the scopes of // for statements; they should not be included in the Markdown output.

Version 1.0.0

// for every command:
    # {Command name}

    ## SYNOPSIS
    {{Synopsis text}}

    ## DESCRIPTION
    {{Description text}}

    ## PARAMETERS

    // for every parameter
        // type and default value are non-mandatory
        ### {Parameter name} [{Parameter type}] = {Parameter default value}

        // parameter metadata
        ```powershell
        {{Parameter attributes as specified in param() block in PowerShell functions
        i.e. [Parameter(ParameterSetName = 'ByName')]
        }}
        ```

        {{Parameter description text}}

    ## INPUTS
    // for every input type
        #### {Input type}
        {{Description text}}

    ## OUTPUTS
    // for every output type
        ### {Output type}
        {{Description text}}

    ## EXAMPLES
    // for every example
        ### {Example Name}

        ```powershell
        {{Example body}}
        ```
        {{Example text explanation}}

    ## RELATED LINKS

    // for every link
        [{link name}]({link url})

You can find the current schema on GitHub.

What preview means

The tool and schema is by no means perfect, but it is fully functional and being used by the PowerShell team.Our intention with this release is to gain feedback quickly and adjust accordingly.

Known issues

• Only English language supported.
• Not all Markdown syntax is supported (e.g. tables)

How to use it?

You can install platyPS as module from the PowerShell Gallery:

Install-Module platyPS

Example 1

Create an initial Markdown template from command and copy it to clipboard:

Get-platyPSMarkdown -Command Get-MyCommandName | Set-Clipboard

Copy it to some MyModule.md file on disk.

Example 2

Make external help generation a part of your build process for the module.For example, here is how platyPS builds its own documentation:

# Generate help for the module
Import-Module $pwd\out\platyPS
$maml = Get-platyPSExternalHelp -Markdown (cat -Raw .\src\platyPS\platyPS.md)
mkdir out\platyPS\en-US -ErrorAction SilentlyContinue > $null
Set-Content -Path out\platyPS\en-US\platyPS.psm1-Help.xml -Value $maml -Encoding UTF8

Example 3

Preview Get-Help output for generated maml:

$generatedModule = New-PlatyPSModuleFromMaml -MamlFilePath $outMamlFilePath
$generatedModule.Cmdlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out-String }

Sergei Vorobev

PowerShell Team

Overview

This is the schema for the settings portion of the Azure DSC extension in an ARM template.

Fast Reference

"settings": {
  "wmfVersion": "latest",
  "configuration": {
    "url": "http://validURLToConfigLocation",
    "script": "ConfigurationScript.ps1",
    "function": "ConfigurationFunction"
  },
  "configurationArguments": {
    "argument1": "Value1",
    "argument2": "Value2"
  },
  "configurationData": {
    "url": "https://foo.psd1"
  },
  "privacy": {
    "dataCollection": "enable"
  },
  "advancedOptions": {
    "downloadMappings": {
      "customWmfLocation": "http://myWMFlocation"
    }
  }
},
"protectedSettings": {
  "configurationArguments": {
    "parameterOfTypePSCredential1": {
      "userName": "UsernameValue1",
      "password": "PasswordValue1"
    },
    "parameterOfTypePSCredential2": {
      "userName": "UsernameValue2",
      "password": "PasswordValue2"
    }
  },
  "configurationUrlSasToken": "?g!bber1sht0k3n",
  "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

Details

Settings vs. ProtectedSettings

All of these settings will be saved in a settings text file on your VM.

Properties under ‘settings’ are considered public properties because they will not be encrypted in the settings text file.

Properties under ‘protectedSettings’ will be encrypted with a certificate and will not be shown in plain text in this file on your VM.

So, if your configuration needs credentials, and you would like these credentials to be encrypted on your VM, you can include them in protectedSettings like so:

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
            "userName": "UsernameValue1",
            "password": "PasswordValue1"
        }
    }
}

Example

I have a simple configuration I made that looks like this:

Configuration TestConfig
{
    param (
        $CountryName
    )
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    File TestFile
    {
        Ensure = "Present"
        DestinationPath = "C:\TestFile"
        Contents = "Hello there fair traveler! Welcome to $CountryName!"
    }
}

I want to use the Azure DSC Extension in an ARM template to apply this configuration to my VM.

So, first, I save this configuration in a file named ‘WorldlyConfig.ps1′, zip it up, and post the zip file on my website at the URL ‘https://superworldtraveler.thisisnotarealURL/WorldlyConfig.zip’ (just an example, not a real URL).

This file on my website has restricted access, so I will need to provide a SAS token.

I generate the SAS Token ‘?flibberdigibbets’ so that the extension can access the file.

Now, in my ARM template, I use these settings to tell the DSC extension to run my configuration:

"settings": {
    "configuration": {
        "url": "https://superworldtraveler.thisisnotarealURL/WorldlyConfig.zip'",
        "script": "WorldlyConfig.ps1",
        "function": "TestConfig"
    },
    "configurationArguments": {
        "CountryName": "Canada"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "?flibberdigibbets"
}

Updating from the Previous Format

Any settings in the previous format (containing the public properties ModulesUrl, ConfigurationFunction, SasToken, or Properties) will be automatically adapted to the current format and will run just as they did before.

The previous settings schema looked like this:

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties":  {
        "ParameterToConfigurationFunction1":  "Value1",
        "ParameterToConfigurationFunction2":  "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

Here’s how the previous format adapts to the current format:

Troubleshooting – Error Code 1100

Error Code 1100 indicates that there is a problem with the user input to the DSC extension.

The text of these errors is variable and may change.

Here are some of the errors you may run into and how you can fix them.

Invalid Values

“Privacy.dataCollection is ‘{0}’. The only possible values are ”, ‘Enable’, and ‘Disable'”

“WmfVersion is ‘{0}’. Only possible values are . and ‘latest'”

Problem: A provided value is not allowed.

Solution: Change the invalid value to a valid value. See the table in the Details section above.

Invalid URL

“ConfigurationData.url is ‘{0}’. This is not a valid URL”

“DataBlobUri is ‘{0}’. This is not a valid URL”

“Configuration.url is ‘{0}’. This is not a valid URL”

Problem: A provided URL is not valid.

Solution: Check all your provided URLs. Make sure they all resolve to valid URLs that the extension can access on the remote machine.

Invalid ConfigurationArgument Type

“Invalid configurationArguments type {0}”

Problem: The ConfigurationArguments property cannot resolve to a Hashtable object.

Solution: Make your ConfigurationArguments property a Hashtable. Follow the format provided in the example above. Watch out for quotes, commas, and braces.

Duplicate ConfigurationArguments

“Found duplicate arguments ‘{0}’ in both public and protected configurationArguments”

Problem: The ConfigurationArguments in public settings and the ConfigurationArguments in protected settings contain properties with the same name.

Solution: Remove one of the duplicate properties.

Missing Properties

“Configuration.function requires that configuration.url or configuration.module is specified”

“Configuration.url requires that configuration.script is specified”

“Configuration.script requires that configuration.url is specified”

“Configuration.url requires that configuration.function is specified”

“ConfigurationUrlSasToken requires that configuration.url is specified”

“ConfigurationDataUrlSasToken requires that configurationData.url is specified”

Problem: A defined property needs another property that is missing.

Solutions:

• Provide the missing property.
• Remove the property that needs the missing property.

Traditionally PowerShell script debugging has been limited to script running inside the PowerShell console or ISE (Integrated Script Environment), which means you are limited to debugging script that you can see and is running interactively. This is great most of the time as it allows you to experiment with and debug PowerShell script by setting breakpoints and stepping through the script code. But PowerShell is more than just a command line shell that supports scripting. It is also a robust management automation platform where scripts can run concurrently and non-interactively. How do you debug these scripts?A perfect example of this is PowerShell DSC (Desired State Configuration). DSC lets you create special PowerShell script functions or classes for the purpose of configuring remote machines (https://blogs.technet.microsoft.com/privatecloud/2013/08/30/introducing-powershell-desired-state-configuration-dsc/).These resource scripts run on remote target machines in a special host process. How on earth do you debug these scripts? Sure you can begin by adding a lot of verbose messaging to your scripts. But ideally you would like to debug a live session by setting breakpoints, stepping through the code and viewing variables just like you can with script running in the console or ISE.

Fortunately PowerShell V5 has new debugging features that allow you to do just this. In this article I will briefly discuss the new PowerShell 5.0 cmdlets that help you attach to arbitrary local PowerShell hosting processes and debug running PowerShell script. I’ll then talk about how PowerShell DSC uses these new PowerShell features for DSC resource debugging on a target computer. Along the way I’ll point out current limitations when debugging live DSC resource scripts, and ways DSC resource script debugging can be improved in the future.

PowerShell V5 Advanced Debugging Cmdlets

As you might expect debugging arbitrary running scripts on a local or remote machine is a bit more complex than simply setting breakpoints in a file you have open in the ISE and then hitting the F5 key. There are two new sets of cmdlets to help with this. The first involve using PowerShell runspace objects to find and debug running scripts in a session. The second deal with attaching a console or ISE session to a separate local process that hosts PowerShell. Combining these together gives you the ability to debug any scripts on a local or remote machine.

What are Runspaces?

First you need to understand PowerShell runspaces since advanced debugging is necessarily built around these.

https://blogs.technet.microsoft.com/heyscriptingguy/2015/11/26/beginning-use-of-powershell-runspaces-part-1/

Runspaces are PowerShell abstractions that define the context in which PowerShell script and commands run. Normally you don’t care about runspaces because when you run script inside the console or ISE a “default” runspace is created for you. You don?t need to be aware of the runspace, it just all works. But if you want to run other background scripts in the session, you can do this too by creating more runspaces. Each background script runs in its own runspace while allowing you to continue to use the session console. This is exactly how PowerShell jobs work. You can think of runspaces as containing all of the state needed to run a script, such as variables, functions, loaded modules, etc. Since scripts run within a runspace, debugging an arbitrary running script is synonymous to debugging its runspace.

New Runspace Cmdlets

There are five new cmdlets that help you discover and debug runspaces.

Get-Runspace

This cmdlet is for discovery and lists all runspaces in the session. Running this from the console or ISE will normally return just one (default) runspace.

Debug-Runspace

This cmdlet is run from the console or ISE and performs a “debugger attach” operation to the specified runspace. It can’t be used on the default runspace (you will get an error if you try) because that already has the console debugger associated with it. But for other runspaces it lets you attach the existing console or ISE debugger to that non-default runspace. The debugger remains attached until you type Ctrl+C at the keyboard to get back the command line prompt. When the debugger is attached the debugger is put in “break all” mode and if the runspace happens to be running script then the debugger will automatically break at the next script execution point. Otherwise it will wait until script begins running and then break at the first available execution point.

Enable-RunspaceDebug

This cmdlet enables the runspace for debugging. This means that it will wait for a debugger to be attached when a breakpoint is hit. It also has a -BreakAll switch parameter that tells the runspace to immediately stop in the debugger when running a new script. Be careful with this as script stopped and waiting for a debugger attach can appear to be hung, when in fact it is just waiting for a debugger attach. The runspace Availability property tells you if it is waiting for a debugger with a value of “InBreakpoint”.

Disable-RunspaceDebug

This cmdlet disables the runspace for debugging by reverting it back to normal operation. It also releases the debugger if it is stopped at a breakpoint.

Get-RunspaceDebug

This cmdlet returns the current debug setting of the runspace

Attach to Host Process Cmdlets

PowerShell now allows you to attach to another local process that is hosting PowerShell. By doing this you can see what runspaces that host process has and whether it is running any script. And of course you can debug any script running in that runspace. Note that you can attach to an arbitrary hosting process only if you have Administrator privileges on that machine. Otherwise you are restricted to host processes that were created with your credentials. There are three cmdlets to support these operations.

Get-PSHostProcessInfo

This cmdlet returns all local processes that are hosting PowerShell and that you can attach to.

Enter-PSHostProcess

This cmdlet lets you attach to the process from the console or ISE and interact in a PowerShell session in that process. This means you can run commands or script in that process including finding and debugging runspaces. This cmdlet is very similar to the existing Enter-PSSession cmdlet except that you are interacting with an existing local host process rather than a remote machine.

Exit-PSHostProcess

This cmdlet exits the interactive session with the host process and severs the connection.

Debugging PowerShell DSC Resource Scripts

Congratulations! You are now armed with the knowledge needed to use and understand PowerShell DSC resource debugging. I could have skipped the first part and started here but I thought it worthwhile to first explain (admittedly briefly) the new PowerShell debugging features\cmdlets that this is based on.

PowerShell DSC runs resource scripts on a target machine in the LCM (Local Configuration Manager) that is hosted in a wmiprvse.exe process. So from the above discussion you can immediately see how this will work. The DSC resource script is run on the target machine, stops in the debugger and waits for a debugger attach. We use the cmdlets discussed above to attach to the LCM host process and then debug the runspace running the resource script.

To do this the script is run in a special LCM debug mode. Currently this debug mode only supports break all functionality where the LCM running script is stopped at the first execution point and waits for a debugger attach. Hopefully in the future the LCM debug mode will support script source file line breakpoints so that the script is stopped right where you want. There is another way to get the script to stop where you want it to, but it involves modifying the script source. See the Wait-Debugger section below.

DSC Debug Mode Cmdlets

Enable-DSCDebug

This cmdlet sets the LCM on the machine to debug mode. It currently only supports ?BreakAll. The LCM BreakAll mode causes any resource script execution to stop immediately and wait for a debugger attach to be attached.

Disable-DSCDebug

This cmdlet reverts the LCM back to normal operation.

DSC resource script debugging steps

1. Set the LCM on the target machine to debug break all mode (Enable-DSCDebug -BreakAll)
2. Run the DSC configuration and wait for the script to stop in the debugger (you will receive messages telling when this happens)
3. Follow the message instructions to attach the debugger to the runspace running the script
4. Run “step into” debugger command until you get to your resource method (Test, Get, Set)
5. Set line breakpoints as needed and debug the script
6. When finished, detach the debugger
7. Set the LCM back to non-debug mode (Disable-DSCDebug)

Example

This example illustrates how to debug DSC class resource scripts. I have created a simple DSC class resource named ‘FileResource’ that copies or removes a file during configuration. A DSC resource class must have at least three methods (Test, Set, and Get) but can have other helper methods, and in this example I have a CopyFile helper method that performs the file copy.

Simple resource class for test

##
## Test Class based resource
##

enum Ensure
{
    Absent
    Present
}

[DscResource()]
class FileResource
{
    [DscProperty(Key)]
    [string] $Path

    [DscProperty(Mandatory)]
    [Ensure] $Ensure

    [DscProperty(Mandatory)]
    [string] $SourcePath

    [DscProperty(NotConfigurable)]
    [Nullable[datetime]] $CreationTime


    [void] Set()
    {
        $fileExists = $this.TestFilePath($this.Path)
        if ($this.ensure -eq [Ensure]::Present)
        {
            if (! $fileExists)
            {
               $this.CopyFile()
            }
        }
        else
        {
            if ($fileExists)
            {
                Write-Verbose -Message "Deleting the file $($this.Path)"
                Remove-Item -LiteralPath $this.Path -Force
            }
        }
    }

    [bool] Test()
    {
        $present = Test-Path -LiteralPath $this.Path

        if ($this.Ensure -eq [Ensure]::Present)
        {
            return $present
        }
        else
        {
            return (! $present)
        }
    }

    [FileResource] Get()
    {
        $present = Test-Path -Path $this.Path

        if ($present)
        {
            $file = Get-ChildItem -LiteralPath $this.Path
            $this.CreationTime = $file.CreationTime
            $this.Ensure = [Ensure]::Present
        }
        else
        {
            $this.CreationTime = $null
            $this.Ensure = [Ensure]::Absent
        }

        return $this
    }

    [void] CopyFile()
    {
        if (! (Test-Path -LiteralPath $this.SourcePath))
        {
            throw "SourcePath $($this.SourcePath) is not found."
        }

        if (Test-Path -LiteralPath $this.Path -PathType Container)
        {
            throw "Path $($this.Path) is a directory path"
        }

        Write-Verbose "Copying $($this.SourcePath) to $($this.Path)"

        Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force
    }
}

Configuration file

##
## Configuration for DSC test class
##

Configuration DSCTestClass
{
    Import-DSCResource -module DSCClassResource
    FileResource file
    {
        Path = "C:\temp\test\test.txt"
        SourcePath = "c:\temp\test.txt"
        Ensure = "Present"
    }
}

DSCTestClass

The DSC resource is already on the target machine so I will start by enabling DSC resource script debugging and starting the configuration.

Enable-DscDebug -BreakAll
Start-DscConfiguration .\temp\DSCTestClass -wait force

Notice that I started the DSC configuration using the ?wait parameter to make it run interactively so that I can see the output in the ISE console window. We see a warning message that tells us the resource script is stopped and waiting for a debugger to be attached. It then provides us with the command lines needed to connect to the computer, attach to the process, and debug a specific runspace. The first command (Enter-PSSession) is optional and not needed when debugging directly on the local machine. In this example I am working in a remote desktop to the target machine so I can skip this first command. I then open a new ISE window and run the next two provided commands in the ISE to get the debugging session. I like using the ISE for script file debugging because it provides a much nicer debugging experience when compared to the PowerShell console.

Keep in mind that you need to have Administrator permissions on the target machine in order to debug DSC scripts.

Enter-PSHostProcess -Id 944 -AppDomainName DscPsPluginWkr_AppDomain
Debug-Runspace -Id 4

We now have a live debugging session! Notice how the command line prompt changes after running each command. After the Enter-PSHostProcess command you see the prompt indicate that we have attached to process 944, which is the wmiprvse.exe process hosting the LCM. Then the Debug-Runspace cmdlet attaches the debugger to the runspace with Id 4 and the prompt shows [DBG] to indicate you are in a debugging session, [Process:944] because you are attached to that host process, and [Runspace4] to indicate the runspace you are debugging.

Also there is no resource script source file window open in the ISE yet. This is because that resource script has not run yet and so the ISE debugger doesn?t know about it. Instead we see in the ISE console the launching script that the LCM uses to run the first resource method ($global:DSCClassObject.Test()). We simply keep running the ?step into? debug command (F11 key) until the class method is run, and at this point the ISE opens the source script file.

From the above screen shot you can see that after pressing F11 three times the script calling $global:DSCClassObject.Test() method completed at which point the ISE found the source file, opened it in the debugger, and displayed the current execution point of the Test class method. Now we can step through the resource class code as it executes in the LCM by using the F10 and F11 keys. We can also set line breakpoints using the F9 key. And we can view variables. Awesome. I saw that the $present variable was false and since my configuration requires the file to be present I expect the Set method to be called next. I then pressed F5 key to let execution continue.

As expected we stopped next in the Set class method. Here I want to debug the CopyFile helper class method that does all of the work and so set a line breakpoint where it is called.

Important Note!

Once again I needed to press the F11 key three times to step through the script stub that runs the Set Method. This is because the LCM uses the same script stub to run each class method and you need to step through this code to get to the class method. Remember that break all debug mode stops at the first execution point. It is a blunt instrument but works. But additionally the LCM resets the runspace each time it runs a class method and, unfortunately, this also means all breakpoints are removed. So you cannot expect breakpoints to persist between each class method invocation and so you will need to set line breakpoints each time.

Wait-Debugger

The Enable-DscDebug ?BreakAll debugging mode is useful but can be a bit difficult to use, especially if you need to debug a specific method/function in complex resource code. At some point I hope that the LCM will support line breakpoints. But in the meantime there is one other technique you can use to help this situation involving the new Wait-Debugger cmdlet. What this cmdlet does is tell the PowerShell script execution engine to stop at the script execution point immediately after the Wait-Debugger cmdlet, and wait for a debugger to be attached. Basically it does the same thing as Enable-RunspaceDebug ?BreakAll but at a specific point in the script.

The downside to using Wait-Debugger is that you need to modify the source script. But if you are tracking down a difficult to find bug on a specific machine that you control, you can (temporarily) insert the Wait-Debugger cmdlet in the script code, attach the ISE debugger and do live script debugging at that point.

CAUTION: Make sure you remove the Wait-Debugger lines after you are done! Running script can appear hung when it is stopped at a Wait-Debugger if you forgot you added the cmdlet to your script. You certainly don?t want to have this cmdlet in production script!

Here I leave the LCM in BreakAll debug mode (Enable-DscDebug ?BreakAll) and then I just keep pressing the F5 run key until the ISE opens the source file where I inserted Wait-Debugger command. Notice that the current execution point is the line immediately after the Wait-Debugger. Now I have a live debug session exactly where I want!

Conclusion

DSC configuration is really great but also pretty complex. You create resource scripts to define configuration state but these scripts run on remote machines and in some arbitrary hosting process. Sometimes you require a live debugging session to ensure your script is working correctly. Now, with DSC debug mode and the new PowerShell advanced debugging features, you can debug your resource scripts while running in a live session on a target computer. This live debugging session is within the LCM process running in the LocalSystem context (Administration credentials are required), which is a great improvement over debugging your resource scripts on your local development machine.

Paul Higinbotham
Senior Software Engineer
Windows PowerShell Team

We’ve just updated the DSC Resource Kit for April!
Since our last update in February, there have been 107 merged pull requests with 49 closed issues.
Thanks to our wonderful community, the DSC Resource Kit now consists of 279 resources!

We have updated 21 DSC modules which include 6 new resources.

The updated modules are:

• xActiveDirectory
• xAzurePack
• xComputerManagement
• xCredSSP
• xDnsServer
• xDscDiagnostics
• xDSCResourceDesigner
• xFailOverCluster
• xFirefox
• xHyper-V
• xMySql
• xNetworking
• xPendingReboot
• xPSDesiredStateConfiguration
• xRemoteDesktopSessionHost
• xSCSMA
• xSharePoint
• xSQLServer
• xStorage
• xWebAdministration
• xWindowsUpdate

For a detailed list of what resources and fixes have been implemented, see the “What Has Recently Been Released?” section below.

We strongly encourage you to update to the newest version of all modules using the PowerShell Gallery, and don’t forget to give us your feedback in the comments below, on GitHub, or on Twitter (@PowerShell_Team)!

Where Can I Find All Released DSC Modules?

To see a list of all released DSC Resource Kit modules, go to the PowerShell Gallery and display all modules tagged as DSCResourceKit. You can also enter a module’s name in the search box in the upper right corner of the PowerShell Gallery to find a specific module.

Another way to find a specific module is to go directly to its URL on GitHub:
http://www.powershellgallery.com/packages/< Module_Name >
For example:
http://www.powershellgallery.com/packages/xWebAdministration

Of course, you can also always use PowerShellGet (available in WMF 5.0) to find modules with DSC Resources:

# To list all modules that are part of the DSC Resource Kit
Find-Module -Tag DSCResourceKit
# To list all DSC resources from all sources 
Find-DscResource

How Can I Install DSC Resources From the PowerShell Gallery?

We recommend that you use PowerShellGet to install DSC resource modules:

Install-Module -Name <Module_Name>

For example:

Install-Module -Name xWebAdministration

If you have previous versions of modules installed, you can update them all by opening an elevated PowerShell prompt and using this command:

Update-Module

After installing the modules, you can discover all of the resources available to your local system by running:

Get-DscResource

As with the previous Resource Kits, all the resources are experimental. The “x” prefix in the names stands for experimental – which means these resources are provided AS IS and are not supported through any Microsoft support program or service.

If there is an issue for a module you are particularly concerned about, watch the version number of the module in the PowerShell Gallery for updates. You can also file an issue against the module on GitHub to request a fix.

How Can I Find DSC Modules on GitHub?

We’ve open-sourced the development of DSC resources on GitHub. You can see the most recent state of all resources by going to their GitHub pages at:
https://github.com/PowerShell/< Module_Name >
For example, for the xCertificate module, go to:
https://github.com/PowerShell/xCertificate.

All DSC modules are also listed as submodules of the DscResources repository in the xDscResources folder so that you can see them in one place.

How Can I Contribute?

You are more than welcome to contribute to the development of DSC resource modules. There are several different ways you can help. You can create new DSC resources or modules, add test automation, improve documentation, fix existing issues, or open new ones. Most of the information you need to get started can be found in our contributing guide.

If you would like to help, please take a look at the list of open issues for the DscResources repository. You can also check issues opened for specific modules by going to:
https://github.com/PowerShell/< Module_Name >/issues
For example:
https://github.com/PowerShell/xPSDesiredStateConfiguration/issues

Your help in developing DSC is much appreciated!

What Has Been Recently Released?

You can see a detailed summary of all recent changes in the table below.
If you want to see a change log for previous versions, go to the GitHub repository page for a given module (see the “How Can I Find DSC Modules on GitHub?” section above for details).

Questions, comments?

If you’re looking into using PowerShell DSC, have questions or issues with a current resource, or would like a new resource, let us know in the comments below, on Twitter (@PowerShell_Team), or by creating an issue on GitHub.

Katie Keim
Software Engineer
PowerShell Team

Specifically, Bash on Windows is a developer tool. The idea here is that you’ve got some code that already works great on Linux that you’d like extend and hack on your Windows 10 machine. Or maybe you want to play with some Ruby gems that have some GNU utility dependencies. Drop into Bash, and have a field day.

It’s worth noting that this is not a platform for running or hosting production Linux workloads or server applications. It’s not for managing Windows Server workloads. Microsoft, the PowerShell Team, and the PowerShell community built extensive coverage for Windows, Windows Server, Active Directory, IIS, Exchange, SharePoint, System Center, SQL Server, Hyper-V, and Azure. In addition, we have a large partner ecosystem that supports PowerShell on both clients and servers, and this coverage is growing.

Of course, for those of us who love our developer workflows inside PowerShell, absolutely nothing will change. Bash and PowerShell are totally side-by-side. If you never type ‘bash’ in your console, literally zero will change for you as a PowerShell user.

Lastly, while Bash on Windows natively supports the Linux OpenSSH client, this complements our plans to deliver a native Win32 version of OpenSSH and to merge it upstream with the official OpenSSH repository. There are many advantages to having a Windows native SSH client, server, and toolchain, and we see huge value in supporting the official OpenSSH project in general. (In fact, you can check out our roadmap and progress on GitHub.)

We are incredibly excited about the plans we have for the future of PowerShell. PowerShell is a first-class scripting language, interactive console, remoting experience, and configuration management platform (DSC). Keep an eye on this space as we continue introducing new features, expanding our ecosystem, and growing our community. We welcome Bash on Windows as a fantastic addition to the Windows command-line ecosystem.

Joey Aiello
Program Manager, PowerShell

We have just released a brand new module called the AWS DSC Toolkit!
This module allows you to register AWS EC2 instances as DSC Nodes in Azure Automation.
You can then control your EC2 instances in Azure Automation using PowerShell DSC configurations.

The 4 new cmdlets provided by this module are:

• Register-EC2Instance
• Test-EC2InstanceRegistration
• Set-IAMInstanceProfileForRegistration
• Test-IAMInstanceProfileForRegistration

An example of these cmdlets is available here.

This module is currently in preview.
It is provided as is and is not supported through any Microsoft support program or service.

Installation

The AWS DSC Toolkit is available on the PowerShell Gallery.
You can install it using PSGet:

Install-Module AwsDscToolkit

The source code is also available on GitHub.

Credentials and Region

To use the cmdlets in this module, you will need to log in to your Azure account and provide AWS credentials as well as an AWS region.

You can easily log into your Azure account with this cmdlet:

Add-AzureRmAccount

By default, the cmdlets in this module will use the AWS credentials profile with the name ‘default’.

To specify the AWS credentials profile with the name ‘default':

Set-AWSCredentials -AccessKey 'MyAccessKey' -SecretKey 'MySecretKey' -StoreAs 'default'

To set the default AWS region:

Set-DefaultAWSRegion 'myRegion'

You can also specify your AWS credentials and region through the AwsAccessKey, AwsSecretKey, AwsProfile, and AwsRegion parameters on each of the cmdlets.

Register-EC2Instance

Registering a New Instance

To register a new instance to Azure Automation, use the Register-EC2Instance cmdlet with the New flag:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -New -InstanceProfile_Name 'MyInstanceProfileName' -SecurityGroup 'MySecurityGroup'

When the New flag is set, this cmdlet acts as a proxy for the AWS cmdlet New-EC2Instance. All parameters of New-EC2Instance are included in Register-EC2Instance -New except for those pertaining to user data (UserData, UserDataFile).

By default, Register-EC2Instance will create a t2.micro instance with the latest version of the AMI (Amazon Machine Image) with the name WINDOWS_2012R2_BASE.

Your new instance must have access to an AWS encryption key through the instance profile with the name specified by the InstanceProfile_Name parameter. For more information on this see the ‘IAM Instance Profile Requirements’ section below.

You new instance must also have a security group which will allow it to download the AWS DSC Bootstrapper and talk to Azure Automation. The default security create by this command will suffice:

New-EC2SecurityGroup -GroupName 'MySecurityGroup' -Description 'Security group for registration to Azure Automation'

This creates a default security with all outbound ports open and all inbound ports closed.

Registering an Existing Instance

To register an existing instance to Azure Automation, use the Register-EC2Instance cmdlet with the InstanceId parameter:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId'

Unfortunately, not all existing EC2 instances can be registered due to limitation with AWS permissions on existing instances. For more information on this, see the ‘Checking If an Existing Instance Can Register’ section.

Specifying a DSC Node Configuration at Registration Time

You can specify a DSC Node configuration on your Azure Automation account to apply to an EC2 instance immediately after registration using the NodeConfigurationName parameter:

Register-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId' -NodeConfigurationName 'MyConfiguration.Webserver'

You can also modify the behavior of DSC immediately after registration using the ConfigurationMode, ConfigurationModeFrequencyMins, RefreshFrequencyMins, RebootNodeIfNeeded, AllowModuleOverwrite, and ActionAfterReboot parameters.

By default these are set to the following values:

For more information on these values, see the PowerShell DSC documentation.

Test-EC2InstanceRegistration

This cmdlet will return an EC2InstanceRegistrationStatus enum value.
This new type is included with the module.

The 4 possible values are:

• CannotRegister
• NotReadyToRegister
• ReadyToRegister
• Registered

Checking If an Existing Instance Can Register

To check if your EC2 instance can register, use the Test-EC2InstanceRegistration cmdlet:

Test-EC2InstanceRegistration -InstanceId 'ExistingInstanceId'

If an Azure Automation account is not provided, this cmdlet will return CannotRegister, NotReadyToRegister, or ReadyToRegister.

CannotRegister

This value indicates that your instance does not have an IAM instance profile. AWS currently does not allow you to assign an IAM instance profile to an existing EC2 instance. To work around this, you can create an image of your existing instance and then create a new EC2 instance with an IAM instance profile from that image.

NotReadyToRegister

This value indicates that your instance has an IAM instance profile, but the instance profile does not have the correct permissions to register this instance. For more information on how to fix your IAM instance profile, see the ‘IAM Instance Profile Requirements’ section below.

Before a new instance created by Register-EC2Instance has finished registering, it may also return the NotReadyToRegister status since new instances do not require permission to use the AWS Run Commmand feature.

ReadyToRegister

This value indicates that the instance is correctly configured to register.
Before an existing instance has finished registering, it should return ReadyToRegister.

Checking If an Instance is Registered

To check if an instance is registered with your Azure Automation account, use the Test-EC2InstanceRegistration cmdlet with an Azure Automation account specified:

Test-EC2InstanceRegistration -AzureAutomationAccount 'MyAzureAutomationAccount' -InstanceId 'MyInstanceId'

This cmdlet will return an EC2InstanceRegistrationStatus enum value.

If the instance is registered, this value will be Registered.
If the instance is not registered or is still in the process of registering, it may return NotReadyToRegister or ReadyToRegister.

Please keep in mind that it usually takes about 10-20 minutes for an instance to register.
If you are using an instance that has an older WMF, it may take longer since the instance’s WMF will need to be updated to work with Azure Automation.

Registered

This value indicates that the instance is registered as a DSC node with the provided Azure Automation account.
Test-EC2InstanceRegistration will not check for the Registered status unless you provide an Azure Automation account.

IAM Instance Profile Requirements

In order to register any EC2 instance to Azure Automation, the Register-EC2Instance cmdlet will retrieve the registration key associated with your Azure Automation account. To keep this key safe, the cmdlet encrypts your key using an AWS encryption key associated with your AWS account. Any EC2 instances registering to Azure Automation Register-EC2Instance cmdlet must also have access to this encryption key in order to decrpyt your RegistrationKey. This access is given through an IAM instance profile.

In order to register an existing EC2 instance, the Register-EC2Instance cmdlet uses the AWS Run Command feature.
This means that to register an existing instance, the attached instance profile must have permission to use the Run Command feature. This is not required for instances created by the Register-EC2Instance cmdlet

Set-IAMInstanceProfileForRegistration

Once you have an encryption key on your AWS account, the Set-IAMInstanceProfileForRegistration cmdlet can create or modify an IAM instance profile to have the correct permissions to register a new or existing EC2 instance.

More information on how to create an encryption key is available here.

To modify or create a new IAM instance profile with the correct key access to register a new EC2 instance:

Set-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'

This will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile.

If an IAM instance profile with the name provided does not exist, this cmdlet will create one.
If the IAM instance profile with the name provided does exist, the profile will be modified with the proper permissions for registration.

The Set-IAMInstanceProfileForRegistration cmdlet will only provide access to Run Command when the ExistingInstance flag is set.
For example, to modify or create an IAM instance profile with access to encryption keys and permission to use run command:

Set-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance

If access has not already been granted, this will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile. This will also attached the AWS managed policy called ‘AmazonEC2RoleforSSM’ to a role in the specified instance profile.

This cmdlet returns an AWS IAM instance profile.

Test-IAMInstanceProfileForRegistration

To check if an IAM instance profile has the correct permissions to register a new EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet:

Test-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'

To check if an IAM instance profile has the correct permissions to register an existing EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet with the ExistingInstance flag:

Test-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance

This cmdlet will return a boolean value.
The permission to use Run Command may be removed from the instance profile once the instance has registered.

Over the past year, the PowerShell Team has released and developed a ton of open-source code. Many of our open-source projects started and have grown out in the open, like our DSC resources, PowerShell Script Analyzer, PowerShell Editor Services, and the PowerShell VS Code plugin. Others are existing open-source projects where we’ve started to contribute new code like OpenSSH, Pester, or PSReadline. However, until now, we have not open-sourced any core components of PowerShell that originally started as closed-source.

Today, we’re proud to announce that Microsoft.PowerShell.Archive, a module that shipped as a built-in component with PowerShell 5.0 on Windows 10 and with WMF 5.0, is now an open-source project on GitHub. Any work that we do on the Archive module will be done directly in its GitHub repository. You can also contribute to that open-source repository via pull requests (just like with our experimental DSC resources!) You can also file GitHub Issues against the Archive module for any bugs you might find or feature requests you have.

Don’t fret, our UserVoice is still our primary feedback portal (though you may see some Archive module requests also reflected on GitHub). In fact, we were driven to open-source the Archive module because of feedback we received from you, our community, via UserVoice. We’ve also recently simplified our guidance on UserVoice for how you file feedback and what our responses mean, so definitely hop over there and tell us what you want. Your suggestion could be the next thing we’re thrilled to announce.

We also have released a new version of Microsoft.PowerShell.Archive on the PowerShell Gallery. Currently, the only new functionality is that the Archive module now works on PowerShell 4.0 (another piece of UserVoice feedback that you gave us), but you’ll also be able to take advantage of any future innovations before they make their way into Windows 10 or Windows Server by updating Archive from the Gallery.

To install from the Gallery on PowerShell 4.0, you first have to install the PackageManagement module.

Now that you have PackageManagement installed (or if you’re running PowerShell 5.0+, which includes PackageManagement by default), you can install Microsoft.PowerShell.Archive from the Gallery:

Install-Module -Force Microsoft.PowerShell.Archive

It’s that easy!

We hope you’re as excited as we are to bring the Archive module into the world of open-source software, and I can’t wait to see what you can help us achieve together.

Joey Aiello
PM, PowerShell

Looking to develop PowerShell cmdlets for Nano Server? Try out our new PowerShell SDK for Nano on the PowerShell Gallery. Or, if you already have Windows 10 or Windows Management Framework 5.0 installed, simply run:

Install-Module Microsoft.PowerShell.NanoServer.SDK

If you’ve been watching the Server & Cloud Blog, you’ll know that we recently announced the availability of Technical Preview 5 of Windows Server 2016. And if you’ve also been following the Windows Server Blog, you will have noticed that last week marked the latest installment of the “10 Reasons You’ll Love Windows Server” series. Not surprisingly, in Jeffrey’s Top Ten for Windows Server 2016 are PowerShell & DSC and Nano Server.

As customers and partners have gotten a chance to try out the technical previews of Nano Server, we’ve had a number of people ask us how they can write cmdlets for PowerShell on Nano Server. The reason is that PowerShell on Nano Server is a little bit different than PowerShell on Windows 10 or Windows Server 2016 with Desktop Experience.

Starting with version 5.1 (the version included with Windows Server 2016), PowerShell is available in different editions which denote varying feature sets and platform compatibility.

• Desktop Edition: Built on .NET Framework and provides compatibility with scripts and modules targeting versions of PowerShell running on full footprint editions of Windows such as Server Core and Windows Desktop.
• Core Edition: Built on .NET Core and provides compatibility with scripts and modules targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano Server and Windows IoT.

Nano Server includes the PowerShell Core edition by default in all Nano Server installations. PowerShell Core functions in the same way as other editions of PowerShell, such as the Desktop edition of Windows PowerShell running on Windows 10 and Windows Server 2016 with Desktop Experience. However, the reduced footprint of Nano Server means that not all PowerShell features from Windows Server 2016 are available in PowerShell Core on Nano Server. The reduced footprint of .NET Core also means that not all existing cmdlets written in C# will run on PowerShell Core.

If you have existing PowerShell cmdlets that you’d like to run on Nano Server, or are developing new ones for that purpose, we’ve published the PowerShell Core SDK module to the PowerShell Gallery as well as a set of useful topics on TechNet to assist with developing cmdlets for Nano Server. You can install the SDK module using PowerShellGet:

Find-Module Microsoft.PowerShell.NanoServer.SDK -Repository PSGallery | Install-Module -Scope CurrentUser

The PowerShell Core SDK module exposes cmdlets to set up the correct .NET Core CLR and PowerShell Core reference assemblies, create a C# project in Visual Studio 2015 targeting those reference assemblies, and set up the remote debugger on a Nano Server machine so that you can debug .NET cmdlets running on Nano Server remotely in Visual Studio 2015.

The PowerShell Core SDK module requires Visual Studio 2015 Update 2. If you don’t have Visual Studio 2015 installed, you can install Visual Studio Community 2015. If you already have Visual Studio 2015, just make sure you have Update 2 or later installed. Also, the SDK module depends on the following feature to be installed in Visual Studio 2015:

Windows and Web Development -> Universal Windows App Development Tools -> Tools (1.3.1) and Windows 10 SDK

We suggest you review your Visual Studio installation before using the SDK module to ensure these prerequisites are satisfied. Make sure you select to install the above feature during the Visual Studio installation, or modify your existing Visual Studio 2015 installation to install it.

After you install the PowerShell Core SDK module, run Get-Command to take a look at the included cmdlets:

• New-NanoCSharpProject: Creates a new Visual Studio C# project targeting CoreCLR and PowerShell Core included in the Windows Server 2016 Technical Preview 5 release of Nano Server.
• Install-RemoteDebugger: Installs and configures the Visual Studio remote debugger on a Nano Server machine.
• Start-RemoteDebugger: Starts the remote debugger on a remote machine running Nano Server.
• Stop-RemoteDebugger: Stops the remote debugger on a remote machine running Nano Server.
• Show-SdkSetupReadMe: Opens the SDK root folder in File Explorer and opens the README.txt file for manual setup.

If you are writing new cmdlets, you should start with New-NanoCSharpProject – make sure to run this from the Package Management Console in Visual Studio. If you have existing cmdlets or like to set things up manually on your own, you can skip to the Show-SdkSetupReadMe cmdlet which describes how to set things up yourself.

If you get stuck or need more info, we also have some new topics published to TechNet to give you more details:

Developing PowerShell Cmdlets for Nano Server (START HERE)

PowerShell on Nano Server (including a list of what doesn’t work in TP5)

Getting Started with Nano Server

PowerShell Core SDK for Nano Server

As always, we welcome your feedback on our UserVoice site. Happy coding!

Dan Harman
PM, PowerShell