Scripts
PowerShell scripts to execute within PowerShell Universal.
Last updated
PowerShell scripts to execute within PowerShell Universal.
Last updated
You can create PowerShell scripts within PowerShell Universal to execute manually, on a schedule, or when events happen within the platform. They are stored on disk and they persist to a local or remote Git repository.
The scripts.ps1 configuration file stores the Script properties.
To add a new script, click the New Script button within the Automation / Scripts page. There are various settings you can provide for the script.
This is the name of the script as shown in Universal Automation. This is also the name used to persist the script to disk. The name needs to be unique within the current folder.
See Modules and Commands below.
This description of the script shows in various places within the UA UI and is returned by the Universal cmdlets.
This prevents a script from running manually. This is enforced in the UI as well as the web server and cmdlets.
The max job history defines the amount of jobs stored when running this script. It defaults to 100. Jobs are also cleaned up based on the server-wide job retention duration setting from the Settings / General page.
The error action changes how the script reacts when it has an error. By default, terminating and non-terminating errors are ignored and the script always succeeds. You can change this setting to stop to cause scripts to fail immediately when an error is encountered.
If you wish to write errors directly to the error pane without causing changes in how the script is handled (for example in an exception handler), use Write-PSUError to output the error record and it appears in the job's error tab.
This allows you to define the required PowerShell environment for the script. By default, it uses the server-wide default PowerShell environment. PowerShell environments are automatically located the first time the Universal Server starts up or read from the environments.ps1 file. You can also add Environment on the Settings / Environments page.
The number of minutes before the script times out. The default value of 0 means the script will run forever. Once a script reaches its timeout, it is canceled.
When checked, this disables pipeline output storage. This greatly reduces jobs' CPU and storage overhead, but the script still writes to the information, warning, and error streams.
Defines the maximum concurrent jobs with which the script can be run. It defaults to 100.
You can run a script in the UI from the Automation / Scripts page by clicking Run or by clicking View and then Run. In each case, the Run Dialog appears, allowing you to select various settings for the job.
Learn more about parameters here.
PowerShell Universal automatically determines the parameters as defined within your scripts. It takes advantage of static code analysis to determine the type, default values and some validation that is then presented within the UI.
For example, you may have a script with the following parameters:
The result is a set of input options based on the types of parameters.
The integrated environment does not support running as alternate credentials.
You can run scripts as another user by configuring secret variables. PowerShell Universal uses the Microsoft Secret Management module to integrate with secret providers. See variables for more information on secrets.
To run as another user, simply add or import a PSCredential variable. From there, you can select the credential within the run dialog.
You can use the Computer dropdown to select other machines on which to run a script. The default value is to run on any available computer.
You can run a script on all computers by selecting the All Computers option from the Computer dropdown.
You can use PowerShell remoting by taking advantage of Invoke-Command . We do not support the use of Enter-PSSession or Import-PSSession.
You can use comment-based help to define the description, a synopsis, parameter-based help, and links for your scripts. These will be displayed within the PowerShell Universal UI.
The above yields the following user interface. The synopsis displays as the short description, and a longer description displays in the description section. Links appear under the description.
Commands and cmdlets found in modules can be used as the target for scripts rather than authoring the script directly.
Let's assume that we have a module called PSUModule that contains the following function.
It's possible to expose this function as a script by using the following syntax in scripts.ps1.
The function surfaces just like other scripts within the admin console. Parameters, help text and other PSU features work the same as with scripts.
