1 of 100

v5

About

The ultimate command center for your PowerShell environment.

PowerShell Universal provides a centralized location to store and run scripts, build modules, expose REST APIs and share them with end users via automatic or custom user interfaces, setup schedules and more.

APIs

Transform your PowerShell scripts into RESTful HTTP and WebSocket APIs for seamless integration across platforms. Leverage OpenAPI provide documentation and additional automation opportunities.

What's New in v5?

New features in PowerShell Universal v5.

New Admin Console

The admin console has been rebuilt using Blazor for ASP.NET. The look and feel are the same but more tightly associated with the backend Universal platform.

Portal

The provides a simple-to-use access point for consumers of PSU resources. You can assign resources by role, and they will be grouped by tags in a searchable interface without the complexities of the admin console.

Pages and Widgets

Portal and provide easy-to-use UI components that you can visually position on pages, which can be assigned to roles. Widgets are built using Blazor and PowerShell accept parameters, and they are interactive.

PowerShell Universal Gallery

The PowerShell Universal Gallery is now integrated directly in PowerShell Universal. Access pre-built solutions for your PowerShell Universal environment.

You can view the .

Granular Permissions

Authorization within the platform is now configured via a that controls which users have access to which resources. This also includes new roles for specific feature groups, so administrators do not need to configure privileges for every scenario.

PostgreSQL Support

PostgreSQL is now supported as a persistence store. PostgreSQL is open source and free.

Updated Runtimes

PowerShell Universal v5 is built on .NET 9 and PowerShell 7.5.

gRPC Cmdlets

The Universal module now uses gRPC for all communication with the system. gRPC is an interprocess communication technology that is fast and runs over HTTP. By unifying on a single technology, the cmdlets now take advantage of all the granular privileges and help reduce technical debt in the platform.

Windows PowerShell 5.1 and PowerShell 7 Environments

The Agent environment has been replaced with Windows PowerShell 5.1 and PowerShell 7 environments. These environments host the PowerShell engine, but they allow for better control of assembly loading to ensure more modules are compatible with PowerShell Universal.

Additional Resources

Additional PowerShell Universal resources.

The Ironman Software blog has articles about PowerShell Universal.

Uninstall

Uninstall PowerShell Universal

Application Files

Depending on how you installed PowerShell Universal, you will need to uninstall the application files.

ZIP Installation

If you installed using a provided ZIP file, you can simply stop the PowerShell Universal process or service and delete the folder you extracted to.

MSI Installation

If you installed with the Windows MSI, uninstall the application from Add\Remove Programs.

Module Installation

The Universal module installs the application files to the following locations by default.

Windows

%ProgramData%\PowerShellUniversal

Linux and Mac OS

%HOME%/.PowerShellUniversal

Configuration Files

Configuration files are stored in the repository folder. Once you have removed the application files, you can delete the configuration files. They are stored in the following locations by default:

Windows

%ProgramData%\PowerShellUniversal
%ProgramData%\UniversalAutomation

Linux

%HOME%/.PowerShellUniversal/

Mac OS

%HOME%/.PowerShellUniversal/

Desktop

%AppData%\PowerShellUniversal

Database

Removing the database depends on the database type used.

SQLite

SQLite databases are stored in a single file on the file system.

Windows

%ProgramData%\PowerShellUniversal\database.db

Linux and Mac OS

%HOME%/.PowerShellUniversal/database.db

PostgreSQL and SQL

PostgreSQL and SQL databases are stored on your SQL server and will require you to manually remove the database.

IIS

You need to remove the IIS App Pool and Website when removing PowerShell Universal. Note that App Pools can be shared amongst websites and caution should be taken when doing so.

Downgrade

Learn how to revert to a downgrade level of PowerShell Universal.

In some scenarios it may be required to roll back the version of PowerShell Universal. This could be due to a feature change or bug that affects the system in a way too impactful to continue with the version. We validating a version in a development or quality assurance environment before upgrading in production to avoid having to perform a downgrade.

Downgrading can be complicated and error prone. We recommend restoring from a backup or snapshot instead of downgrading.

Supported Browsers

Universal uses a variety of modern web frameworks and can have issues with older browsers such as Internet Explorer.

Recent versions of the following web browsers are supported: Chrome, Firefox, Safari, and Microsoft Edge.

When considering a browser, you will need to understand that certain features are required. They include:

Release Support Policy

PowerShell Universal recently migrated from a static, two-year support policy for releases to a standard and long-term support policy based on the underlying frameworks that the platform is built upon.

Support Policy

Starting with version 6, PowerShell Universal will provide long term support options pinned to the underlying support policy of the .NET SDK. Microsoft provides support for .NET versions for 18 months on standard support releases and 36 months on long-term support releases. PowerShell Universal runs on a similar support policy.

Version 5 is the last version on the historical, arbitrary support policy per major version. It will be supported until August 2026. Please see the below table for upcoming release support. Support is the same for each release type but varies based on the life time.

Version

Release Date

End of Support

Support Type

API

About

About PowerShell Universal REST APIs.

Universal provides the ability to define REST API endpoints using PowerShell. When the endpoints are executed by a compatible HTTP client, the PowerShell script will execute and return the result to the end user.

This feature is for developing custom APIs run by Universal. It is not required for managing Universal. Universal provides a set of management APIs that are included with the platform.

Execution Environment

The REST API execution environment runs in your default PowerShell version. Unlike Automation jobs, which can also be run via the Universal management API, APIs that you define are run in a single PowerShell process. Because the PowerShell process is not started and stopped for each call to the endpoint, the API is much faster.

You can define the that runs the PowerShell Universal API process by specifying the -ApiEnvironment on Set-PSUSetting. Changing this setting will cause the API process to restart.

Per Endpoint Environment

You can also define the environment used by specifying the Environment on the endpoint itself.

Performance

Performance is relative to the hardware and network conditions that you are running Universal on. That said, in ideal conditions you can expect the Universal APIs to service about 500 requests per second. This is with an entirely empty endpoint so any script that you add to that endpoint will reduce the throughput. The reduction of throughput will depend on the cmdlets and script executed within the API endpoint. There is no hard limit.

See for detailed information about benchmark tests on Universal APIs.

Variables

Variables are listed on the .

API

Event Hubs

Receive client events from the PowerShell Universal server.

Event Hubs require a .

Event Hubs provide the ability to connect client to the PowerShell Universal server. Once connected, the PowerShell Universal server can send messages to the connected clients and they will run a local PowerShell script block.

Creating an Event Hub

Rate Limiting

Rate limiting options for Universal.

Rate limiting requires a .

PowerShell Universal lets you rate limit requests made to the web server. You can configure rate limiting per endpoint and per period. By default, the client IP address rate limits clients.

Configuration data for rate limits are stored in the ratelimits.ps1 file.

Automation

About Automation

Run and schedule scripts with automation

Run Scripts

You can run in PowerShell Universal. PowerShell Universal integrates deeply with the PowerShell host to provide a UI for param blocks, output rich objects, display progress and even allow the user to provide feedback.

Terminals

In-browser PowerShell terminals.

Terminals require a .

Terminals are in-browser PowerShell consoles that you can execute arbitrary commands within. Terminals are configured to target an environment that you select and can optionally us Run As credentials to run as other users. The history of terminals is maintained within the PowerShell Universal database. You can reconnect to disconnected terminals as long as they haven't timed out.

Terminal configurations are stored in terminals.ps1

Tests

PowerShell Universal automated test support.

This feature requires a .

PowerShell Universal integrates with the test framework to allow you to execute test suites and view results. Results are stored in the PowerShell Universal database so you can view historical results.

You can work with tests by visiting Automation \ Tests.

