| description |
|---|
PowerShell scripts to execute within PowerShell Universal. |
PowerShell scripts can be created within PowerShell Universal to execute manually, on a scheudle or when events happen within the platform. They are stored on disk and also persisted to a local or remote Git repository.
{% hint style="info" %}
Script properties are stored in the scripts.ps1 configuration file.
{% endhint %}
To add a new script, you can click the New Script button within the Automation / Scripts page. There are various settings you can provide for the script.
.png)
Name of the script as shown in Universal Automation. This will also be the name used to persist the script to disk. This setting needs to be unique within the current folder.
See Modules and Commands below.
A description of the script. This is shown in various places within the UA UI and also returned by the Universal cmdlets.
Prevents a script from being run manually. This is enforced in the UI as well as the web server and cmdlets.
Defaults to 100. It defines the amount of jobs that are stored when running this script. Jobs are also cleaned up based on the server-wide job retention duration setting from within the Settings / General page.
Changes how the script reacts when there is an error within the script. By default, terminating and non-terminating errors are ignored and the script will always be successful. 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), you can use Write-PSUError to output the error record and it will appear in the error tab of the job.
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 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 will timeout. The default value of 0 means the script will run forever. Once a script reaches it's time out, it will be cancelled.
When checked, this will disable the storage of pipeline output. This will greatly reduce the CPU and storage overhead of jobs. The script will still write to the information, warning, and error streams.
Defines the maximum concurrent jobs the script can be run. Defaults to 100.
New-PSUScript -Name Script.ps1 -Path Script.Ps1 -ConcurrentJobs 1You can run a script in the UI by click the Run button the Automation / Scripts page or by clicking View and then Run. In each case, you will be presented with the Run Dialog that allows you to select various settings for the job.
.png)
{% hint style="info" %} Learn more about parameters here. {% endhint %}
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.
param(
$Test,
[DateTime]$Time,
[int]$Number,
[PSCredential]$Credential,
[System.ConsoleColor]$Color
)The result is a set of input options that are based on the types of parameters.
.png)
{% hint style="info" %} The integrated environment does not support running as alternate credentials. {% endhint %}
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 from within the run dialog.
.png)
You can use the Computer drop down to select other machines to run a script on. The default value is to run on any computer that is available.
You can run a script on all computers by selecting the All Computers option from the Computer drop down.
Note that 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 to define the description, a synopsis, parameter based help, and links for your scripts. These will be displayed within the PowerShell Universal UI.
<#
.SYNOPSIS
This is a script for pinging other computers.
.DESCRIPTION
This script can ping other computers.
.PARAMETER HostName
The host name or address to ping.
.LINK
https://www.ironmansoftware.com
#>
param($HostName)
Test-NetConnection $HostNameThis above will yield the following user interface. The synopsis will be shown as the short description and a longer description can be shown in the description section. Links will appear under the description.
.png)
Commands and cmdlets found in modules can be used at 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.
function Show-HelloWorld {
param($Name)
"Hello, $Name!"
}It's possible to expose this function as a script by using the following syntax in scripts.ps1.
New-PSUScript -Module 'PSUModule' -Command 'Show-HelloWorld'The function will be surfaced just as other scripts within the admin console. Parameters, help text and other PSU features will work the same as with scripts.
.png)
Parameter for a function