Parameters

Jobs support automatically generating forms with parameters based on your script's param block. The type of control will change based on the type you define in the block. Parameters that are mandatory will also be required by the UI.

Basic Parameters

Parameters can be simply defined without any type of parameter attribute and they will show up as text boxes in the UI.

param($Test)

$Test

Parameters Types

Universal supports various types of parameters. You can use String, String[], Int, DateTime, Boolean, Switch and Enum types.

String

You can define string parameters by specifying the [String] type of by not specifying a type at all. Strings will generate a textbox.

param(
    [String]$Textbox,
    $Textbox2
)

String Arrays

You can specify string arrays by using the [String[]] type specifier. String arrays will generate a multi-tag select box.

param([String[]]$Array)

Date and Time

You can use the [DateTime] type specifier to create a date and time selector.

param([DateTime]$DateTime)

Boolean

You can use a [Bool] type selector to create a switch.

param([Bool]$Switch)

Integer

You can define a number selector by using the [Int] type specifier.

param([Int]$Number)

Switch Parameter

You can define a switch parameter using the [Switch] type specifier to create a switch.

param([Switch]$Switch)

Enumerations

You can use System.Enum values to create select boxes. For example, you could use the System.DayOrWeek to create a day of the week selection box.

param([System.DayOfWeek]$DayOfWeek)

PSCredential

When you specify a PSCredential , the user will be presented with a drop down of credentials available as variables.

param(
    [PSCredential]$Credential
)

File

You can allow users to upload files by using the [File] type.

param(
    [File]$File
)

Files will be available as a PSUFile object in your scripts. This object has a byte[] array that you can use to process the file.

For example, you can get the string content for the file by converting it using the Encoding classes.

[Text.Encoding]::UTF8.GetString($File.Content)

Display Name

You can use the DisplayNameAtrribute to set a display name for the script parameter.

param(
    [ComponentModel.DisplayName("My Script")]
    $MyScript
)

Help Messages

You can define help messages for your parameters by using the HelpMessage property of the Parameter attribute.

param(
    [Parameter(HelpMessage = "Class you want to enroll in")]
    [string]$Class
)

Required Parameters

You can use the Parameter attribute to define required parameters.

param(
    [Parameter(Mandatory)]
    $RequiredParameter
)

$RequiredParameter

Default Value

You can use both static and default values for parameters. The default value is calculated when the job is about to be run.

param(
    $Parameter = "Hello, World",
    [DateTime]$ExecutionTime = Get-Date
)

$Parameter
$ExecutionTime

Passing Parameters from PowerShell

You can pass parameters from PowerShell using the Invoke-PSUScript cmdlet. This cmdlet supports dynamic parameters. If you have a param block on your script, these parameters will automatically be added to Invoke-PSUScript.

For example, I had a script named Script1.ps1 and the contents were are follows.

param($MyParameter)

$MyParameter

I could then invoke that script using this syntax.

Invoke-PSUScript -Name 'Script.ps1' -MyParameter "Hello"

The result would be that Hello was output in the job log and pipeline.

Parameter Sets

PowerShell Universal supports parameter sets. When a parameter set is defined, a drop down is provided that allows for switching between the sets.

param(
    [Parameter(ParameterSetName = 'Set1')]
    $Parameter1,
    [Parameter(ParameterSetName = 'Set2')]
    $Parameter2
)

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.

Add a New Script

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.

Script Options

Name

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.

Description

A description of the script. This is shown in various places within the UA UI and also returned by the Universal cmdlets.

Disable Manual Invocation

Prevents a script from being run manually. This is enforced in the UI as well as the web server and cmdlets.

Manual Time

This setting is used to track the amount of time saved.

Max Job History

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.

Error Action

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.

Environment

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.

Timeout

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.

Anonymous

The anonymous setting allows the script to be run when the user is not authenticated. This is useful when using scripts in Pages.

Discard Pipeline

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.

Concurrent Jobs

Defines the maximum concurrent jobs the script can be run. Defaults to 100.

Running a Script

You 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.

Running a Script With Parameters

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 that are based on the types of parameters.

Running a Script as Another User

To run as another user, simply add or import a PSCredential variable. From there, you can select the credential from within the run dialog.

Running a Script on Another Computer

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.

Running a Script on All Computers

You can run a script on all computers by selecting the All Computers option from the Computer drop down.

Remoting

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.

Comment-Based Help

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.

This 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.

API