Apps

About

Create web applications in PowerShell using PowerShell Universal Apps.

Apps are individual websites created with PowerShell Universal. They take advantage of a large set of pre-defined cmdlets for all kinds of components and interactive features. You can use apps to create dynamic websites that meet any need you can think of. Some common apps are:

Disparate Data Grouped into Tables and Data Grids
End User Onboarding Tools
UI Tools for System Management without Elevated Credentials

For a full list of real-life examples, .

Apps should be considered an advanced feature and require both knowledge of the PowerShell Universal app cmdlets as well as a decent knowledge of PowerShell itself. With that said, they provide the greatest level of customization for web apps in PowerShell.

Data Display

Alert

Alert component for Universal Apps.

Alerts provide a simple way to communicate information to a user.

Simple Alerts

Alerts have four different severities and can include text or other content.

New-UDAlert -Severity 'error' -Text 'This is an error alert — check it out!' 
New-UDAlert -Severity 'warning' -Text 'This is an warning alert — check it out!'
New-UDAlert -Severity 'info' -Text 'This is an error info — check it out!' 
New-UDAlert -Severity 'success' -Text 'This is an success alert — check it out!'

Advanced Alerts

Alerts can contain any component and also a title.

API

Badge

Badges component for Universal Apps.

Basic Badge

Examples of badges containing text, using primary and secondary colors. The badge is applied to its children.

Chip

Chip component for Universal Apps.

Chips are compact elements that represent an input, attribute, or action.

Chips allow users to enter information, make selections, filter content, or trigger actions.

While included here as a standalone component, the most common use will be in some form of input, so some of the behavior demonstrated here is not shown in context.

Basic Chips

Date and Time

Date and time component for Universal Apps.

The New-UDDateTime component is used for formatting dates and times within the client's browser. By using the client's browser, you can format the time based on the local time zone and locale settings for the user.

The output of New-UDDateTime cannot be used with components like New-UDHtml, New-UDMarkdown or Show-UDToast. The object returned by New-UDDateTime needs to run JavaScript within the browser and is not an actual DateTime object.

The date and time component uses DayJS. For a full list of custom formatting options, visit the .

Basic Formatting

By default, the date and time will be formatted using the LLL localized formatting template.

Resulting output: August 16, 2018 8:02 PM

Custom Formatting

You can specify custom formatting strings using the .

Resulting output: 25/01/2019

Locale

You can specify the locale to display the date and time in.

Resulting output: 13 de septiembre de 2022 7:30

API

List

List component for Universal Apps.

Lists are continuous, vertical indexes of text or images.

Lists are a continuous group of text or images. They are composed of items containing primary and supplemental actions, which are represented by icons and text.

List

New-UDList -Content {
    New-UDListItem -Label 'Inbox' -Icon (New-UDIcon -Icon envelope -Size 3x) -SubTitle 'New Stuff'
    New-UDListItem -Label 'Drafts' -Icon (New-UDIcon -Icon edit -Size 3x) -SubTitle "Stuff I'm working on "
    New-UDListItem -Label 'Trash' -Icon (New-UDIcon -Icon trash -Size 3x) -SubTitle 'Stuff I deleted'
    New-UDListItem -Label 'Spam' -Icon (New-UDIcon -Icon bug -Size 3x) -SubTitle "Stuff I didn't want"
}

OnClick Event Handler

You can define an action to take when an item is clicked by using the -OnClick parameter of New-UDListItem.

API

Markdown

Markdown display for Universal Apps.

New-UDMarkdown accepts a markdown string and renders it as HTML elements within a dashboard.

New-UDMarkdown -Markdown "
   # Header
   - List Item 1
   - List Item 2
   
   ## Sub Header
"

Markdown in Paper

When using New-UDPaper, you will need to override the default display type of the paper to avoid formatting issues.

$m=@'
# Hello

## world
- a
- b
-c
'@

New-UDPaper -Elevation 7 -Children {
   New-UDMarkdown -markdown $m
} -Style @{
   display = 'block'
}

API

New-UDMarkdown

Tooltip

Tooltip component for PowerShell Universal Apps.

Tooltips display informative text when users hover over an element.

Placement

Place the tooltip on

Tree View

Tree view component for Universal Apps.

New-UDTreeView allows you to create a tree of items and, optionally, dynamically expand the list when clicked.

Basic Tree View

Create a basic tree view by using the New-UDTreeNode cmdlet.

Typography

Typography component for Universal Apps

Use typography to present your design and content as clearly and efficiently as possible.

Too many type sizes and styles at once can spoil any layout. A typographic scale has a limited set of type sizes that work well together along with the layout grid.

All Typography Types

@("h1", "h2", "h3", "h4", "h5", "h6", "subtitle1", "subtitle2", "body1", "body2", 
"caption", "button", "overline", "srOnly", "inherit", 
"display4", "display3", "display2", "display1", "headline", "title", "subheading") | ForEach-Object {
    New-UDTypography -Variant $_ -Text $_ -GutterBottom
    New-UDElement -Tag 'p' -Content {}
}

Colored Text

You can use the -Style parameter to define colors for your text.

Theme-based Styling

You can use styling by using the -Sx parameter of New-UDTypography. For example, to apply the secondary text color, you can use the following syntax.

API

Data Visualization

Image

Image component for apps.

Image by URL

Display an image based on a URL. You can host URLs using .

Image by Path

Display an image based on a file local to the server.

Feedback

Backdrop

Backdrop component for Universal Apps.

The backdrop component places an overlay over the drop of the entire page. It's useful for displaying loading states.

Basic Backdrop

To create a basic backdrop, you can use the New-UDBackdrop cmdlet and include content to show within the backdrop. The content will be centered on the page. To show the backdrop, use the -Open switch parameter.

Progress

Progress component for Universal Apps

Circular Progress

New-UDProgress -Circular -Color Blue

Linear Indeterminate

Linear Determinate

API

Skeleton

A skeleton component for PowerShell Universal Apps.

A skeleton is a form of a loading component that can show a placeholder while data is received.

Variants

There are three variants that you can use for a skeleton. You can use a circle, text or a rectangle. You can also define the height and width of the skeleton.

New-UDSkeleton
New-UDSkeleton -Variant circle -Width 40 -Height 40
New-UDSkeleton -Variant rect -Width 210 -Height 118

Animations

Skeletons will use the pulsate animation by default. You can also disable animation or use a wave animation.

API

Inputs

Input controls for Universal Dashboard

Autocomplete

Autocomplete component for Universal Apps

The autocomplete is a normal text input enhanced by a panel of suggested options.

Static List of Options

Creates a basic autocomplete with a static list of options

Button

Button component for Universal Apps

Buttons allow users to take actions, and make choices, with a single tap.

Contained Button

Contained buttons are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app.

Checkbox

Check component for Universal Apps

Checkboxes allow the user to select one or more items from a set.

Checkboxes

Checkboxes can be disabled and checked by default

Checkboxes with custom icon

Create checkboxes that use any icon and style.

Checkboxes with onChange script block

Create checkboxes that fire script blocks when changed.

Checkbox with custom label placement

You can adjust where the label for the checkbox is placed.

Get the value of a Checkbox

You can use Get-UDElement to get the value of the checkbox. Get-UDElement will also return other properties of the checkbox component.

The following example shows a toast message with the value of the checkbox.

API

Date Picker

Date Picker component for Universal Apps

Date pickers pickers provide a simple way to select a single value from a pre-determined set.

Date pickers can be used in Forms and Steppers.

OnChange Event Handler

The OnChange event handler is called when the date changes. You can access the current date by using the $Body variable.

Variant

