Windows Scripted Actions: Usage, Supported Features, and Considerations
Overview
This article provides information detailed information about the usage, supported features, and important considerations of Windows Scripted Actions. Windows Scripted Actions allow for custom script execution on Windows-based systems within the specified constraints and provide various options for parameter control.
Note: The model for Windows Scripted Actions execution has changed as of v5.3, so ensure that previously used Windows Scripted Actions remain functional. This change also affects the REST API. Instead of the "ScriptedActionsIds" field, use "ScriptedActions" for passing the list of Windows Scripted Actions. However, for backward compatibility, the "ScriptedActionsIds" field should also work, although it does not support passing parameters.
Custom Windows Scripted Actions Options
Support is available for custom Windows Scripted Actions options. This allows you to execute Windows scripts with specific configurations. Here are the current restrictions and supported options:
Supported Platforms
Only Windows scripts are supported. Azure Runbooks are not supported.
Script Execution Mode
Scripts can run in Individual or Individual with Restart modes.
Cloud PCs
Custom scripts are not supported on Cloud PCs.
Windows Scripted Actions Groups
Using scripts in Windows Scripted Actions Groups is not supported.
PowerShell Code Validation
Windows scripts include basic PowerShell code validation upon saving. This feature helps ensure that the script's code is syntactically correct and minimizes potential issues.
Supported Parameter Types and Controls
Windows Scripted Actions support a variety of parameter types, each with its own control in the UI.
`bool`, `switch`: Checkbox
`byte`, `sbyte`, `ushort`, `short`, `int`, `uint`, `long`, `ulong`, `float`, `double`, `decimal`: Number input with value bounds for each type
`char`, `string`: Text input
`string[]`: Multi-select
Supported Attributes
You can use the following attributes in your scripts:
`DisplayName`
`Description`
`Parameter`
`Mandatory`
`HelpMessage` (can override or be overridden by the "Description" attribute)
`ParameterSetName` (currently only for Nerdio Manager built-in parameters)
`ValidateSet` (for "string" type, replaces text input with a single select; for "string[]," sets available options)
JSON Parameters Definition
You can define parameters in your script using JSON notation. The structure for JSON parameter definitions is as follows:
{
"parameter_name_1": {
"DisplayName": "string",
"Description": "string",
"IsRequired": "bool",
"Type": "string",
"OptionsSet": [
{ "Value": "Any value that will be passed to the script parameter" },
{ "Value": "Other value", "Label": "Display name for this option, optional" }
]
},
"parameter_name_2": { ... }
}
Note: All parameters, as well as the JSON definition itself, are optional.
Using Built-in Nerdio Manager Parameters
Default variables are passed to Windows Scripted Actions by default. However, when including custom parameters, these variables must be defined using ParameterSetName or they are included in the scripted action.
To use built-in Nerdio Manager parameters, including `$AzureRegionName` and `$AzureSubscriptionName`, you can do the following:
Omit the "param" block, and the old behavior applies, which automatically passes built-in parameters to the script.
If you want to add a required built-in parameter to the "param" block with the proper name (as listed in the tooltip), type ("string" for most, "object" for `$SecureVars`), and specify `ParameterSetName = "NME_PARAMETER"`.
Example:
In this case, the parameter is hidden in the UI but automatically passed to the script by Nerdio Manager.
param (
[Parameter(ParameterSetName="NME_PARAMETER")]
[string] $AzureRegionName
)
Important Considerations
Ensure to check the correct operation of Windows Scripted Actions in various scenarios:
Run Windows Scripted Actions on hosts.
Run bulk Windows Scripted Actions on hosts.
Power off and set as an image.
Run Windows Scripted Actions on a desktop image.
Create a desktop image from a library.
Create a desktop image from a VM.
Clone a desktop image.
Host pool properties -> VM deployment tab.
Additional Resources
For usage examples and access to the new scripts, refer to the main repository where the new scripts are added after release.
Comments (0 comments)