Downloads

Download the latest version of PowerShell Universal.

Blog

The Ironman Software blog has articles about PowerShell Universal.

Connect with the PowerShell Universal community.

Chat with other PowerShell Universal users.

Purchase a license for the features of PowerShell Universal.

File a bug report or feature request for PowerShell Universal.

Samples that can be inserted into your PowerShell Universal system using the .

Check out video tutorials for PowerShell Universal.

The provides integration for working with automation. We recommend you also install the .

Developing Scripts

To add scripts to the Universal platform, you can do it via the admin console or the file system. The Visual Studio Code extension also provides integration for managing the scripts.ps1 configuration file.

The Scripts tree view will provide access to each of your scripts, the admin console the scripts.ps1

Universal is a cross-platform solution for developing web-based tools with PowerShell. It currently provides three main features which include APIs, Automation and Dashboards.

Universal provides an Administrator console, management REST API, PowerShell cmdlets and a idempotent configuration system using PowerShell scripts.

APIs

Install PowerShell Universal

You'll need to install the PowerShell Universal server. but you can use the command line below to get started quickly.

Features

• Simple Background Jobs - Universal Automation provides the ability to run simple background jobs in Windows PowerShell and PowerShell 7. Jobs can be scheduled to run with simple CRON expressions.

• Runs anywhere - Built on .NET to support multi-platform, docker, raspberry pi, and just about anything!

• Persistence - Universal Automation job status is automatically backed by database persistence to allow for easy reporting of job results and data.

• PowerShell First - Build from the ground up for Administrators/Developers/DevOps professionals familiar with PowerShell. UA integrates with Write-Progress, the pipeline, and user input, like Read-Host, to allow users to interact with scripts via the UA dashboard.

Windows

• Windows PowerShell v5.1 or greater or PowerShell v7.0 or greater

• .NET Framework v4.7.2 (only for Windows PowerShell)

Linux

• PowerShell v7.0 or great

• Validated Distributions: Ubuntu 18.04

Mac OS X

Server-side SQL Table

This example uses Universal Dashboard.

This example takes advantage of a SQL server and the New-UDTable cmdlet to create a table that retrieves data from a database table. The filtering, sorting and paging take place within the database.

This example assumes that we have a database called podcasts running in the local MS SQL Server. It has a table called shows that includes a column called host and a column called name.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'SQL' -BaseUrl "/" -Framework 'UniversalDashboard:Latest' -Content {
        New-UDDashboard -Title 'SQL' -Content {
            New-UDTable -Title 'Shows' -LoadData {
                $TableData = ConvertFrom-Json $Body

                $OrderBy = $TableData.orderBy.field
                if ($OrderBy -eq $null)
                {
                    $OrderBy = "name"
                }

                $OrderDirection = $TableData.OrderDirection
                if ($OrderDirection -eq $null)
                {
                    $OrderDirection = 'asc'
                }

                $Where = ""
                if ($TableData.Filters) 
                {
                    $Where = "WHERE "

                    foreach($filter in $TableData.Filters)
                    {
                        $Where += $filter.column.field + " LIKE '%" + $filter.value + "%' AND "
                    }

                    $Where += " 1 = 1"
                }

                $PageSize = $TableData.PageSize 
                # Calculate the number of rows to skip
                $Offset = $TableData.Page * $PageSize
                $Count = Invoke-DbaQuery -SqlInstance localhost\MSSQLSERVER -Database 'podcasts' -Query "SELECT COUNT(*) as count FROM shows $Where"

                $Data = Invoke-DbaQuery -SqlInstance localhost\MSSQLSERVER -Database 'podcasts' -Query "SELECT * FROM shows $Where ORDER BY $orderBy $orderdirection OFFSET $Offset ROWS FETCH NEXT $PageSize ROWS ONLY" | ForEach-Object {
                    @{ 
                        name = $_.name 
                        host = $_.host
                    }
                } 
                $Data | Out-UDTableData -Page $TableData.page -TotalCount $Count.Count -Properties $TableData.properties
            } -Columns @(
                New-UDTableColumn -Property 'name' -Sort $true -Filter $true
                New-UDTableColumn -Property 'host' -Sort $true -Filter $true
            ) -Sort -Filter
        }
    }
}

Getting Started

PowerShell Module

You can use the PowerShell Universal PowerShell module to install the Universal server. To install the module, use Install-Module.

To install the Universal server, you can use Install-PSUServer.

You can configure the path that the server is stored in by using the -Path parameter.