You can customize how the date picker is shown. The default is the inline variant that displays the date picker popup in line with the input control. The static variant displays the date picker without having to click anything.

Locale

To set the locate of the date picker, specify the -Locale parameter.

Minimum and Maximum

By default, the user can select any date. To specify minimum and maximum dates, using the -Minimum and -Maximum parameters.

Views

You can limit which portions of the date picker are included by using the -Views parameter. For example, if you wanted to remove the year selector and limit to the current year, you could do the following.

API

Floating Action Button

Floating action button component for Universal Apps

A floating action button (FAB) performs the primary, or most common, action on a screen.

A floating action button appears in front of all screen content, typically as a circular shape with an icon in its center. FABs come in two types: regular, and extended.

Only use a FAB if it is the most suitable way to present a screen’s primary action.

Only one floating action button is recommended per screen to represent the most common action.

Floating Action Button

New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Small
New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Medium
New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Large

OnClick

API

Radio

Radio component for Universal Apps

Radio buttons allow the user to select one option from a set.

Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a dropdown menu because it uses less space.

Radio buttons should have the most commonly used option selected by default.

Simple Radio

Rating

Rating input component.

Basic Rating

New-UDRating

OnChange

Take action when the rating is changed.

Maximum

Change the maximum rating.

Precision

Change the precision for ratings.

Size

Change the size of the rating icons.

Slider

Slider component for Universal Apps.

Sliders allow users to make selections from a range of values.

Sliders reflect a range of values along a bar, from which users may select a single value. They are ideal for adjusting settings such as volume, brightness, or applying image filters.

Slider

Switch

Switch component for Universal Apps

Switches toggle the state of a single setting on or off.

Switches are the preferred way to adjust settings on mobile. The option that the switch controls, as well as the state it’s in, should be made clear from the corresponding inline label.

Switch

Create a basic switch.

Time Picker

Time picker component for Universal Apps

Time pickers pickers provide a simple way to select a single value from a pre-determined set.

Time Picker

New-UDTimePicker

Locale

Specify the locale of the time picker.

24-Hour Time

You can use the -DisableAmPm parameter to use 24-hour time.

API

Navigation

Drawer

Drawer component for Universal Apps

Permanent Drawer

A permanent drawer will be shown at all times. By default, it is show on the left side of the screen.

New-UDDrawer -Variant 'permanent' -Content {
  New-UDList -Children {
        New-UDListItem -Label "Home"
        New-UDListItem -Label "Getting Started" -Children {
            New-UDListItem -Label "Installation" -OnClick {}
            New-UDListItem -Label "Usage" -OnClick {}
            New-UDListItem -Label "FAQs" -OnClick {}
            New-UDListItem -Label "System Requirements" -OnClick {}
            New-UDListItem -Label "Purchasing" -OnClick {}
        }
    }
}

API

Link

Link component for Universal Apps.

Create a hyper link in a dashboard.

Basic Link

Create a basic link that goes to a web page.

New-UDLink -Text 'Ironman Software' -Url https://www.ironmansoftware.com

Change Style

Adjust the underline and text style.

Open in a New Window

Open the link a new window when clicked.

OnClick Event Handler

Execute a PowerShell script block when the link is clicked.

API

Tabs

Tab component for Universal Apps

Tabs make it easy to explore and switch between different views.

Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.

Tabs

Layout

Grid Layout

Drag and drop layout designer.

Grid Layout

The Grid Layout component is useful for defining layouts in a visual manner. You can drag and drop components using the web interface to automatically define the layout as JSON.

Hidden

Quickly and responsively toggle the visibility value of components and more with the hidden utilities.

How it works

Hidden works with a range of breakpoints e.g. xsUp or mdDown, or one or more breakpoints e.g. -Only 'sm' or -Only @('md', 'xl'). Ranges and individual breakpoints can be used simultaneously to achieve very customized behavior. The ranges are inclusive of the specified breakpoints.

Up

Using any breakpoint -Up parameter, the given children will be hidden at or above the breakpoint.

Down

Using any breakpoint -Down parameter, the given children will be hidden at or below the breakpoint.

Only

Using the breakpoint -Only parameter, the given children will be hidden at the specified breakpoint(s).

The -Only parameter can be used in two ways:

list a single breakpoint
list an array of breakpoints

API

Stack

Stack components in one dimesion.

The Stack component manages layout of immediate children along the vertical or horizontal axis with optional spacing and/or dividers between each child.

Horizontal Stack

Horizontally stacked items.

New-UDStack -Content {
   New-UDPaper -Content { "Item 1" } -Elevation 3
   New-UDPaper -Content { "Item 2" } -Elevation 3
   New-UDPaper -Content { "Item 3" } -Elevation 3
} -Spacing 2

Vertical Stack

Vertically stacked items.

API

Utilities

Dynamic Regions

Dynamic regions allow you control the reload of data within the region.

New-UDDynamic allows you to define a dynamic region. Pages themselves are dynamic in nature. This means that every time a page is loaded, it runs the PowerShell for that page. Sometimes, you may want to reload a section of a page rather than the whole page itself. This is when you will want to use dynamic regions.

Basic Dynamic Region

This dynamic region reloads when the button is clicked.

Error Boundary

Error boundary component for apps.

The New-UDErrorBoundary component is used for isolating portions of a dashboard to contain components that may throw an error. Many app components use the error boundary component internally.

If you'd like to isolate a portion of your app to prevent the entire page from failing to load, you can use the following syntax.

If any error is thrown from the content, you will see an error such as thing.

API

Protect Section

Protect sections based on roles.

The Protect-UDSection cmdlet hides it's content if a user does not have the specified roles.

Protect-UDSection -Role @("Administrator") -Content {
   New-UDTypography -Text 'Only Administrators see this'
}

HTML

Define static HTML using Univeral apps.

You can define static HTML using New-UDHtml. This cmdlet does not create React components but rather allows you to define static HTML. Any valid HTML string is supported.

The following creates an unordered list.

Modifying the <head> tag

You can use the New-UDHelmet component to add new tags to the <head> of the HTML document. This is useful for loading custom JavaScript or CSS libraries.

Surfaces

Expansion Panel

Expansion Panel component for Universal Apps

Expansion panels contain creation flows and allow lightweight editing of an element.

An expansion panel is a lightweight container that may either stand alone or be connected to a larger surface, such as a card.

Simple Expansion Panel

Scripts

PowerShell scripts to execute within PowerShell Universal.

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.

Add a New Script

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.

Script Options

Name

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.

Module and Command

See below.

Description

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

Disable Manual Invocation

This prevents a script from running manually. This is enforced in the UI as well as the web server and cmdlets.

Max Job History

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.

Error Action

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.

Environment

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.

Timeout

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.

Discard Pipeline

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.

Concurrent Jobs

Defines the maximum concurrent jobs with which the script can be run. It defaults to 100.

Running a Script

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.

Running a Script With Parameters

Learn more about 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 based on the types of parameters.

Running a Script as Another User

The integrated does not support running as alternate credentials.

You can run scripts as another user by configuring . PowerShell Universal uses the Microsoft Secret Management module to integrate with secret providers. See variables for more information on secrets.

Create a new PSCredential secret variable.

Click Platform \ Variables and then click Create Secret. Select the PSCredential variable type. Enter the username and password. Ensure that the Disable Run As Support value is unchecked.

Run the Script and select the credential

Navigate back to Automation \ Scripts and click the Run Script button. Select an environment besides the Integrated environment. By default, this will be either PowerShell 7 or Windows PowerShell 5.1.

You will now be prompted with the Run As drop down to select the credential. From there, you can select the credential within the run dialog.

Running a Script on Another Computer

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.

Running a Script on All Computers

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

