Note: This article describes in-detail Windows Scripts scripted actions.
See the Scripted Actions Article for General information on scripted actions.
Windows Scripts are scripted actions that are run directly on the Virtual Machine. They can be thought of as "logon scripts", except executed machine-wide and preformed as part of the provisioning process for creating or removing session hosts, or running commands against the Desktop Image VMs for installing/updating software and other tasks.
How it works
NMW uses the custom script extension to execute PowerShell code on the Virtual Machine.
Side note: (it also uses this for other tasks too, such as installing FSLogix and AVD agents).
The code is taken from the NMW scripted actions library, and then passed to the extension to be run on the VM. Certain variables are passed with it, such as $DesktopUser, which are defined depending on which VM NMW is passing the script to.
There are considerations to keep in mind. Most of these are applicable to custom script extension as a whole, so details can be found here: https://docs.microsoft.com/en-us/azure/virtual-machines/extensions/custom-script-windows#tips-and-tricks
1. Custom Script Extensions have a 90-minute timeout. This means that if a script is stuck or taking too long to complete, it will fail after 90 minutes. This is a limitation set by Azure. This also means that if a script is stuck prompting for user input, it will take 90 minutes to fail.
2. The script is run with administrative privileges, and does not interrupt other sessions. This means that most scripts are safe to run while users are on the VM.
3. Scripts that cause reboots will fail the entire process. The extension is waiting for the PowerShell script to complete fully, and if a reboot is started, it will fail. For actions which require restarts and then additional actions, split the script up into multiple scripts, and use "individual with restart" functionality, then place the rest of the scripts in order.
Troubleshooting the Extension
The major component of Windows Scripts is "custom script extension" (AKA "CSE" or "CSExtension"). Thus, most of the troubleshooting is essentially preformed using processes specific to it, as detailed here: https://docs.microsoft.com/en-us/azure/virtual-machines/extensions/custom-script-windows#troubleshoot-and-support
As mentioned in the MS Doc, C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension is the main location to first look for troubleshooting. It will contain the direct output of the code execution.
Testing the Code
It is recommended to use an isolated "development" session host, and running the scripts directly on the host to test your scripts. This will ensure that the powershell code itself is functional and preforms as desired, and provides quick results as opposed to running the commands through nerdio.