You can add the PSU server to the PATH environment variable by use the -AddToPath parameter.

Once the server has been installed, you can use Start-PSUServer to start it.

You can specify the path to the executable using the -ExecutablePath parameter. If you have set the location of the server to -AddToPath with Install-PSUServer, Start-PSUServer should find the executable automatically.

Chocolatey Package (Windows)

You can install PowerShell Universal using the . The package runs the MSI install. It will install Universal as a service and open a web browser after the install.

You can login with the "admin" user and any password.

Winget (Windows)

You can install PowerShell Universal using Winget. It will run the MSI and install as a service.

You can also specify the --silent flag to prevent the installer from showing and the web browser from opening at the end of the install.

ZIP Install

You can also download the ZIP from our if you would like to xcopy deploy the files on Windows or Linux.

Windows

You can start Universal by unzipping the contents, unblocking the files and then executing Universal.Server.exe.

Linux

On Linux, start the process Universal.Server. You may need to chmod +x the file if it does not start.

Docker

See the .

MSI Install (Windows)

The MSI install will create a PowerShell Universal service and open the admin console after installation.

Properties

SUPPRESSBROWSER

Setting the SUPPRESBROWSER MSI property to true will prevent the browser from opening after installation.

Next Steps

At this point, Universal is up and running. Please consult other sections in this documentation for instructions on how to configure, secure, and start using PowerShell Universal. Happy Scripting!

Build interactive user interfaces and dashboards with PowerShell script. Integrate with your existing PowerShell modules and functions to bring data in from anywhere.

• Build tools for your help desk users

• Report on data in interactive visualizations like charts, calendars, maps and more

• Provide role-based access controls to pages and even individual components

Display Log Messages in PowerShell Universal

This example configures PowerShell Protect to send log messages to a PowerShell Universal instance. It sends HTTP POST requests to the configured server.

PowerShell Universal provides the ability to rate limit requests made to the web server. Rate limiting can be configured on a per endpoint and per period. By default, the client IP address is used to rate limit clients.

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

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

The current version of the following web browsers are supported: , , , and

Send Message to Slack

This example uses .

This example uses a custom Slack webhook to send a message from a Universal API.

You can invoke this API by calling Invoke-RestMethod

The following message will show up in Slack.

You can use a cascading style sheet (CSS) by add a .css file to a published folder and then passing it to the -Stylesheets parameter for New-UDDashboard.

For example, the dashboard.ps1 file would look like this.

You could then setup a published folder to provide the assets route. This is what the contents of publishedFolders.ps1 will look like.

Within the C:\assets folder, you can place any assets you'd like to access on the /assets

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

Autocomplete with a static list of options

PowerShell Universal is licensed per server. We provide licenses for individuals and organizations.

You can purchase a license on our website.

What's a server?

A server is a single running instance of PowerShell Universal.

Free Use Restrictions

Universal can be used forever for free with the following limitations.

Universal API

• No authentication

• No Rate Limiting

Universal Automation

• 25 jobs per day

• 2 concurrent jobs

• No Triggers

Universal Dashboard

• No authentication

• No access to diagnostic tools

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

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

New-UDErrorBoundary -Content {
    throw "Oh no!"
}

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

API

New-UDErrorBoundary

Display an error card when an error is thrown in your script.

The Visual Studio Code extension for PowerShell Universal provides integration for working with APIs. We recommend you also install the PowerShell extension.

Developing APIs

You can add APIs by using the admin console or through the editor in Visual Studio Code.

To add an API in the Admin Console, you can visit http://localhost:5000/admin/apis and click Add Endpoint.

Once an endpoints.ps1 file has been created, you can click the Open Endpoints.ps1 button within the API tree view to view the configuration file for APIs.

The configuration file uses the Universal PowerShell cmdlets to define the endpoints within Universal.

If you created a blank endpoint, it would look something like this.

If you edit the endpoints.ps1 file, it will update the API automatically. For example, if I added a new API, it would then appear in the admin console.

Installation

Our docker image is available on Docker Hub. You can start it by pulling and then running with the default port bound.

Tags

Persistent Data

To create a Docker image that can persist the Universal data, you can create a dockerfile like the one below.

This dockerfile exposes port 5000, creates a /data volume, sets configuration environment variables to store the Universal repository and database in the volume and then sets the Universal.Server as the entry point to the container.

Linux

Windows

You can run a build with the build command.

You can start the docker container with the run command and make sure to specify the volume to mount.

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 {}
        }
    }
}

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.