Running a Script from an App with Output

If you would like to run a script from an app and display the output as it runs, using the following example. It takes advantage of Invoke-PSUScript and Get-PSUJobOutput.

Load Balancing

PowerShell Universal uses a least-busy server loading balancing algorithm. If more than one server is a valid target for a job, PowerShell Universal will select the server with the least number of jobs running on that server.

Remoting

You can use PowerShell remoting by taking advantage of Invoke-Command . PowerShell Universal does not support the use of Enter-PSSession or Import-PSSession.

Comment-Based Help

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.

Modules and Commands

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.

Statistics

Using a script's job history, PowerShell Universal will provide basic statistics about the execution of the script. These include success rate, average execution time, and breaks downs of environment, user and computer execution.

Start-Job Support

While it's possible to start jobs using Invoke-PSUScript, it may be desirable to start a job using the PowerShell Start-Job cmdlet. Using Start-Job does not register the job with PowerShell Universal and the execution information will not be present in the jobs table.

The Integrated, PowerShell 7 and Windows PowerShell 5.1 environments are not compatible with Start-Job because they are custom PowerShell hosts. In order to use Start-Job, you will need to configure a custom PowerShell environment. Click Settings \ Environments. Next, click Create New Environment. Name the environment, select the Custom environment type and specify pwsh.exe as the executable path.

You will now be able to use this environment to run the Start-Job cmdlet.

API

Upgrade

This document covers upgrading the PowerShell Universal application.

Overview

This document will cover the upgrade process for production PowerShell Universal instances. We will cover the following topics.

Data Backup
Upgrade Process
Upgrade Validation

The Universal application binaries can generally be upgraded without having to change the configuration or database manually, but we do recommend backups of production data.

Recommendations

For production environments, we recommend deploying PowerShell Universal to a staging or development environment prior to major upgrades. This allows for testing before end users are affected. You can use to test changes in PowerShell Universal instances without purchasing another license.

1. Data Backup

PowerShell Universal uses a script-based configuration system alongside a database used for retention of entities such as app tokens, job history and identities. If possible, you will want to backup these items before running an upgrade for easy rollback in case an issue is encountered during validation.

Database

Backing up the database ensures that all apptokens, job history, identities and database secrets are retained in the case of an upgrade failure. SQL databases also may adjust the schema of the database and may require a rollback of not only the data, but also the schema of the tables in the database.

SQLite

By default, PowerShell Universal uses a single file database called SQLite. Unless configured otherwise, the database is stored in %ProgramData%\UniversalAutomation. You should have a database.db and possibility a database-log.db. Both of these files should be backed up. The service must be stopped in order to back up the files.

SQL

When using SQL for persistence, backup the entire database (including schema). There isn't necessarily a need to stop the PowerShell Universal service when backing up the database, but it may continue to write to the database (for example when running scheduled jobs) after the backup has been completed.

Configuration Scripts

Scripts make up the main configuration data to backup when upgrading a production PowerShell Universal instance. For production, we recommend using a version control system. You can also take advantage of the built-in git integration. If you are using a two-way sync for PowerShell Universal git integration, consider tagging your git branch prior to the upgrade to allow for easy rollback to unexpected changes within the git repository.

2. Upgrade Progress

Below are sections for each type of system upgrade and the steps that you should take based on how you originally installed PSU.

MSI

When installing via the MSI, you will want to follow the same backup procedures above.

appsettings.json

You will want to back up the appsettings.json file stored in %ProgramData%\PowerShellUniversal. This file contains information such as port, data storage location and other server settings. Typically, the MSI will not make changes to this file once created. It will use the settings found for the upgraded version. That said, if necessary, the MSI will make changes to the appsettings file. These changes are considered breaking and will be listed in the changelog for the release.

Service Account

When running an MSI upgrade, the PSU service is not uninstalled, and thus, the service account will still be set once the service starts up.

If you perform an uninstall and then an install using the MSI, then the service account will be removed.

Upgrade Process

Once all the configuration files and the database are backed up, you can run the new MSI installer.

For major upgrades (e.g. v4.3.4 to v5.0.4 etc), you will need to uninstall the previous version prior to running the new version.

The installer may prompt for a restart of the machine if files are locked. The PSU MSI will uninstall all the files in the installation directory and install entirely new files.

Once the MSI has completed, you can navigate to your PowerShell Universal admin console to perform installation validation.

IIS

Below you will find information about upgrading an IIS install.

web.config

In addition to the files listed to backup above, you will also want to consider backing up your web.config file. If you have made no changes to this file, you do not need to back it up.

The web.config file that is included in the application installation directory will be overwritten during upgrades. If you have moved your web.config file to an alternate location, it will not be overwritten. When creating an IIS website, you can simply include the web.config file in the web app's directory and have the .

Upgrade Process

When upgrading with IIS, you will need to first stop your application pool to ensure that the binaries used by IIS are no longer in use and then replace the binaries with the new ones. To ensure that the upgrade works as expected, it's recommended to delete all the application files and then unzip the new ones into the same directory to avoid assembly conflicts.

As with any installation from a ZIP file, make sure that you run Get-ChildItem -Recurse | Unblock-File from an elevated command prompt across the PowerShell Universal files to ensure they can be executed properly.

Once you have copied the new files and unblocked them, start the app pool, navigate to the PowerShell Universal Admin Console and perform installation validation.

Universal Module

The Universal module can be used to upgrade installations of PowerShell Universal previously installed by the module.

Do not use the Universal module to upgrade instances installed via MSI.

Follow the backup procedures above and then perform the upgrade.

First, upgrade the local PowerShell Universal module and verify the expected version is installed.

Next, run Update-PSUServer to download and unzip the new PSU instance.

After the upgrade is complete, navigate to the PowerShell Universal Admin Console and begin upgrade validation.

ZIP

Perform the necessary backup procedures and download the latest ZIP of PowerShell Universal.

Stop the PowerShell Universal service. Delete the existing PowerShell Universal application files. Extract the ZIP files to the same directory. Finally, run Unblock-File against the directory to ensure that PSU can execute properly. Always run this command as administrator.

After the upgrade is complete, navigate to the PowerShell Universal Admin Console and begin upgrade validation.

Database

By default, the PSU service will migrate to the latest database version during the startup process.

The database can also be upgraded before upgrading the application. This is recommended for larger installations that may require some time for the schema update to take place. In some environments, allowing the service to upgrade the database can result in a timeout, like with Service Control Manager in Windows.

If you are using SQL, you can find SQL files generated and placed in the SQL folder within the PSU installation media. Run these scripts against your database before upgrading.

All types of databases support the psu command line tool for upgrades.

3. Upgrade Validation

After running an upgrade, you should perform basic validation against your PSU server to ensure that it is fully functional.

Notifications

Verify that there are no errors within the notification drop down. They may be a sign of issues during the upgrade.

Modules

Upgrades to PowerShell Universal may change assembly versions of DLLs shipped with the platform. This can cause other modules to fail to load. While this may not be obvious at first, you may consider taking an inventory of modules used in your platform to ensure that the versions are consistent before and after the upgrade to limit changes.

If you have installed a version of the Universal module outside of PowerShell Universal (for example, with Install-Module), you must make sure to update the module or it can conflict with the new one installed with PowerShell Universal.

Apps

The most common upgrade issues come due to changes in the Universal App framework. Apps can be complex and bug fixes or features can sometimes cause for certain user's app while fixing issues pertaining to another user's app. Please read the changelog before upgrading to understand the impact of changes made to the app framework and consider testing the app with development data before upgrading in production.

Nightly Builds

