Update for the latest information regarding DSC Extension, refer to the product documentation.

……….

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": {
	"forcePullAndApply": false
        "downloadMappings": {
            "specificDependencyKey": "https://myCustomDependencyLocation"
        }
    } 
},
"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"
        }
    }
    "Privacy": {
        "DataCollection": "enable"
    },
    "AdvancedOptions": {
        "DownloadMappings": {
            "specificDependencyKey": "https://myCustomDependencyLocation"
        }
    }
},
"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.