New-UDSwitch -Checked $true 
New-UDSwitch -Checked $true -Disabled

OnChange Event

Respond to when a switch value is changed. The $EventData variable will include whether or not the switch was checked or unchecked.

Get-UDElement Support

You can retrieve the value of the switch within another component by using Get-UDElement. Use the Checked property to determine whether the switch is checked out not.

New-UDSwitch

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.

Installation

Designing Layouts

You can employ the -Design parameter to configure the layout of yourr page. This allows dynamic drag and drop of components that you place within the content of the grid layout. As you drag and resize components, the layout will be copied to your clipboard. Note: All components must possess a statid -Id

Using Layouts

Once you have configured the layout to fit your needs, you can paste the JSON into your script and assign it with the -Layout parameter. Remove the -Design parameter to lock elements in place.

Allowing Users to Modify Layouts

You can allow your users to dynamically modify layouts by using the -Draggable, -Resizable and -Persist parameters. The layout changes are stored locally so the next time each user visits a page, it will be loaded with their chosen layout.

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.

New-UDHtml -Markup "<ul><li>First</li><li>Second</li><li>Third</li></ul>"

API

New-UDHtml

Write raw HTML to your dashboard.

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.

New-UDTreeView -Node {
    New-UDTreeNode -Name 'Level 1' -Children {
        New-UDTreeNode -Name 'Level 2 - Item 1' 
        New-UDTreeNode -Name 'Level 2 - Item 2'
        New-UDTreeNode -Name 'Level 2 - Item 3' -Children {
            New-UDTreeNode -Name 'Level 3'
        }
    }
}

Dynamic Tree View

Dynamic tree views allow you to run PowerShell whenever a node is clicked. You can then return a list of nodes that should be rendered underneath the clicked node. You can also take other actions such as opening a modal or showing a toast.

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

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.

Custom Variable Scopes

Universal Dashboard exposes two custom variable scopes using custom providers. These providers allow you to store your variables in scopes that make sense for a web application. The cache scope is used to store variables that can be used within any endpoint inside a dashboard. The session scope is used to store variables that can be used for a single user's session of the dashboard.

Cache Scope

Cache scope is used to store a variable that will be available in any endpoint. Cache scope is useful for storing data that make be shown in more than one control or may be time consuming to look up. This could be helpful for querying machine performance counters, Active Directory or Azure.

Just like any other scope, cache variables are defined with a prefix and a colon separator.

Once assigned, the $Cache:Computer variable is available within any endpoint.

Session Scope

Session scope is used to store a variable per session. A session is established when a user's browser first visit a dashboard. A cookie is stored in the user's browser that dictates that it is part of the session. Sessions have an idle timeout of 25 minutes.

Just like any other scope, cache variables are defined with a prefix and a colon separator.

Once assigned, the $Session:ShowChart variable is available in dashboard endpoints. Session variables are not available in REST API endpoints or scheduled endpoints.

Once a session is terminated, the session variables are cleared.

Variables allow for the global definition of variables that are available within scripts. You can also import secrets that are also available within scripts or as run as credentials.

Creating a Variable

To create a variable, navigate to the Automation / Variables page. Click Add Variable to define a new variable.

Standard variables are just name \ value pairs of strings. They will be added to your scripts before they are run.

Creating a Secret Variable

Secret variables are stored within the selected vault. The value of those variables are never stored within Universal. To define a new secret variable, click Add Variable on the variables page and select the Secret tab.

From this dialog, you'll be able to define string and PSCredentials in the specified vault.

Importing Secret Variables

You can also import pre-existing secrets as variables into Universal. The variable values are not imported but will be looked up during execution. Click the Import Secret button to import secrets.

Related Cmdlets

General

The Universal application binaries can generally be upgraded without having to change the configuration or database manually. This document will cover how to upgrade the application and some caveats to be aware of in regards to configuration and data persistence.

Schedules can be assigned to scripts and allow you to define frequency and other parameters for a script such as run as credentials.

By default, endpoints will return a 200 OK message even if there are errors. If an error occurs, you will get a blank response from the endpoint. This document demonstrates different ways to handle errors within APIs.

Automatically Returning Errors

To automatically return errors from APIs, you can change the default behavior by setting the -ErrorAction parameter of New-PSUEndpoint to Stop. Any errors will cause an 500 Internal Server Error to be returned with a list of the errors and stack trace.

Convert JPEG to PNG

This example uses .