When using nightly builds, you cannot upgrade from one nightly version to another. You can upgrade from a generally available version to a nightly version. In order to test a new nightly build, you will need to uninstall the current nightly build, rollback the database schema and then install the new version. You can roll back the database schema with psu.exe .

Common Upgrade Issues

IIS App Pool Does Not Start After Upgrade

The most common upgrade issue is that Unblock-File is not called properly on the extracted files when performing an upgrade of a IIS ZIP install. Also make sure to run the Unblock-File command recursively and from within an administrative session.

Another command issue is extracting the files over the top of the existing files. This can cause assembly conflicts and puts the application in an unknown state. Follow the IIS upgrade documentation and delete the files before extracting them.

Command Not Found Errors

When new functionality is added to PowerShell Universal it is typically done using new cmdlets. If older versions of the PowerShell Universal module are installed on the system, it can cause conflicts with the one shipped within the installation media. Ensure that you have removed older versions of the Universal module if you encounter these errors.

Table\Column Not Found Error when using SQL Persistence

This can happen if SQL schema upgrades are not being run during upgrades. If you set the RunMigrations setting to false in appsettings.json, you must run the migrations manually or the PowerShell Universal service will not function properly.

Breaking App Component Change

These changes can be visual or functional. Please ensure that you review the changelog for items that may be related to the change you are seeing. Consider posting the forums or opening a GitHub issue to see if the issue is as designed and if there is a viable workaround.

We make the best possible effort to support everyone's' apps without breaking changes. That said, every configuration is pretty unique so we are more than happy to address issues you may encounter. Please, just let us know.

License Issues after Upgrade

The licensing model of PowerShell Universal provides licensed users the ability to upgrade to whatever is the newest version as long as they have an active perpetual or subscription license. If you attempt to upgrade a server that is no longer within the license window, the server will not function as expected. You will need to downgrade back to the previous version to restore functionality.

Additionally, you may encounter issues due to the PSU service restart. When the service starts, it verifies license subscription status. If it fails to do so, it may not be licensed properly and cause other issues. The root cause is typically networking issues while attempting to access the IronmanSoftware.com website for activation. Offline license keys do not contact the IMS website for activation and will not encounter this issue.

Mixed Versions

Mixing versions of PowerShell Universal servers with the same database may cause issues as schema changes between the database or protocol changes in internal APIs may be mismatched. We recommend staging your upgrades in a way that you will eventually be running all PowerShell Universal servers as the same version.

There is a known compatibility issue between PSU 5.5.4 and earlier and PSU 5.6.0 and later. We do not recommend mixing these versions. Scheduling jobs may fail on existing 5.5.4 servers when combined with 5.6.0 servers.

5.0 Breaking Changes

Removal of Pages

The drag and drop page designer has been removed in favor of and .

Removal of App Pages Designer

The drag and drop page designer for apps has been removed. Apps created with the designer will still function.

Removal of Access Controls

Access Controls have been removed in favor of . You can also use the to assign resources, like scripts, to users without the need for complicated permissions.

Cmdlet Communication Channel and Authorization Changes

Prior to v5, cmdlets would send data over HTTP or by using an internal gRPC channel. Now, all cmdlets use an externally facing gRPC Channel that is protected by authentication and authorization. It no longer uses standard REST API HTTP calls.

This can be a problem for PowerShell Universal instances behind and requires that the proper header values are sent.

Please review the documentation for more information.

Common cmdlet errors you may encounter during upgrade

HTTP Status Code 403

The cmdlet you are calling does not have access to the PowerShell Universal APIs. You will need to specify an -AppToken parameter on the cmdlets in order to use them.

You can also enable the to allow internally called cmdlets from PowerShell Universal without the need for authorization.

URI Not Defined

The cmdlets are unable to determine how to call the PowerShell Universal APIs. You will need to either specify a -ComputerName parameter or setup the API URL in appsettings.json.

SSL Certificate Error

If you are using a self-signed certificate, you will need to specify the -TrustCertificate parameter of the cmdlets.

PowerShell 7 Environment No longer Uses Pwsh.exe

The default PowerShell 7 environment uses a .NET version of Universal.Agent.exe executable running PowerShell 7.5. This allows for the greatest compatibility with PowerShell Universal libraries and other modules.

It's still possible to use the pwsh.exe process in custom environment configurations.

IIS Hosting Package

If you are hosting in IIS, ensure that you install the .

Integrated Environment PowerShell Version

The integrated environment now uses PowerShell 7.5.

SQLite by Default

SQLite is the default persistence method. You will need to perform a manual conversion from LiteDB before installing version 5.

LiteDB Support Removed

LiteDB has been removed as a supported database engine. Included with the PowerShell Universal installation files, you will find psu.exe. It can be used to convert a LiteDB database into a SQLite database. Use the following command line.

The tool will create a database.bak file before performing the conversion. Progress will be reported in the console.

After converting the database, you will need to update the appsettings.json file to use the new SQLite plugin and update the connection string to a SQLite format. Below is a snippet you can use to apply to your configuration file.

Converting a Database for a MSI Upgrade

In order for the PowerShell Universal installer to run successfully, you will need to update the database before running the MSI installer. Below are the steps to take to do so.

Download the ZIP package for Windows and extract to a local directory.
Stop the PowerShell Universal service
Run the psudb.exe command from the ZIP directory, as stated above, to convert the database file in %ProgramData%\UniversalAutomation
Update the %ProgramData%\PowerShellUniversal\appsettings.json file to use the SQLite plugin rather than the LiteDB plugin

Desktop Mode Removed

Desktop mode has been removed. Resources such as hot keys, file associations and shortcuts are no longer supported. The MSI now supports User scope installs that will run as the current user and start upon login.

Install-PSUServer on Windows Installs from the MSI

In previous versions of PowerShell Universal, this command would install to a directory and create the service manually. This command now installs from MSI. If you previously installed with this module, you would need to remove the existing install with a previous version of the module and then install with the new version of the module.

Open a new command prompt and run the following.

Git Database Storage Removed

PowerShell Universal no longer supports storing the git repository directly in the database. We recommend using a remote git provider like GitHub, GitLab, or Gitea. PowerShell Universal v5 does support local git repositories without the need to sync to a remote. This allows for storing file history directly on the PowerShell Universal server.

Removed Heatmap and Marker Cluster from New-UDMap

Maps no longer support heatmaps or marker clusters.

Jobs

Jobs are the history of scripts that have been run.

Jobs are the result of running a script. Jobs are retained based on the script and server level settings.

Viewing Jobs

Jobs can be viewed by clicking the Automation / Jobs page. Click the View button to navigate to the job. Jobs in progress can also been cancelled.

View Job Output

Standard PowerShell streams such as information, host, error, warning and verbose are shown within the output pane.

View Job Pipeline Output

Storing large amounts of pipeline output can negatively affect performance. You can discard pipeline output by setting the Discard Pipeline setting on scripts.

Pipeline output for jobs is also stored within PowerShell Universal. Any object that is written to the pipeline is stored as CliXml and available for view within the Pipeline Output tab.

You can expand the tree view to see the objects and properties from the pipeline.

Viewing Errors

Any errors written to the error stream will be available on the Error tab within the job page.

Status

Jobs will return various statuses depending on configuration and the result of the execution. Settings that can affect job status include:

ErrorActionPreference
WarningActionPreference

The following table describes how PowerShell Universal treats statuses.

Status

Description

Suppress

Feedback

Some jobs will require feedback. Any script that contains a Read-Host call will wait until there is user interaction with that job. The job will be in a Waiting for Feedback state, and you can respond to that feedback by click the Response to Feedback button on the job page.

To accept a SecureString with a password input field, you can use the -AsSecureString parameter of Read-Host.

Invoking Jobs from PowerShell

You can use Invoke-PSUScript to invoke jobs from the command line. You will need a valid to do so. Parameters are defined using dynamic parameters on the Invoke-PSUScript cmdlet.

Call Scripts from Scripts

You can also call UA scripts from UA scripts. When running a job in UA, you don't need to define an app token or the computer name manually. These will be defined for you. You can just call Invoke-PSUScript within your script to start another script. Both jobs will be shown in the UI. If you want to wait for the script to finish, use Wait-PSUJob.

Waiting for a Script to Finished

You can use the Wait-PSUJob cmdlet to wait for a job to finish. Pipe the return value of Invoke-PSUScript to Wait-UAJob to wait for the job to complete. Wait-PSUJob will wait indefinitely unless the -Timeout parameter is specified.

Return Pipeline Data

You can use the Get-PSUJobPipelineOutput cmdlet to return the pipeline output that was produced by a job. This pipeline output will be deserialized objects that were written to the pipeline during the job. You can access this data from where you have access to the PowerShell Universal Management API.

Returning the last job's output

It may be required to return the output from a script's last job run. In order to do this, you will need to use a combination of cmdlets to retrieve the script, the last job's ID and then return the pipeline or host output.

Returns the last job's output as an object

By default, Get-PSUJobOutput will return the output as a string. To return the output as an object with information about the output, use -AsObject.

Invoke a Script and Wait for Output

You can use the -Wait parameter of Invoke-PSUScript to achieve this.

Additionally, the following example invokes a script, stores the job object in a $job variable, waits for the job to complete and then returns the pipeline and host output.

Integrated Mode

The integrated mode allows calling these cmdlets from within PowerShell Universal without an App Token or Computer Name. It uses the internal RPC channel to communicate.

You can set the -Integrated parameter to switch to integrated mode. This parameter does not work outside of PowerShell Universal.

The following cmdlets support integrated mode.

Get-PSUScript
Invoke-PSUScript
Get-PSUJob
Get-PSUJobOutput

Invoking Jobs with REST

You can call jobs over REST using the management API for PowerShell Universal. You will need a valid app token to invoke jobs.

Call Scripts with REST

To call a script, you call an HTTP POST to the script endpoint with the ID of the script you wish to execute.

Providing Parameters

You can provide parameters to the job via a query string. Parameters will be provided to your script as strings.

Setting the Environment

You can set the environment by pass in the environment property to the job context. The property must be the name of an environment defined within your PSU instance.

Setting the Run As account

You can set the run as account by passing in the name of a PSCredential variable to the Credential property.

Invoke Jobs from Apps

You can use the same cmdlets that you use in other PowerShell scripts to run scripts in apps. You may want a more interactive experience when doing so. Below are some examples of how to achieve that using the app framework.

Displaying Output

You can use the Invoke-PSUScript and the Get-PSUJobOutput cmdlets to create a UI element that updates as the script runs. Assume you have a script like the one below. It simply writes to the Information stream every 100 milliseconds 100 times.

Within your app, you can start the script based on some user interaction and then update an element as the script is running. The below example creates a button and a pre tag element to serve as the destination for the script's output. When the user clicks the button, it will start the job and wait for it to finish. Within the loop, it retrieves the script's output and then updates the pre element with the output content.

Finally, it retrieves an updated status of the job and waits 100 milliseconds before running again.

Displaying Progress

The app framework's PowerShell host will automatically interface with features of PowerShell, like Write-Progress.

If you use the -Wait parameter of Invoke-PSUScript , it will automatically display the script's progress in a dialog in your app. Assume we have a script defined as below. This script writes progress every 100 milliseconds.

Within our app, we can simply call the script with the -Wait parameter. When the user clicks the button, the progress will be displayed in the app.

Requesting Input

The app framework's PowerShell host will automatically interface with features of PowerShell, like Read-Host.

If you use the -Wait parameter of Invoke-PSUScript , it will automatically prompt the user for input when encountering the Read-Host command. Assume we have a script that requests user input using Read-Host.

In your app, simply call the script with the -Wait parameter.

The user will then be prompted as the script runs.

Variables Defined in Jobs

Variables defined in jobs can be found on the .

Job Run ID

The default behavior for PowerShell Universal is to track jobs based on an autoincrementing int64-based ID. Every time a new job is run, the job is one higher in ID than the last. Because of this behavior, it is easy to guess other job IDs and can potentially lead to a security risk.

In order to avoid this issue, you can enable the JobRunID experimental feature. Although internally the system still creates jobs with ascending numeric IDs, you cannot access jobs based on those IDs. Instead, a new field called RunID is used. RunID utilizes a GUID rather than an ID for look ups. This greatly reduces the ability for an attacker to guess a job ID.

You will need to enable this feature to use it.

API

Endpoints

Endpoint configuration for Universal APIs.

Endpoints are defined by their URI and HTTP method. Calls made to the Universal server that match your defined API endpoint and method execute the API endpoint script.

To invoke the above method, you can use Invoke-RestMethod.

When defining endpoints in the management API, you can skip the New-PSUEndpoint call, as the admin console defines it.

The only contents that you need to provide in the editor are the script you wish to call.

Avoid using endpoint URLs that match internal PowerShell Universal Management API URLs, as this causes unexpected behavior. You can reference the for the to verify that none of the URLs match.

HTTP Methods

Endpoints can have one or more HTTP methods defined. To determine which method is used by an endpoint, use the built-in $Method variable.

Variable URL

URLs can contain variable segments. You can denote a variable segment using a colon (:). For example, the following URL would provide a variable for the ID of the user. The $Id variable will be defined within the endpoint when it is executed. Variables must be unique in the same endpoint URL.

To call this API and specify the ID, do the following:

Query String Parameters

Query string parameters are automatically passed into endpoints as variables that you can then access. For example, if you have an endpoint that expects an $Id variable, you can provide it in the query string.

The resulting Invoke-RestMethod call must then include the query string parameter.

When using multiple query string parameters, ensure that your URL is surrounded by quotes so PowerShell translates it properly. Including an ampersand (&) without quotes will cause issues in both Windows PowerShell and PowerShell 7.

Security Considerations

When accepting input via Query String parameters you may be vulnerable to . Consider using a param block to ensure that only valid parameters are provided to the endpoint.

Below is an example of CWE-914. Include a $IsChallengePassed query string parameter to bypass the challenge.

In order to avoid this particular issue, you can use a param block.

Headers

Request headers are available in APIs using the $Headers variable. The variable is a hashtable. To access a header, use the following syntax:

Cookies

Request cookies are available in APIs using the $Cookies variable. The variable is a hashtable. To access a cookie, use the following syntax:

Send back request cookies with the New-PSUApiResponse cmdlet. Use the -Cookies parameter with a supplied hashtable.

Body

To access a request body, you will simply access the $Body variable. Universal $Body variable will be a string. If you expect JSON, you should use ConvertFrom-Json.

To call the above endpoint, specify the body of Invoke-RestMethod.

Live Log

You can view the live log information for any endpoint by clicking the log tab. Live logs include URL, HTTP method, source IP address, PowerShell streams, status code, return Content Type, and HTTP content length.

You can write to the live log from within your endpoints with cmdlets like Write-Host.

Testing

You can use the Test tab in the Endpoint editor to test your APIs. Using this Test tool, you can adjust headers, the query string, and body. You can also adjust the Authentication and Authorization for the test.

When using the test tab, any changes to the values of the test will result in an updated Code block that you can then use within PowerShell. Click the Code tab to view the test code.

Additionally, tests performed within the tester will be stored for 30 days to allow for retesting without having to reconfigure all the properties. Clicking the Apply button will setup the Test tool with the same properties.