This examples accepts a JPEG file and converts to to a PNG using Universal Dashboard. To implement this example, we need to use published folders and a dashboard that uses UDForm and the UDUpload component. After converting the image, it displays it.

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

Time Picker

New-UDTimePicker

PowerShell Universal can be managed with the PowerShell Universal Visual Studio Code extension. It allows you to connect to a local Universal instance and manage APIs, dashboards and scripts.

Installation

You can download the extension from the . You can also download the extension from within the Visual Studio Code extension pane. Search for PowerShell Universal and click Install.

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

New-UDExpansionPanel

REST API authentication requires a Universal API license. Once enabled, you will be able to enforce authentication and authorization on your endpoints.

Defining Secure Endpoints

You can define secure endpoints in the UI by enabling authentication.

You can also define secure endpoints using the .universal/endpoints.ps1 file or the Management API using New-PSUEndpoint.

When authentication is enabled, it will enforce the use of one of the configured authentication methods. APIs support the following methods.

• JWT App Tokens

• Windows Authentication

• Cookie Authentication

Accessing Secure Endpoints

Once you have defined a secure endpoint, you will need to provide authentication and authorization to access the endpoint.

Authenticating with tokens

To authenticate with tokens, first, you need generate a new app token for use. You can use the Grant-PSUAppToken cmdlet to do so remotely or you can create an app token in the UI using the Settings Security AppTokens tab.

Click Grant App Token to create a new one.

Once you have created your app token, you can now use it to authenticate against the secure endpoint. To do so, pass the Authorization header along with the request.

Authenticating with Windows Authentication

To authenticate with , you can use the -UseDefaultCredentials parameter of Invoke-RestMethod and Invoke-WebRequest . This will perform negotiate authentication whether you are running inside IIS or a service.

Authenticating with Cookies

To authenticate with cookies, you will first need to call the login API to receive a valid cookie from the system. You can use Invoke-WebRequest to do so. Pass the user name and password as the body. Specify the -SessionVariable parameter to establish a session.

Once you have successfully authenticated, you can use your $mySession variable to call secure endpoints.

Enforcing Roles

In addition to creating endpoints that require authentication, you can also enforce roles by define a role in the New-PSUEndpoint cmdlet or by selecting one in the UI. If a role is selected, it's possess the role.

Windows and Cookie authentication will assign roles based on the Identity of the user and the role policies as they are applied.

JWT app tokens will use the role that was defined when they were generated.

Related Cmdlets

When building dashboards, you will pick one of the two built in dashboard frameworks. The components that are available for that framework will different. You can find examples of each of the frameworks at the below links.

• Universal Dashboard v2

Dashboards can contain one or more pages. The simplest dashboard will contain a single page with some content. You can call any PowerShell cmdlet that is available on your machine to populate your dashboard.

Here's an example of simple dashboard that displays some text.

Components

Components are the individual widgets that you can place on you dashboard. There are components for displaying data, taking user input, adding text and images and more. Components can be downloaded as PowerShell modules and added to your dashboard.

Examples of all of the components can be found .

Components are be caused using the standard verb-name syntax for any PowerShell cmdlet.

Pages

You can specify multiple pages within a dashboard. Each page defines a route. As for v3, all pages are dynamic. PowerShell will execute on each page load to render the new page. Since UD is a single page application, the web browser does not need to refresh the entire web page when navigating between the different dashboard pages.

Built-in Variables

There are several built-in variables that are available in dashboards.

Debugging

When building a dashboard you will likely run into issues with cmdlet calls or syntax. Dashboards will auto reload as you make changes to the dashboard files. If a dashboard fails to start, you can navigate to the admin page, click Dashboards and click the Info button next to your dashboard.

The Log tab will show all the logging coming from the PowerShell execution from within in your dashboard. This should allow you to easily see errors and warnings coming from your dashboard.

You can use Write-Debug to add additional log messages to your dashboard. To enable debug logging, you will have to set the $DebugPreference variable at the top of your dashboard script.

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

New-UDAlert

Scripts are the basic entity within Universal Automation. Scripts are just PowerShell scripts. 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.

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.

PowerShell Version

Allows you to define the required PowerShell version for the script. By default, it uses the server-wide default PowerShell version. PowerShell versions are automatically located the first the Universal Server starts up. You can also add PowerShell Versions on the Settings / General 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.

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

Universal Automation 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

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.

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

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.

Related Cmdlets

Component Examples

We maintain several component libraries that you can use in your dashboards directly or as examples.

• Active Directory

Single-File Configuration Examples

This page contains examples of PowerShell Universal configurations. All examples are built using single-file hosting and configuration. These examples assume that you have PowerShell Universal installed. To install PowerShell Universal, use the following command line.

You can login to PowerShell Universal using the username admin and any password.

Table of Contents

• Active Directory

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 date and time component uses DayJS. For a full list of custom formatting options, visit the DayJS documentation.

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

API

New-UDDateTime

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

OnClick

New-UDFloatingActionButton

Dashboard Frameworks define the PowerShell scripts and JavaScript components that are used to render the dashboard. Additional frameworks, when available, can be added through the Add Framework button from the Dashboard Frameworks page.

There are two dashboard frameworks built into PSU. Universal Dashboard v2 and Universal Dashboard v3. The intent of Universal Dashboard v2 is to enable users of PowerShell Universal Dashboard to easily run their existing dashboards within PowerShell Universal. Only bug fixes will be going into UDv2. Universal Dashboard v3 is built on a more modern framework and will be receiving feature updates going forward.

Both dashboards are open source so you can contribute to the dashboard in terms of bug fixes or features.

For an example of each framework, click on the appropriate link below.

• Universal Dashboard v2

A Universal Dashboard website is composed of components. There are two frameworks that provide a set of core components that you can use within your pages. In addition to the core component, you can also extend Universal Dashboard with a large set of community created components.

There are two non-framework components that are built in to PSU. These include the Nivo charts library as well as the UDMap component. They will work in either framework. Additional components can be downloaded from the UD Marketplace.

External components are distributed as PowerShell modules and can be used in a dashboard by using Import-Module.

When building a dashboard, you can simply call the PowerShell cmdlets within your dashboard script to create a new component.

New-UDDashboard -Title 'Dashboard' -Content {
    New-UDTypography -Text 'Hello, world!'
}

Adding Components to Dashboards

Some components are not included automatically. You can add component modules by clicking the Components button on the Dashboard page and then adding the components. This list will also include components downloaded from the Marketplace.

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.

OnClick Handler

The backdrop provides an -OnClick handler that you can use to close the backdrop when clicked. You can use Set-UDElement to open and close the backdrop.

Developing a Dashboard with VS Code

The provides integration for working with dashboards. We recommend you also install the .

To add a new dashboard, visit the admin console and go to Dashboard Dashboards and click the Add Dashboard button.

After adding the dashboard, a dashboard PS1 file will be created and the dashboards.ps1

Triggers allow for automation jobs to be started when certain events happen within PowerShell Universal. For example, this allows you to take action when jobs complete, the server starts or dashboards stop. Triggers are useful for assigning global error handling or sending notifications when certain things happen.

Circular Progress

Linear Indeterminate

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

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.

The UDUpload component is used to upload files to Universal Dashboard. You can process files the user uploads. You will receive the data for the file, a file name and the type of file if it can be determined by the web browser.

This component works with and .

Uploading a File

Uploads a file and shows the contents via a toast.

The body of the OnUpload

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

Date pickers can be used in and .

OnChange Event Handler

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

Universal Dashboard v3 is built on Material UI. Material UI provides a that UD now takes advantage of. You can utilize this theme system by providing a hashtable of options to the New-UDDashboard 's -Theme parameter.

Here's an example of changing the theme's main color.

Setting the default theme

You can set the default theme to either Light or Dark using the -DefaultTheme

The code editor component allows you to host the editor within your dashboards.

The App Bar displays information and actions relating to the current screen.

The top App Bar provides content and actions related to the current screen. It's used for branding, screen titles, navigation, and actions.

AppBar with Custom Drawer

List Locked Accounts

This example uses Universal Automation.

Shows an example of how to list locked Active Directory accounts. This example assumes that the user running PowerShell Universal has access to the local Active Directory environment.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUScript -Name 'LockedAccounts' -ScriptBlock {
        Search-ADAccount -LockedOut
    }
}

Locked accounts will be listed on the job page's pipeline output.

You can also access the locked accounts by using the Universal PowerShell module.

Reset Password

This example uses .

Shows an example of how to reset an Active Directory user account using PowerShell Universal Automation. This script accepts the identity of the account to reset, the password to set, whether to unlock the account and whether to require the user to change their password on logon.

Restore Deleted User

This account users PowerShell Universal and .