Form Data

You can pass data to an endpoint as form data. Form data will pass into your endpoint as parameters.

You can then use a hashtable with Invoke-RestMethod to pass form data.

JSON Data

You can pass JSON data to an endpoint and it will automatically bind to a param block.

You can then send JSON data to the endpoint.

Param Block

You can use a param block within your script to enforce mandatory parameters and provide default values for optional parameters such as query string parameters. Variables such as $Body, $Headers and $User are provided automatically.

In the below example, the $Name parameter is mandatory and the $Role parameter has a default value of Default.

When using the param block with route parameters like the above example, you must include the route variable in your parameter. If it is not specified, you will not have access to that value.

For example, the following $Name variable is always $null. The endpoint always returns false.

If you use the CmdletBinding or Parameter attribute within your param block, the endpoint will strictly enforce which parameters are allowed into the endpoint.

For example, the following enforces that the name parameter is specified.

That said, you cannot specify additional parameters to the endpoint. Doing the following will cause an error.

If you change your endpoint to avoid using the Parameter attribute, you can pass in any number of params and they will be bound as variables and not parameters to the endpoint.

Returning Data

Data returned from endpoints is assumed to be JSON data. If you return an object from the endpoint script block, it is automatically serialized to JSON. If you want to return another type of data, you can return a string formatted however you chose.

Processing Files

Uploading Files

You can process uploaded files by using the $Data parameter to access the byte array of data uploaded to the endpoint.

The multipart/form-datacontent type is not supported for uploading files to APIs.

You can also save the file into a directory.

Downloading Files

You can send files down using the New-PSUApiResponse cmdlet.

Returning Custom Responses

You can return custom responses from endpoints by using the New-PSUApiResponse cmdlet in your endpoint. This cmdlet allows you to set the status code, content type and even specify the byte[] data for the content to be returned.

You can also return custom body data with the -Body parameter of New-PSUApiResponse.

Invoking the REST method returns the custom error code.

You can control the content type of the returned data with the -ContentType parameter.

You can control the response headers with a hashtable of values that you pass to the -Headersparameter.

Persistent Runspaces

Persistent runspaces allow you to maintain runspace state between API calls. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent API calls.

By default, runspaces are reset after each execution. This removes variables, modules and functions defined during the execution of the API.

To enable persistent runspaces, you will need to configure an for your API. Set the -PersistentRunspace parameter to enable this feature. This is configured in the environments.ps1 script.

You can then assign the API environment in the settings.ps1 script.

Timeout

By default, endpoints will not time out. To set a timeout for your endpoints, you can use the New-PSUEndpoint -Timeout parameter. The timeout is set in the number of seconds.

External Endpoint Content

You can define the path to an external endpoint content file with the -Path parameter of New-PSUEndpoint. The path is relative to the .universal directory in Repository.

The content of the endpoints.ps1 file is then this:

C# APIs

C# APIs are enabled as a .

There is no UI for creating a C# API, so you need to do so using configuration files. First, create a .cs file that runs your API.

You will have access to a request parameter that includes all the data about the API request.

You will also have access to a ServiceProvider property that allows you to access services within PowerShell Universal. These are not currently well-documented, but below is an example of restarting a dashboard.

Some other useful services include:

IDatabase
IApiService
IConfigurationService
IJobService

You can choose to return an ApiResponse from your endpoint.

Once you have defined your C# endpoint file, you can add it by editing endpoints.ps1.

The PowerShell Universal service automatically compiles and runs C# endpoints.

API

Data Grid

Data grid component for Universal Apps.

The UDDataGrid component is an advanced version of the table that is useful for displaying large amounts of data. It supports many of the same features as the table but also provides complex filtering, row virtualization, multi-column sort and more.

Simple Data Grid

Data grids load their data via the -LoadRows event handler. You will need to return a hashtable that contains the row data and the total number of rows.

Columns are defined using hashtables.

Columns

Columns are customizable using New-UDDataGridColumn. More information on this cmdlet can be found .

Rendering Custom Columns

You can render custom components in columns by specifying render within the column hashtable. You can access the current row's data by using the $EventData or $Row variable

In this example, the number is shown in the name column with a New-UDTypography component.

Flexible Width Columns

Column fluidity or responsiveness can be achieved by setting the flex property of a column.

The flex property accepts a value between 0 and ∞. It works by dividing the remaining space in the grid among all flex columns in proportion to their flex value.

For example, consider a grid with a total width of 500px that has three columns: the first with width: 200; the second with flex: 1; and the third with flex: 0.5. The first column will be 200px wide, leaving 300px remaining. The column with flex: 1 is twice the size of flex: 0.5, which means that final sizes will be: 200px, 200px, 100px.

To set a minimum and maximum width for a flex column set the minWidth and the maxWidth property on the column.

Auto Sizing Columns

If you'd like to let the data grid auto size the column widths, you can use the -AutoSizeColumns parameter of New-UDDataGrid. The data grid will evaluate the size of the data and determine the best size for the columns after the data is loaded. This may cause some UI rearrangement after the data loads.

LoadRows

The -LoadRows parameter is used to return data for the data grid. Table state will be provided to the event handler as $EventData. You will find the following properties within the $EventData object.

Property

Description

Type

Paging

To implement paging, you can access the page and pageSize properties of the $EventData variable. If you are using a remote data source, you will want to implement custom paging logic. Below is an example of using the paging properties to page through the rows locally. Depending on your data source (e.g. SQL), you may page through data differently.

Out-UDDataGridData automatically implements paging, and you do not need to do the above if you have all your data in memory. The above is just used for demonstration purposes.

Filtering

The data grid supports filtering data based on each column. Multiple filters can be defined to allow the user to narrow down the displayed data set. By default, the Out-UDDataGridData cmdlet implements filtering for local data. When using a remote data source, like SQL, it is suggested to implement custom filtering to improve user experience and performance.

Filter Data Structure

The filter object is included in the $EventData for the -LoadRows event handler when a filter is defined. The object has a structure as follows.

Items

The items property contains a collection of fields, operators and values. You can use these to filter your data.

Property

Description

Type

LogicOperator

The logic operator field is used to specify the link between the filters. This can be and or or.

QuickFilterValues

Contains a collection of quick filter values that you can chose how to apply to your data.

QuickFilterLogicOperator

Contains the logic operator for the quick filter values specified by the user. This can be and or or.

Custom Filter

The Out-UDDataGridData cmdlet provides an implmentation of filtering for static data. If you use this cmdlet, you do not need to implement filtering manually. If you have a remote data source, you will want to provide a custom implementation for filtering. Below is an example of using the filter structure in $EventData to eliminate rows based on the filters provided by the user.

Custom Quick Filter

The quick filter is a similar to a simple search box. You can enable quick filtering with the -ShowQuickFilter parameter on New-UDDataGrid. A search box will appear in the top right of the data grid. When the user enters a value in the data grid, the quick filter information will be provided.

Below is an example of how to use quick filters. Out-UDDataGridData implements quick filtering and is not required when using local data. The below is done for demonstration only.

Sorting

The $EventData object will contain a Sort property when the user sorts the data grid. It contains properties for each column that is sorted. The properties will start as 0 and increment as more columns are sorted.

For example, you can access the first sorted column as follows.

You will also receive the sort direction for each column.

Property

Description

Type

Detailed Content

You can use the -LoadDetailContent event handler to display additional information about the row you are expanding. Information about the current row is available in $EventData.row.

Example: Nested Data Grids

You can use the -LoadDetailContent parameter to look up nested data about an object. In this example, we load a data grid of virtual machines and display the name, operating system, memory and CPU cores. Expanding the detail content provides a data grid of the network cards available on the virtual machine. We are using dummy data in this example but you could use any cmdlet available to PowerShell Universal.