In this example, we use Universal Dashboard to create a dashboard that displays a table that includes all the deleted user accounts for the domain. It creates a custom column with a button that includes a Restore button that executes a script to restore the specified account. This example assumes that the identity running the script is capable of accessing Active Directory.

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

 New-UDChip -Label 'Basic'

Chips with Icons

OnClick

Shows a toast when the chip is clicked.

OnDelete

New-UDChip

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.

Auto Refresh

Dynamic regions enable the ability to auto refresh components after a certain amount of time. The entire region's script block will be run when autorefreshing.

Loading Component

Sometimes refreshing a dynamic component may take some time. For example, if you are querying another service's REST API or a data. Dynamic regions support configuration of the component that shows when the region is reloading. By default, nothing is shown. This can be any Universal Dashboard component.

API

New-UDDynamic

Defines a dynamic region on a page.

Modals inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

Basic

Full Screen

Full Width

Full width modals take up the full width as defined by the -MaxWidth parameter.

Persistent

Persistent modals do not close when you click off of them. You will have to close it with Hide-UDModal.

Hide a Modal

You can use the Hide-UDModal button to hide a modal that is currently show.

Show-UDModal

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

Vertical Tabs

Dynamic Tabs

Dynamic tabs will refresh their content when they are selected. You will need to include the -RenderOnActive parameter to prevent all the tabs from rendering even if they are not shown.

New-UDTabs

New-UDTab

Select components are used for collecting user provided information from a list of options.

Simple Select

Create a simple select with multiple options.

Grouped Select

Create a select with groups of selections.

OnChange

Execute a PowerShell event handler when the value of the select is changed.

Get-UDElement

Retrieve the value of the select from another component.

New-UDSelect

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

OnChange

An event handler that is called when the radio group is changed. the $Body variable will contain the current value.

Default Value

Set the default value of the radio group.

Custom Formatting

You can use custom formatting within the radio group. The below example will place the radio buttons next to each other instead of on top of each other.

New-UDRadio

In Material Design, the physical properties of paper are translated to the screen.

The background of an application resembles the flat, opaque texture of a sheet of paper, and an application’s behavior mimics paper’s ability to be re-sized, shuffled, and bound together in multiple sheets.

Paper

New-UDPaper -Elevation 0 -Content {} 
New-UDPaper -Elevation 1 -Content {} 
New-UDPaper -Elevation 3 -Content {}

Square Paper

By default, paper will have rounded edges. You can reduce the rounding by using a square paper.

Colored Paper

The -Style parameter can be used to color paper. Any valid CSS can be included in the hashtable for a style.

The following example creates paper with a red background.

New-UDPaper

Transitions allow you to transition components in and out of view within your dashboard using various animations. You can take advantage of interactive cmdlets like Set-UDElement to change the transition state and cause an element to move in.

In the following example, we have a card that transitions in via a Fade. Clicking the switch the toggle the card in and out.

The resulting effect looks like this.

Collapse

The collapse transition will collapse a section in and out. You can specify a collapse height to only collapse a portion of the section.

Fade

A fade transition fades a component in and out as seen in the previous example. You can configure the timeout value to specify the number of seconds it takes to complete the transition.

Slide

The slide transition moves a component into position. You can determine the position of the slide by specifying the -SlideDirection parameter.

Grow

The grow transition will fade and grow a component into place.

Zoom

The zoom transition will zoom a component into place.

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

Slider with minimum and maximum values

Disabled Slider

Slider with custom step size

Slider with marks

Range based slider

OnChange event for slider

New-UDSlider

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.

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.

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.

Variables

There are a set of predefined variables that are available in API endpoints. You'll be able to use these variables in your scripts.

Related Cmdlets

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

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

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

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

Published folders allow you to share a local folder through your Universal website. Any file within the published folder will be accessible via a web request. This can be helpful for storing images or other files that you may want to provide via your Universal Dashboard.

Publishing a Folder

From the Dashboard / Published Folders page, you can click Add Published Folder. You will need to enter the local path as well as the request path. The local path is the folder that you wish to publish. The request path is the path that the end user will request to download the files from the folder.

You can choose to turn on authentication and authorization for the folder.

PowerShell Universal Dashboard v2.9 is a PowerShell module that allows you to create dashboard with PowerShell script. It is the predecessor to PowerShell Universal. The technology the enabled UD has been migrated into PowerShell Universal. You should be able to run the same PowerShell scripts in PowerShell Universal that you would in Universal Dashboard with some minor modifications.

Migrating from Universal dashboard to PowerShell Universal