Editing

Tables provide editor support by specifying the -OnEdit event handler. The new row data will be provided as $EventData. You can chose to return updated row information (for example, adjusting something the user has entered) and return it from the event handler. If you do not return anything, the row will reflect what the user entered.

The $EventData has the following format.

Ensure that you provide the editable property to each column you wish for the user to edit.

Selection

You can enable row selection using the -CheckboxSelection parameter to display checkboxes for the rows to select. Row selection requires a deterministic ID for the data rows provided. In the below example, you will see each row has a specific ID specified.

You can access selected data with the -OnSelectionChange event handler or by retrieving the row IDs via Get-UDElement.

Custom Export

To override the default export functionality, use the -OnExport event handler. $EventData will be the same context object used for -LoadRows. You should use Out-UDDataGridExport to return the data from -OnExport.

Multiple Export Types

When using a custom export, you can use the -ExportOptionsparameter to define multiple export types. When the user selects the export type, you can check the Type property of $EventDatato determine which type of export to produce.

Example: Static Data

In this example, we generate an array of 10,000 records. We will create a new function, Out-UDDataGridData to manage the paging, sorting and filtering. This function is already included in the .

Example: SQL Data

In this example, we'll query the PowerShell Universal database with dbatools.

API

Table

Table component for Universal Apps

Tables display sets of data. They can be fully customized.

Tables display information in a way that’s easy to scan, so that users can look for patterns and insights. They can be embedded in primary content, such as cards.

Simple Table

A simple example with no frills. Table columns are defined from the data.

Table with Custom Columns

Define custom columns for your table.

Table with Custom Column Rendering

Define column rendering. Sorting and exporting still work for the table.

Table Column Width

Column width can be defined using the -Width parameter. You can also decide to truncate columns that extend past that width.

Filters

You can configure custom filters per column. The table supports text, select, fuzzy , slider, range, date , number, and autocomplete filters.

Static Options for Select Filters

When using server-side processing, the available filters may not display the full range of options since the select dropdown only has access to the current page of results. To avoid this, you can use the -Options parameter on New-UDTableColumn.

Search

To enable search, use the -ShowSearch parameter on New-UDTable.

When using custom columns, you will need to add the -IncludeInSearch parameter to the columns you'd like to include in the search.

Table with server-side processing

Process data on the server so you can perform paging, filtering, sorting and searching in systems like SQL. To implement a server-side table, you will use the -LoadData parameter. This parameter accepts a ScriptBlock. The $EventData variable includes information about the state of the table. You can use cmdlets to process the data based on this information.

$EventData Structure

The $EventData object contains the following properties.

Property Name

Type

Description

Example

Retrieving Displayed Data

You may want to allow the user to take action on the current set of displayed data. To do so, use Get-UDElement in the input object you want to retrieve the data from and get the table by Id. Once you have the element, you can use the Data property of the element to get an array of currently displayed rows.

Paging

By default, paging is disable and tables will grow based on how many rows of data you provide. You can enable paging by using the -ShowPagination cmdlet (alias -Paging). You can configure the page size using the -PageSize cmdlet.

Disable Page Size All

By default, the page size selector provides an option to show all rows. If you want to prevent users from doing this, use the -DisablePageSizeAll cmdlet.

Pagination Location

You can change the location of the pagination control by using the -PaginationLocation parameter. It accepts top, bottom and both.

Page Sizes

The page size, by default, is set to 5. Users can adjust the number of rows per page by using the Rows per page drop down. You can adjust the default page size by using the -PageSize parameter. To adjust the values available within the Rows per page drop down, you can use an array of integers pass to the -PageSizeOptions parameter.

Sorting

To enable sorting for a table, use the -ShowSort parameter. When you enable sorting, you will be able to click the table headers to sort the table by clicking the headers. By default, multi-sort is enabled. To multi-hold shift and click a column header.

You can control which columns can be sorted by using New-UDTableColumn and -ShowSort parameter.

Disable Sort Remove

By default, the sorting of a table has 3 states. Unsorted, ascending and descending. If you would like to disable the unsorted state, use the -DisableSortRemove parameter of New-UDTable.

Selection

Static Table Data

Tables support selection of rows. You can create an event handler for the OnRowSelected parameter to receive when a new row is selected or unselected or you can use Get-UDElement to retrieve the current set of selected rows.

The following example creates a table with row selection enabled. A toast is show when clicking the row or when clicking the GET Rows button.

The $EventData variable for the -OnRowSelected event will include all the columns as properties and a selected property as to whether the row was selected or unselected.

For example, the service table data would look like this.

Dynamic (Server-Side) Tables

When using selection and -LoadData, the -OnRowSelected $EventData will be the IDs of the rows and not the entire row data. It will still indicate where the row has been selected or de-selected.

Collapsible Rows

You can include additional information within the table by using the -OnRowExpand parameter of New-UDTable. It accepts a ScriptBlock that you can use to return additional components.

Exporting

Tables support exporting the data within the table. You can export as CSV, XLSX, JSON or PDF. You can define which columns to include in an export and choose to export just the current page or all the data within the table.

Hidden Columns

Hidden columns allow you to include data that is not displayed in the table but is included in the exported data.

The following hides the StartType column from the user but includes it in the export.

Server-Side Exporting

You can control the export functionality with a PowerShell script block. This is useful when exporting from server-side sources like SQL server tables.

In this example, I have a SQL table that contains podcasts. When exporting, you will receive information about the current state of the table to allow you to customize what data is exported.

Customizing Export Options

You can decide which export options to present to your users using the -ExportOption cmdlet. The following example would only show the CSV export option.

Customizing Labels

You can use the -TextOption parameter along with the New-UDTableTextOption cmdlet to set text fields within the table.

Refresh with a button

Data Parameter

You can externally refresh a table by putting the table within a dynamic region and using Sync-UDElement.

This example creates a button to refresh the table.

LoadData Parameter

If you use the -LoadData parameter, you can sync the table directly. This has the benefit of maintaining the table state, such as the page and filtering, after the refresh.

Show Refresh Button

You can use the -ShowRefresh parameter to provide a refresh button for server-side tables.

Alternating Row Colors

You can use a theme to create a table with alternating row colors.

Custom Row Styles

Use the -OnRowStyleparameter to style the rows based on the row content. Return a hashtable with CSS styles for the row.

v5

About

APIs

What's New in v5?

New Admin Console

Portal

Pages and Widgets

PowerShell Universal Gallery

Granular Permissions

PostgreSQL Support

Updated Runtimes

gRPC Cmdlets

Windows PowerShell 5.1 and PowerShell 7 Environments

Additional Resources

Uninstall

Application Files

ZIP Installation

MSI Installation

Module Installation

Windows

Linux and Mac OS

Configuration Files

Windows

Linux

Mac OS

Desktop

Database

SQLite

Windows

Linux and Mac OS

PostgreSQL and SQL

IIS

Downgrade

Supported Browsers

Release Support Policy

Support Policy

API

About

Execution Environment

Per Endpoint Environment

Performance

Variables

API

Event Hubs

Creating an Event Hub

Rate Limiting

Automation

About Automation

Run Scripts

Terminals

Tests

Apps

About

Data Display

Alert

Simple Alerts

Advanced Alerts

API

Badge

Basic Badge

Chip

Basic Chips

Date and Time

Basic Formatting

Custom Formatting

Locale

API

List

List

OnClick Event Handler

API

Markdown

Markdown in Paper

API

Tooltip

Basic Tooltip

Placement

Tree View

Basic Tree View

Typography