Downloads

Download the latest version of PowerShell Universal.

Blog

The Ironman Software blog has articles about PowerShell Universal.

Forums

Connect with the PowerShell Universal community.

Discord

Chat with other PowerShell Universal users.

Purchasing

Purchase a license for the features of PowerShell Universal.

Issue Tracker

File a bug report or feature request for PowerShell Universal.

Samples

Samples that can be inserted into your PowerShell Universal system using the PowerShell Universal extension for Visual Studio Code.

Videos

Check out video tutorials for PowerShell Universal.

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.

Data Persistence

Data is persisted in a LiteDB database with a default location of %ProgramData%\UniversalAutomation\database.db. The database will not be deleted during an upgrade of any kind. Any schema updates to the database will happen the first time you start up the new version of Universal. You may wish to backup your database before performing an upgrade.

Configuration Persistence

Configuration files are stored by default in %ProgramData%\UniversalAutomation. Configuration files may be updated or transformed during an update. This will happen the first time that the new version of Universal server is started. You may wish to backup your configuration files before performing an upgrade.

If you are using git, changes to the Universal files will be synchronized after the server starts up.

appsettings.json

The appsettings.json file that is included in the application installation directory will be overwritten during upgrades. To avoid losing your settings in this file, consider installing it into the %ProgramData%\PowerShellUniversal folder. Universal will look at this folder first for configuration settings.

web.config

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 binaries stored in a different location.

Dashboard Components and Frameworks

New versions of Universal may include new versions of Universal Dashboard Frameworks or Components. By default, these components and frameworks are deployed to %ProgramData%\PowerShellUniversal during startup of the Universal server. During an upgrade, these files are not deleted. This ensures that dashboards will continue to run on the previous dashboard framework and component versions.

You should have multiple versions of the dashboard frameworks and components available when you start the new version of Universal.

By default, new dashboards are set to always use the latest version of the dashboard framework. You can chose to set it to a specific version if you would like but will have to manually change the version during an upgrade.

Repository

Most of the settings for PowerShell Universal are stored within the repository folder. By default, this is in %ProgramData%\UniversalAutomation\Repository. While the upgrade should not affect these files, you may want to backup the files before upgrading.

ZIP Upgrade

When upgrading an manual ZIP file installation, you will need to stop the application, delete the entire binary folder and replace it with the new binary folder. When you start the new version of Universal, new dashboard frameworks and components will be deployed and the existing database will be loaded.

MSI Upgrade

To upgrade using the MSI, you can simply run the new version of the MSI. The MSI is setup to always perform a major upgrade. This means it will stop and remove the service, delete the entire installation directory, reinstall with the new files and then install and start the new service.

You will want to follow the guide on data and configuration persistence above to ensure all your settings are saved.

IIS Upgrade

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. Ensure that you follow the configuration persistence recommendations above with regards to the web.config file.

LiteDB v5 Upgrade

PowerShell Universal uses LiteDB to store jobs, app tokens, identities and git sync history. The original version of LiteDB included with PSU is version 4. We will be moving to version 5 in a future version. We have added version 5 support but are not yet upgrading users databases. You can choose to upgrade your database to version 5 by adjusting your connection string to perform an upgrade on the database. We suggest backing up your database file before doing so.

In appsettings.json, you will need to change the database type to LiteDBv5 and add the upgrade parameter to the connection string.

    "Data": {
    "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
    "ConnectionString": "filename=%ProgramData%\\UniversalAutomation\\database.db;upgrade=true",
    "DatabaseType": "LiteDBv5",

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: Chrome, Firefox, Safari, and Microsoft Edge

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

• Build REST endpoints with PowerShell

• Accept common HTTP verbs

• Process request bodies

• Build dynamic URLs with route parameters and query strings

Automation

• Run scripts and view output, pipeline output, and parameters

• Respond to feedback from cmdlets like Read-Host

• Schedule scripts with CRON or one-time schedules

• Automatically build input forms based on param blocks

• Set variables and secrets that can be used throughout scripts

Dashboard

• Build web pages with PowerShell script

• Include input forms, charts and tables

• Build interactive websites with buttons, message boxes and more

Platform

• Cross-platform and supported on Windows and Linux

• Git integration for configuration files, scripts and dashboards

• Built-in authentication and authorization

• Support for Windows PowerShell as well as PowerShell

Licensing

Universal is licensed per feature and per server. You do not need to buy the entire platform if you would like to use a single piece of functionality. Visit our website for more information on pricing.

Free to Use

Universal offers a lot of functionality for free. Below is a list of the features that require a paid license.

API

You can run as many APIs are you want for free. You will need to purchase a license if you would like to enable authentication, authorization and rate limiting.

Automation

With the free version of Automation you can run up to 25 jobs a day with 2 jobs running concurrently. You will need a license to use triggers.

Dashboard

With the free version of dashboard, you can run unauthenticated dashboards. You will not have access to the diagnostics or console pages.

Getting Started

PowerShell Module

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

Install-Module Universal

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

Install-PSUServer -LatestVersion

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

Install-PSUServer -Path (Join-Path $Env:AppData "PSU")

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

Install-PSUServer -AddToPath

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

Start-PSUServer -Port 8080

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.

Start-PSUServer -Port 8080 -ExecutablePath (Join-Path $MyPath "Universal.Server.exe")

Chocolatey Package (Windows)

You can install PowerShell Universal using the Chocolatey package. 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.

choco install powershelluniversal

Winget (Windows)

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

winget install ironmansoftware.powershelluniversal

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.

winget install ironmansoftware.powershelluniversal --silent

ZIP Install

You can also download the ZIP from our Downloads page 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.

Expand-Archive -Path .\Universal.zip -DestinationPath .\Universal
Get-ChildItem .\Universal -Recurse | Unblock-File
Start-Process .\Universal\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 Docker page.

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!

Windows

• or greater or PowerShell v7.0 or greater

• (only for Windows PowerShell)

Linux

• PowerShell v7.0 or great

• Validated Distributions: Ubuntu 18.04

Mac OS X

Component Examples

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

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
• Hyper-V
• Image Processing
• Monitoring
• Slack

Installation

Our docker image is available on . 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.

List Locked Accounts

This example uses .

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.

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

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

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.

Install PowerShell Universal

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

Open PowerShell Universal

By default, PowerShell Universal is running on port 5000 of localhost. You can access the admin console with the user name admin and any password.

PowerShell Universal Visual Studio Code Extension

You can connect to your instance of PowerShell Universal, browse and insert samples and get up and running right away.

Install the Extension

Install the extension by searching for it in the extension page and clicking Install.

Connect to PowerShell Universal

Click the PowerShell Universal icon on the left hand side and the extension will attempt to connect using the default URL and user name. The extension will notify you once it has connected.

Inserting a Sample

Learn more about the various features of PowerShell Universal

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.

Configuration

The extension will prompt you for the URL and App Token used to connect to your PowerShell Universal instance. Follow the instructions within the extension when it starts up.

Features

The PowerShell Universal extension adds a new activity pane panel for PowerShell Universal. It has the following sections.

APIs

You can manage APIs with the extension. You will see a list of APIs. You can click the Open endpoints.ps1 button to view the endpoints file and add new endpoints. Clicking the refresh button will reload any endpoints you add. You can click the Insert Invoke-RestMethod to Console to add a call to the endpoint to the PowerShell Integrated Console.

Dashboards

You can manage dashboards with the extension. You will see a list of dashboards underneath this section. You can open the dashboards.ps1 script, open the a single dashboard's script, restart a dashboard and view dashboards. When you open a dashboard script, the dashboard modules will automatically be loaded so that IntelliSense works in VS Code.

Debug Dashboard Process

You can connect the Visual Studio debugger to the dashboard process by right clicking on the dashboard and click Debug Dashboard Process. This requires the PowerShell extension for Visual Studio Code.

After connecting the debugger, you can run commands such as Get-Runspace and Debug-Runspace to begin debugging aspects of your dashboard.

View Dashboard Logs

You can view dashboard logs by right clicking on the dashboard and clicking View Logs. They will open in a new tab.

Scripts

You can manage scripts with the extension. You will see a list of available scripts underneath this section. You can edit the scripts.ps1, edit an individual script and run scripts. When running scripts, you will receive feedback about the status of the script. Scripts with parameters are not supported in VS Code. You can still run them in PowerShell Universal.

Sample Browser

The sample browser can be used to insert samples from the PowerShell Universal Sample Repository into your PowerShell Universal instance. Just save the files it updates and your PowerShell Universal system will reflect the changes.

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

You can purchase a license on .

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

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 Protect Configuration

This configuration checks to see if the user has included the string \\corp\human-resources anywhere in their script. If they do, it sends an HTTP POST to the URL http://localhost:8080/protect

The body of the HTTP request will contain the computer name and user name separated by a comma.

PowerShell Universal Configuration

This PSU configuration defines an endpoint to accept the POST data from PowerShell Protect. It then saves the data to a file. It also defines a dashboard that will read the data and display it in a table. This assumes that you have installed the PowerShell Universal module and server.

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.

New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
   "Hello, world!"
}

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

Invoke-RestMethod http://localhost:5000/endpoint

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.

New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

To call this API and specify the ID, you would do the following.

Invoke-RestMethod http://localhost:5000/user/123

Query String Parameters

Query string parameters are automatically passed into endpoints as variables that you can then access. For example, if you had an endpoint that expected an $Id variable, it could be provided via the query string.

New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

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

Invoke-RestMethod http://localhost:5000/user?Id=123

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.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    $User = ConvertFrom-Json $Body 
    New-User $User
}

To call the above endpoint, you would have to specify the body of Invoke-RestMethod.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}"

Form Data

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

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
     
    New-User $UserName -FirstName $FirstName -LastName $LastName
}

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

Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
}

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.

New-PSUEndpoint -Url '/user/:name' -Endpoint {
    param([Parameter(Mandatory)$Name, $Role = "Default")
}

Returning Data

Data returned from endpoints will be assumed to be JSON data. If you return an object from the endpoint script block, it will be 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.

New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
    $Data
}

PS C:\Users\adamr> iwr http://localhost:5000/file -method post -InFile '.\Desktop\add-dashboard.png'

StatusCode        : 200
StatusDescription : OK
Content           : [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,2,17,0,0,1,92,8,2,0,0,0,249,210,123,106,0,0,0,1,
                    115,82,71,66,0,174,206,28,233,0,0,0,4,103,65,77,65,0,0,177,143,11,252,97,5,0,0,0,9,112,72,89,115,0,
                    0,…

You could also save the file into a directory.

New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
    [IO.File]::WriteAllBytes("tempfile.dat", $Data)
}

Downloading Files

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

New-PSUEndpoint -Url '/image' -Endpoint {
    $ImageData = [IO.File]::ReadAllBytes("image.jpeg")
    New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData
}

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.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -StatusCode 410
}

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

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404
}

Invoking the REST method will return the custom error code.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file

Invoke-RestMethod: Not what you're looking for.

You can control the content type of the data that is returned by using the -ContentType parameter.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "<xml><node>1</node><node2>2</node2></xml>" -ContentType 'text/xml'
}

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 will be reset after each execution. This will cause variables, modules and functions defined during the execution of the API to be removed.

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

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

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

Set-PSUSetting -ApiEnvironment 'Env'

Related Cmdlets

• New-PSUEndpoint

• Get-PSUEndpoint

• Remove-PSUEndpoint

• New-PSUApiResponse

• Set-UASetting

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

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.

Virtual Machine Creator

This example uses PowerShell Universal Dashboard.

This example can be used to create virtual machines on a Hyper-V host. This dashboard assumes it's being run on the host in question. You could adjust the dashboard script to run on a remote host.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'Hyper-V' -BaseUrl '/' -Framework 'UniversalDashboard:Latest' -Content {

        $HostRam = Get-WMIObject -class Win32_PhysicalMemory | Measure-Object -Property capacity -Sum | % {[Math]::Round(($_.sum / 1GB *0.97),0)-1}
        $HostName=hostname
        $SwitchList = @()
        Get-VMSwitch | Select-Object -ExpandProperty name | ForEach-Object {
            $SwitchList += $_
        }

        function Run-Checks
        {
            $VMHostInfo= Get-VMHost

            $BootISOTextBoxText = (Get-UDElement -Id 'VMBootISO')['value']
            $VHDRootTextBoxText = (Get-UDElement -Id 'VMVHDRoot')['value']
            $VMNameTextBoxText = (Get-UDElement -Id 'VMName')['value']
            $Generation = (Get-UDElement -Id 'VMGeneration')['value']
            $SwitchNameComboBoxText = (Get-UDElement -Id 'VMSwitch')['value']
            $RAMinGBTextBoxText = (Get-UDElement -Id 'VMRam')['value']
            $CPUCountTextBoxText = (Get-UDElement -Id 'VMCPU')['value']
            [int64]$VLANIDTextBoxText = (Get-UDElement -Id 'VMVLan')['value']

            #Paths and Gen Sets    
            if ($BootISOTextBoxText -and $BootISOTextBoxText -ne "") {$ISOFilePathValid = test-path $BootISOTextBoxText}
            if ($VHDRootTextBoxText -and $VHDRootTextBoxText -ne "") {$VHDBootPathValid = test-path $VHDRootTextBoxText}
            if ($Generation -eq 'Gen1') { $VMGeneration = 1 } else { $VMGeneration = 2 } 

            if ($VMNameTextBoxText.Length -ne 0) { $VMExists = Get-VM -name $VMNameTextBoxText -ErrorAction SilentlyContinue }

            if (-not (Test-Path $VMHostInfo.VirtualMachinePath) ) {Show-UDToast -Message  "Default Virtual Machine path is not valid in HyperV Host Settings"}
            elseif (-not (Test-Path $VMHostInfo.VirtualHardDiskPath) ) {Show-UDToast -Message  "Default Virtual Harddisk path is not valid in HyperV Host Settings"}
            elseif ($VMExists) {Show-UDToast -Message  "VM with that name already exists"}
            elseif ($VMNameTextBoxText.Length -eq 0) {Show-UDToast -Message  "Please Enter VM Name"}
            elseif ($SwitchNameComboBoxText -eq "Switch Name") {Show-UDToast -Message  "Please Select a Switch Name"}
            elseif ($ISOFilePathValid -eq $False) {Show-UDToast -Message  "ISO File path in invaild"}
            elseif ($VHDRootTextBoxText -eq "") {Show-UDToast -Message  "VHD Root path is blank.  Please enter a valid path"}
            elseif ($VHDBootPathValid -eq $False) {Show-UDToast -Message  "VHD Root path in invaild"}
            elseif ($RAMinGBTextBoxText.Length -eq 0) {Show-UDToast -Message  "Please Enter Ram Amount in GB"}
            elseif ([int64]$RAMinGBTextBoxText -lt 1) {Show-UDToast -Message  "Please Enter Ram Amount of at least 1GB"}
            elseif ([int64]$RAMinGBTextBoxText -gt $HostRam) {Show-UDToast -Message  "Please Enter Ram Amount of "+ $HostRam + "GB or bellow"}
            elseif ($CPUCountTextBoxText.Length -eq 0) {Show-UDToast -Message  "Please Enter a CPU Count"}
            elseif ([int64]$CPUCountTextBoxText.Length -eq 0) {Show-UDToast -Message  "Please Enter a CPU Count"}
            elseif ([int64]$CPUCountTextBoxText -lt 1) {Show-UDToast -Message  "Please Enter a CPU Count of at least 1"}
            elseif ([int64]$CPUCountTextBoxText -gt 64) {Show-UDToast -Message  "Please Enter a CPU Count of 64 or below"}
            elseif ([int64]$VLANIDTextBoxText -gt 999 -or [int64]$VLANIDTextBoxText -lt 1) {Show-UDToast -Message  "Please Enter VLAN ID between 1 and 999."}
            else 
            {
                (65..90) | ForEach-Object { 
                    $DriveLetter = [char]$_  

                    [int64]$value = (Get-UDElement -Id "Drive$DriveLetter")['value']

                    if ($value -gt 65536)
                    {
                        Show-UDToast -Message  "For $DriveLetter Drive please Enter a Disk Size of 65536 GB or below"
                        return $false
                    }
                } 

                Show-UDToast -Message  "Looking Good Man ;)"

                return $true
            }

            return $false
        }

        function Create-VMs
        {
            Run-Checks

            $BootISOTextBoxText = (Get-UDElement -Id 'VMBootISO')['value']
            $VHDRootTextBoxText = (Get-UDElement -Id 'VMVHDRoot')['value']
            $VMNameTextBoxText = (Get-UDElement -Id 'VMName')['value']
            $Generation = (Get-UDElement -Id 'VMGeneration')['value']
            [int]$SwitchNameComboBoxIndex = (Get-UDElement -Id 'VMSwitch')['value']
            $SwitchNameComboBoxText = $SwitchList[$SwitchNameComboBoxIndex]
            Show-UDToast -message ((Get-UDElement -Id 'VMSwitch') | ConvertTo-Json)
            $RAMinGBTextBoxText = (Get-UDElement -Id 'VMRam')['value']
            $CPUCountTextBoxText = (Get-UDElement -Id 'VMCPU')['value']
            $VLANIDTextBoxText = (Get-UDElement -Id 'VMVLan')['value']

            if ($Generation -eq 'Gen1') { $VMGeneration = 1 } else { $VMGeneration = 2 } 

            #Create VM

            try
            {
                New-VM -Name $VMNameTextBoxText -MemoryStartupBytes ([int]$RAMinGBTextBoxText*1073741824) -SwitchName $SwitchNameComboBoxText -Generation $VMGeneration -ErrorAction Stop
            }
            catch
            {
                $VMCrateFailed=$True
                Show-UDToast -Message ("VM " + $VMNameTextBoxText + " Failed to Create :( $($_.Exception.Message)")
            }


            if (-Not($VMCrateFailed -eq $True))
            {
                (65..90) | ForEach-Object { 
                    $DriveLetter = [char]$_  
                    [int64]$value = (Get-UDElement -Id "Drive$DriveLetter")['value']
                    if ($value -gt 0)
                    {
                        $Path = $VHDRootTextBoxText+"\"+$VMNameTextBoxText+"\"+$VMNameTextBoxText+"-"+$value+".vhdx"
                        if (-not (test-path $Path)) 
                        {
                            New-VHD -Path $Path -SizeBytes (Invoke-Expression ("$($Value)GB")) -Dynamic
                        } 
                        else 
                        {
                            $VHDPathExisted = $true
                        }
                    }
                } 

            Get-VM $VMNameTextBoxText | Set-VMProcessor -Count $CPUCountTextBoxText
            Get-VM $VMNameTextBoxText | set-VMNetworkAdapterVlan -Access -vlanId $VLANIDTextBoxText

            (65..90) | ForEach-Object { 
                $DriveLetter = [char]$_  
                [int64]$value = (Get-UDElement -Id "Drive$DriveLetter")['value']
                $Path = $VHDRootTextBoxText+"\"+$VMNameTextBoxText+"\"+$VMNameTextBoxText+"-"+$value+".vhdx"

                if (Test-Path $Path)
                {
                    Add-VMHardDiskDrive -VMName $VMNameTextBoxText -Path $Path -ControllerType SCSI -ControllerNumber 0
                }
            } 

            # 
            #  REMOVING NETWORK FROM THE BOOT ORDER

            #Set New Boot order
            if ($VMGeneration -eq "2")
                {
                    $old_boot_order = Get-VMFirmware -VMName $VMNameTextBoxText -ComputerName $HostName | Select-Object -ExpandProperty BootOrder
                    $new_boot_order = $old_boot_order | Where-Object { $_.BootType -ne "Network" }
                    Set-VMFirmware -VMName $VMNameTextBoxText -ComputerName $HostName -BootOrder $new_boot_order
                }


            #  ADD DVD Drive with ISO Attached
            if ($BootISOTextBoxText -ne "")
            {
                Get-VM $VMNameTextBoxText | Add-VMDvdDrive -Path $BootISOTextBoxText
            }

            if ($VHDPathExisted) {
                Show-UDToast -Message ("VM " + $VMNameTextBoxText + " Created OK, but at least one VHD already existed and was just reattached")
            }
            else 
            {
                Show-UDToast -Message ("VM " + $VMNameTextBoxText + " Created OK")}
            }
        }


        New-UDDashboard -Title "Hyper-V VM Creator" -Content {
            New-UDContainer -Children {
                New-UDTypography -Text "Hyper-V VM Creator" -Variant h3 

                New-UDRow -Columns {
                    New-UDColumn -LargeSize 6 -Content {
                        New-UDRow -Columns {
                            New-UDTextbox -Label 'VM Name' -Id 'VMName'
                        }
                        New-UDRow -Columns {
                            New-UDTextbox -Id 'VMRam' -Label 'RAM in GB' -Value $HostRam
                        }
                        New-UDRow -Columns {
                            New-UDTextbox -Id 'VMCPU' -Label 'CPU Count' -Value 2
                        }

                        New-UDRadioGroup -Label 'Generation' -Id 'VMGeneration' -Children {
                            New-UDRadio -Label 'Gen 1' -Value 'Gen1'
                            New-UDRadio -Label 'Gen 2' -Value 'Gen2'
                        } -Value 'Gen1'
                    }
                    New-UDColumn -LargeSize 6 -Content {
                        New-UDRow -Columns {
                            New-UDSelect -Id 'VMSwitch' -Label 'Switch Name' -Option {
                                $i = 0
                                $SwitchList | ForEach-Object {
                                    New-UDSelectOption -Value $i -Name $_
                                    $i++
                                }
                            }
                        }

                        New-UDTextbox -Id 'VMVLan' -Label 'VLAN ID'
                    }
                }

                New-UDRow -Columns {
                    New-UDColumn -LargeSize 12 -Content {
                        New-UDTextbox -Id 'VMBootISO' -Label 'Boot ISO'
                    }
                }

                New-UDRow -Columns {
                    New-UDColumn -LargeSize 12 -Content {
                        New-UDTextbox -Id 'VMVHDRoot' -Label 'VHD Root'
                    }
                }

                New-UDTypography -Text 'Drives' -Variant h4

                New-UDRow -Columns {
                    New-UDColumn -LargeSize 6 -Content {
                        New-UDRow -Columns {
                            # Loop through each letter of the alphabet
                            (65..90) | ForEach-Object { 
                                New-UDColumn -LargeSize 6 -Content {
                                    $DriveLetter = [char]$_  
                                    New-UDTextbox -Id "Drive$DriveLetter" -Placeholder $DriveLetter
                                }
                            } 
                        }
                    }
                    New-UDColumn -LargeSize 6 -Content {
                        New-UDButton -Text 'Do Some Checks' -OnClick { Run-Checks }
                        New-UDButton -Text 'Im feeling lucky Create Vm' -OnClick { Create-VMs }
                    }
                }
            }
        }
    }

}

Send Message to Slack

This example uses Universal API.

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

Start-PSUServer -Port 8080 -Configuration {
    New-PSUEndpoint -Url "/slack" -Method POST -Endpoint {

        $Body = @{
            text = "Hello"
        } | ConvertTo-Json

        Invoke-RestMethod -Uri 'https://hooks.slack.com/services/0000000000/00000000/00000000000000000' -Body $Body -Method POST
    }
}

You can invoke this API by calling Invoke-RestMethod

Invoke-RestMethod http://localhost:8080/slack -Method POST

The following message will show up in Slack.

Send Slack Message on Failed Job

This following example uses Universal Automation. This example requires a license.

This example takes advantage of triggers to send a message to Slack when a job fails within PowerShell Universal. We define two scripts. The first script simply throws and error and is set to fail by using the -ErrorAction Stop setting. The second script receives the job that failed and sends a message to the team's Slack channel.

Start-PSUServer -Port 8080 -Configuration {

    Set-PSULicense -Key 'license'

    New-PSUScript -Name 'ScriptFailed' -ScriptBlock {
        $Body = @{
            text = "Job $($Job.Id) failed!!"
        } | ConvertTo-Json

        Invoke-RestMethod -Uri 'https://hooks.slack.com/services/00000000/00000000/000000000000000' -Body $Body -Method POST
    }

    New-PSUScript -Name 'FailingScript' -ScriptBlock {
        throw "NoooooO!"
    } -ErrorAction Stop

    New-PSUTrigger -Name 'ScriptFailed' -TriggerScript 'ScriptFailed.ps1' -EventType 'JobFailed'
}

When the failing script is running, it will report failure in the UI.

Due to the failure, the trigger will execute and send a message to Slack.

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.

New-PSUEndpoint -Url "/test" -Endpoint { 
    # Enter your script to process requests.
}

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.

New-PSUEndpoint -Url "/test" -Endpoint { 
 "hello"
}

New-PSUEndpoint -Url "/test2" -Endpoint { 
    # Enter your script to process requests.
}

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

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

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.

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

Retro Dashboard

This retro looking dashboard displays the top 10 CPU and memory using processes, disk usage, and live CPU and network usage. It also demonstrates how to use themes to custom the backcolor, text color and font family.

Windows Performance Counter Charts

In this example, we take advantage of Universal Dashboard scheduled endpoints, the in-memory cache and the UDMonitor component. We update the counter sets to use in the cache and load each of the counters' value in the set into an array to use in the dashboard. We then create a dashboard that dynamically creates UDMonitor charts within the page. Each monitor will update every 3 seconds with new data.

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.

Configuring Rate Limiting

To configure rate limiting, you can visit the APIs / Rate Limiting page. Click the Add button and define a new rate limit rule.

Method

The Method is the HTTP method to for this rule. If you use * , all HTTP methods will be affected by this rule. You can also select a single method by picking it from the drop down.

Endpoint

The endpoint is the URL that you are rate limiting. You can rate limit all URLs by using a *. You can define specific URLs by define the relative path: /api/user.

Limit

The number of request in the time frame before rate limiting kicks in.

Period

The period over which the rate limit is counted. For example, if you select a period of 10 minutes and a limit of 100, then up to 100 requests can be made to the method and endpoint you have selected.

Allow Lists

To disable rate limiting for particular IP Addresses, clients and endpoints you can add them to the rate limiting allow lists. You will find these by clicking the settings button.

Related Cmdlets

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

To add a new script to the Universal platform, you can create the PS1 file on the file system and then add the script to the scripts.ps1. The file name is relative to the repository folder. You can also use fully qualified file paths.

To edit a script in VS Code, click the Edit Script button.

The script will open in the VS Code editor.

Running Scripts

You can start scripts by clicking the Run Script button. This will start a Universal Automation job. You'll get notifications of the job's progress in VS Code.

Developing Schedules

You can edit schedules for scripts by editing the schedules.ps1 file. A link to the file is available in the configuration tree view.

Schedules are defined using New-PSUSchedule cmdlet.

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.

Terminating errors will always return a 500 Internal Server Error.

You will notice different behavior in Windows PowerShell and PowerShell 7 when calling REST APIs that return errors. In Windows PowerShell, you will receive a generic error that doesn't return the error message.

In PowerShell 7, when an error is returned, you will see the error message returned.

You can retrieve the error message in Windows PowerShell, by using the following syntax.

Manually Returning Errors

To manually return errors, you need to use the New-PSUApiResponse cmdlet. This cmdlet allows you to define the status code and body for the response.

In this example, we are returning a 404 error code from the endpoint.

Similar to the automatic error codes, error codes returned manually will as display better in PowerShell 7. Here's an example of calling the endpoint.

If called from Windows PowerShell, you will receive an error similar to the one returned automatically.

You can choose to return error codes if certain conditions are met by using your PowerShell script within the endpoint.

Related Cmdlets

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 bee cancelled.

View Job Output

Standard job output is shown on the Output Tab of the job page. This should contain text from various PowerShell streams.

View Job Pipeline Output

Pipeline output for jobs are also stored within UA. 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.

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.

Invoking Jobs from PowerShell

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-UAScript 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-UAJob.

Waiting for a Script to Finished

You can use the Wait-UAJob cmdlet to wait for a job to finish. Pipe the return value of Invoke-UAScript to Wait-UAJob to wait for the job to complete. Wait-UAJob 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.

Invoke a Script and Wait for Output

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.

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

To provide parameters to scripts, you will need to define the parameters are part of the body. Currently the value is required to be a CLIXML string.

To generate CLIXML, you can use the PSSerializer class in PowerShell. You can pass any object into the serialize method.

If you want to pass a credential you will need to pass in the parameter as a variable. You do not need to serialize the variable name.

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.

Variables Defined in Jobs

There are several built-in variables that are defined when a job is run. You can use these variables in your scripts to retrieve information about the current job.

Retrieving the user that started a script

You can retrieve the name of the user that started the script by using the UAJob variable

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

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

Parameters

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

Basic Parameters

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

Type Parameters

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

String

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

String Arrays

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

Date and Time

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

Boolean

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

Integer

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

Switch Parameter

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

Enumerations

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

Help Messages

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

Required Parameters

You can use the Parameter attribute to define required parameters.

Passing Parameters from PowerShell

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

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

I could then invoke that script using this syntax.

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

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

• Universal Dashboard v3

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.

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

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 on GitHub.

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

New-UDPage -Content {
    New-UDTextbox
}

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.

$Pages = @()
$Pages += New-UDPage -Name 'My Home Page' -Content {}
$Pages += New-UDPage -Name 'Diagnostics' -Content {}
New-UDDashboard -Pages $Pages -Title 'Dashboard'

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.

$DebugPreference = 'Continue'

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.

$Cache:Computers = Get-ADComputer

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

New-UDMonitor -Title Computers -Endpoint {
    $Cache:Computers.Length | Out-UDMonitorData
}

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.

New-UDCheckbox -Label "Show chart" -OnChange {
   $Session:ShowChart = $EventData
}

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

New-UDColumn -Endpoint {
    if ($Session:ShowChart) {
         New-UDChart ...
    }
}

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

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

No need to call Start-UDDashboard

In Universal, all you need to do is return the result of New-UDDashboard from your script. There is no need to call Start-UDDashboard. The configuration of the webserver is taken place using the PSU appsetting.json file.

New-UDDashboard -Title 'My dashboard' -Content {

}

No need to call New-UDEndpointInitialization

This cmdlet has been removed from Universal Dashboard. There is no longer a need to call it.

Scheduled Endpoints

You do not need to pass the value of a scheduled endpoint to anything. You can just call New-UDEndpoint with a endpoint schedule and it will automatically be registered with PSU.

$Schedule = New-UDEndpointSchedule -Every 10 -Minute
$Endpoint = New-UDEndpoint -Schedule $Schedule -Endpoint {}

REST APIs

To learn more about APIs, click here.

Authentication and Authorization

Authentication and authorization are now handled by PSU and there is no need to configure UD login pages. Authentication and authorization are configured with the PSU appsettings.json file. Dashboard's themselves can be either authenticated or not authenticated. A license is required to enable authenticated dashboards.

To enable role-based access controls, you can assign roles to pages and use the automatic $Roles variable to check which roles the user is a part of. The $User variable will provide the name of the user.

Authorization Policies

Authorizations policies in Universal work very similar to the ones in Universal Dashboard, you will define them using the New-PSURole cmdlet. When you define the role, you have the option to define a policy that will assign that role automatically to a user.

For example, let's adjust a claims policy from Universal Dashboard for Universal.

Universal Dashboard

$AuthorizationPolicy = New-UDAuthorizationPolicy -Name "Policy" -Endpoint {
    param($User)

    $User.HasClaim("group", "administrator")
}

Universal

New-PSURole -Name 'User' -Policy {
   param($User)

   $User.Claims | Where-Object { $_.Type -eq 'group' -and $_.Value -eq 'administrator' }
}

Enforcing Roles

Much like the Get-UDAuthorizationPolicy cmdlet in Universal Dashboard, you also have access to the assigned roles for users in Universal. Simply check the $Roles variable to see which roles the user has.

PS C:\Users\adamr> $Roles = @('Administrator')
PS C:\Users\adamr> if ($Roles -contains 'Administrator') { $true }

Published Folders

Click here to learn more about Published Folders in PowerShell Universal.

Migrating to Universal Dashboard v3

This section contains migration information for upgrading from UDv2 to UDv3. They are vastly different frameworks and will require rewriting your dashboard. Many of the concepts are the same.

Pages

Pages have a different behavior in v3. All pages are dynamic pages. This means that you don't have to worry about whether a page will be generated at run time or doing start up. Pages are always generated during runtime.

If you have a page such as this one:

New-UDPage -Url "/myPage/:owner" -Endpoint {
    param($owner)
}

You can convert it to a v3 page by changing the syntax to:

New-UDPage -Name 'myPage' -Url "/myPage/:owner" -Content {
    param($owner)
}

New-UDTable (formerly UDGrid and UDTable)

Rather than having two cmdlets for tables (New-UDTable and New-UDGrid). The New-UDTable in v3 provides the ability to display data in a table, filter, page, and sort it. It supports both client and server-side processing.

You can view examples of the table on GitHub.

New-UDDynamic

Unlike in v3, components do not have -Endpoint and -Content parameters. Each component will instead simply have a -Content parameter. To achieve dynamic sections of a page, you can instead use the New-UDDynamic cmdlet. This cmdlets let you define an entire section of a page as dynamic. It also provides auto refresh functionality so you can refresh sections of a page all at once.

New-UDDynamic -Content {
    New-UDTypography -Text (Get-Date)
}

New-UDGrid

New-UDGrid allows you to define a grid layout using the Material UI library. You use this single cmdlet to define rows and columns within your dashboard.

You can view examples of the grid on GitHub.

New-UDForm (formerly UDInput)

New-UDInput has been replaced by New-UDForm. The UDForm component allows far more configuration that UDInput did. You will use the standard controls like UDTextbox, UDCheckbox, and UDSelect instead of New-UDInputField. This means that there are a single set of input cmdlets to use for UD.

All of the input control examples can be found on GitHub.

Navigation

Instead of using New-UDSideNav, you will now use a combination of New-UDAppbar and New-UDDrawer. When New-UDAppBar is used with the default position, it will overlay the AppBar at the top of the page. You can then specify a drawer to customize the navigation experience within your dashboard.

You can see examples of how to do navigation on GitHub.

Nivo and Sparklines are now open source

The Nivo and sparklines controls are now open source and on the Universal Dashboard repository. You can now use them without purchasing a license.

For more examples of Nivo and sparklines controls, see GitHub.

Map is now open source

The map control is also open source and on GitHub.

You can find examples on GitHub.

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.

Trigger Events

The following types of events can be assigned a trigger.

• Job Started

• Job Completed

• Job Requesting Feedback

• Job Failed

• Dashboard Started

• Dashboard Stopped

• Server Started

• Server Stopping

Global Triggers

Global triggers will start the assigned script whenever the event type is invoked.

For example, the Script.ps1 will be run whenever any job is run.

New-PSUTrigger -Name 'Trigger' -EventType JobStarted -TriggerScript Script.ps1

Resource Triggers

Resource triggers will start the assigned script when the event takes place on the selected resource.

For example, the Script.ps1 will be run whenever the Dashboard is stopped.

New-PSUTrigger -Name 'Trigger' -EventType DashboardStopped -TriggerScript Script.ps1 -Dashboard 'Dashboard'

Event Metadata

Whenever a job is started from a trigger, it will be provided with metadata about object that caused the event to trigger.

Triggers related to jobs will be provided a $Job parameter.

param($Job)

$Job

Triggers related to dashboards will be provided a $Dashboard parameter.

param($Dashboard)

$Dashboard

Triggers related to the server status will not receive a parameter.

Related Cmdlets

• New-PSUTrigger

• Remove-PSUTrigger

• Set-PSUTrigger

• Get-UAScript

• Get-PSUDashboard

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

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

Scheduling a Job

To schedule a job, you can do so from the Automation / Schedules page and by clicking the New Schedule button. You can also schedule a script by click the Schedule option from the script's page.

Schedules can be defined based on simple selections like Every Minute or Every Hour or you can define CRON expressions yourself for more configurable schedules. You can also run One Time schedules that run once at a later date.

You can also define which user the scheduled job will run under as well as which PowerShell version to use.

Simple Schedules

Simple schedules are really just helpers for various standard CRON schedules. When you select one, it will define a CRON schedule for your.

CRON

CRON schedules use CRON expressions to define schedules. You can use a tool like Crontab guru to help define the schedule.

One Time

One time schedules will run once in the future. You can select the time and day of when they will run.

Continuous

Continuous schedules will run over and over again. You can define a delay between each scheduled job run.

Parameters

Schedules support setting parameters for scripts. For example, if you have a script that accepts a parameter, you can choose to pass a value to the parameter during the schedule.

param($UserName)

$UserName

Within the modal for defining the schedule, you will have the option to set the parameter value.

When editing schedules from PowerShell, you can define the parameters on the New-PSUSchedule cmdlet. This cmdlet accepts dynamic parameters so that you can pass the values in for your schedule.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -UserName 'adam'

Environments

When creating a schedule, you have the option to specify the environment for your job to run. By default, it will use the default environment. You can define an environment in the UI by using the Environment drop down. You can define an environment using the -Environment parameter in New-PSUSchedule.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Environment '7.1'

Run As

You can define which user to run the schedule as by using the Run As selector in the UI. The Run As selector contains a list of PSCredential variables you have defined. You will need to define a PSCredential variable before the Run As selector is visible. By default, scheduled jobs will run under the credentials of the user that is running PowerShell Universal.

You can define a Run As user in a script by using the -Credential parameter. The value should be the name of the variable that contains your credential.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Credential 'MyUser'

Developing a Dashboard with VS Code

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

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 file will be updated. You can view your dashboard in VS Code underneath the dashboards tree view. It will show the current state of the dashboard and the framework it is using.

If you want to edit your dashboard, click the Open Dashboard File button. This will open the dashboard PS1 file in the editor and import the Universal module and Dashboard framework module so you have IntelliSense.

From here, you can begin editing your dashboard.

Your dashboard should restart automatically when you make changes. You will be able to view the dashboard in the browser by clicking the View button.

If you need to restart your dashboard manually, you can click the Restart button.

Developing a Dashboard with Single-File Configuration

You can use the Universal Dashboard PowerShell module and single-file configuration to build a dashboard directly from PowerShell.

Install the Universal Dashboard PowerShell Module. This will install both the Universal Dashboard framework module and the PowerShell Universal module.

Install-Module UniversalDashboard

Install the latest version of the Universal server.

Install-PSUServer -LatestVersion

Create a PS1 file for your configuration data and start the server.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'Dashboard' -BaseUrl '/dashboard' -Framework 'UniversalDashboard:Latest' -Content {
        New-UDDashboard -Title 'Hello, World' -Content {
            New-UDForm -Content {
                New-UDTextbox -Label 'Say Hi' -Id 'textbox'
            } -OnSubmit {
                Show-UDToast -Message $EventData.textbox
            }
        }
    }
}

Navigate to your dashboard.

Start-Process http://localhost:8080/dashboard

Changes you make to your PS1 file will cause Universal to automatically reload your dashboard and reflect the changes.

Debugging a Dashboard

Logs

You can view the dashboard logs by right clicking on the Dashboard and clicking View Log. The log should provide information about start up issues or errors when executing sections of your dashboard.

Debugger

You can debug individual endpoints within your dashboard by using Wait-Debugger

For example, if I wanted to debug the button on my dashboard, I would add it to the OnClick event handler.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDTypography -Text "Hello, World!"

    New-UDButton -Text "Learn more about Universal Dashboard" -OnClick {
        Wait-Debugger
        Invoke-UDRedirect https://docs.ironmansoftware.com
    }
}

Now, I can right click on my dashboard and click Debug Dashboard Process.

This will issue an Enter-PSHostProcess command in the Integrated Terminal.

PS C:\Users\adamr\Desktop> Enter-PSHostProcess -Id 15464

[Process:15464]: PS C:\Users\adamr\Documents>

Next, you'll want to navigate to your page and click the button. Once the button is clicked, issue a Get-Runspace command in the Integrated Terminal. You'll notice that one of the runspaces is in InBreakpoint availability.

[Process:15464]: PS C:\Users\adamr\Documents> Get-Runspace


 Id Name            ComputerName    Type          State         Availability
 -- ----            ------------    ----          -----         ------------
  1 Runspace1       localhost       Local         Opened        Busy        
  2 Runspace2       localhost       Local         Opened        Available   
  3 RemoteHost      localhost       Local         Opened        Available   
  4 e8be011f-40f8-… localhost       Local         Opened        InBreakpoint

Finally, issue the Debug-Runspace command and VS Code will automatically open your endpoint in the debugger. You'll be able to step through your code, view variables and issue commands against the runspace.

Debug-PSUDashboard

Debug-PSUDashboard can be used instead of Wait-Debugger to more easily debug aspects of your dashboard. Debug-PSUDashboard requires the PowerShell Universal VS Code extension. When placed within a dashboard, this cmdlet will trigger a modal to be show with some information about connecting to the runspace that is currently running the code you are trying to debug.

You can enter the commands listed in any PowerShell host to connect to the runspace that is currently running in the dashboard.

If you have VS Code and the PowerShell Universal extension installed, you can use the Debug with VS Code button to automatically launch VS Code and connect to the runspace. You can see how that works by watching this video.

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

• New-UAVariable

• Get-UAVariable

• Remove-UAVariable

• Set-UAVariable

Dashboards are individual websites created with Universal Dashboard. You can define settings for a dashboard and start and stop the dashboard from within the Universal administrative interface.

Adding a Dashboard

Dashboards can be added to Universal using the Add Dashboard button from the Dashboard / Dashboards page.

Name

Name is displayed throughout the UI and returned from the Universal cmdlets.

Base URL

The base URL is the URL that you will access to view this dashboard. This URL needs to be unique within this instance. You can specify the / root URL if you wish. You will have to visit /admin to login to the administrative page if you set the dashboard to the root URL.

File Name

The full file name to the dashboard file. This file needs to return a dashboard using New-UDDashboard.

Framework

The framework that the dashboard was designed for. By default, Universal Dashboard v2.9 and v3.0 are supported.

Environment

The environment to run the dashboard within.

Auth

Enables authentication for the dashboard.

Role

Defines the role that is required to access the dashboard.

AutoStart

Determines whether the dashboard should start (or restart) when the server starts or changes are made to the dashboard files.

Starting and Stopping Dashboards

Similar to jobs, dashboards run in separate PowerShell processes. You can start and stop a dashboard process by clicking the Start or Stop button from the Dashboards page.

Viewing Diagnostic Information

You can view diagnostic information for a dashboard by clicking the Info button on the Dashboards page. This will show your start information for the dashboard as well as any error that were encountered when starting the dashboard.

Viewing the Dashboard

You can view the dashboard by clicking the View button. This will take you to the Base URL for the dashboard.

Executing Commands with the Dashboard

On the dashboard information page, click on the Console tab to view the UD console. The console allows you to run scripts from within the UD runspace so you can better debug the state of your script. You can evaluate variables and run commands that are available to the dashboard. You will be running in the context of your user in regards to the runspace but the process will be running as the service account user.

Adding Custom Component Libraries

Custom component libraries provide additional components to dashboards. There are three built in component libraries that are not automatically imported into your dashboards.

• UniversalDashboard.Charts

• UniversalDashboard.Map

• UniversalDashboard.CodeEditor

To add these components to your dashboard, you can use the dashboard UI.

Click the info button on the dashboard page.

Next, click the components button in the top right of your dashboard.

Finally, check the component library you'd like added to your dashboard.

You can also add component libraries directly to your dashboards.ps1 script within the .unversal folder or when using single-file hosting and configuration.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Component @("UniversalDashboard.Charts:1.3.0")

Persistent Runspaces

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

By default, runspaces will be reset after each execution. This will cause variables, modules and functions defined during the execution of an endpoint.

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

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

You will need to ensure that the environment is used by the dashboard.

Automatically Granting App Tokens

You can automatically grant app tokens to users that visit dashboards. This is useful if you want to invoke the management API for PowerShell Universal from within a dashboard. Your dashboard will need to have authentication enabled and you will have to use the -GrantAppToken switch parameter on New-PSUDashboard.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Authenticated -GrantAppToken

From within your dashboard, you can now invoke the management API without having to worry about app token management. The API will be invoked in the context of the user that is visiting the dashboard.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDButton -Text 'Job' -OnClick {
        Invoke-UAScript -Name 'Test.ps1'
    }
}

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

• Universal Dashboard v3

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

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.

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.

The New-UDElement cmdlet allows you to create custom React elements within your dashboard. Similar to New-UDHtml, you can define HTML elements using New-UDElement. Unlike, New-UDHtml, you can update elements, set auto refresh and take advantage of the React component system.

Create an Element

You need to specify the -Tag and -Content when creating an element. The below example creates a div tag.

You can nest components within each other to create HTML structures. For example, you could create an unordered list with the following example.

Setting Attributes

You can select attributes of an element (like HTML attributes) by using the -Attributes parameter. This parameter accepts a hashtable of attribute name and values. The below example creates red text.

Auto Refreshing Elements

You can define the -AutoRefresh, -RefreshInterval and -Endpoint parameters to create an element the refreshes on a certain interval. The below example creates an element that refreshes every second and displays the current time.

Setting Element Properties Dynamically

You can use the Set-UDElement cmdlet to set element properties and content dynamically. The following example sets the content of the element to the current time.

You can also set attributes by using the -Properties parameter of Set-UDElement. The following example sets the current time and changes the color to red.

Adding Child Elements

You can add child elements using Add-UDElement. The following example adds child list items to an unordered list.

Clearing Child Elements

You can clear the child elements of an element by using Clear-UDElement. The following example clears all the list items from an unordered list.

Forcing an Element to Reload

You can force an element to reload using Sync-UDElement. The following example causes the div to reload with the current date.

Removing an Element

You can remove an element by using Remove-UDElement.

API

Get-UDElement

Get component state.

Set-UDElement

Set component state.

Remove-UDElement

Remove a component.

Add-UDElement

Add a child component.

Clear-UDElement

Clear child components out of a component.

Sync-UDElement

Reload a component

Select-UDElement

Select a component.

Universal Dashboard is extensible and you can build custom JavaScript components and frameworks. This document will cover how to build custom components that integrate with the Universal Dashboard platform.

Technology Overview

Below is a list of some of the technologies used when building Universal Dashboard components. You will not need to be an expert to produce a component but should be aware of what to search when you encounter a problem.

React

Universal Dashboard's client-side application is built using the . React makes it easy to build components that update the DOM only when necessary and has a pretty robust ecosystem of users. It's one of the most popular JavaScript frameworks at the time of this writing.

Babel

is a transcompiler for JavaScript. It works well with React and allows you to use modern constructs while compiling for backwards compatibility of browsers. Universal Dashboard uses Babel for it's core component frameworks.

Webpack

is an asset bundler. It's extremely customizable and is responsible for turning your JSX files into a bundle that can then be distributed with Universal Dashboard components.

Structure

There are some basic parts to a Universal Dashboard component. You will need to understand the structure in order to successfully build your own.

PowerShell Module

Universal Dashboard custom components are PowerShell modules. They export functions that can be used to create the component when run within a dashboard. The PowerShell module is also responsible for registering the JavaScript assets with Universal Dashboard.

JavaScript Bundle

The JavaScript bundle is produced by the Webpack bundling process. It consists of one or more JS files that you will need to register with UD.

Example Component Module Structure

The most basic structure for a UD component module will include a single JavaScript file, a PSM1 file to export a function and register the JavaScript and a PSD1 module manifest.

Step-By-Step

This following section will take you step-by-step through the different aspects of building a UD component. This assumes you are running PowerShell Universal 1.2 or later and using the PowerShell Universal Dashboard v3 framework.

1. Installing Dependencies

You will need to install the following dependencies before creating your component.

2. Initialize the JavaScript Package

After installing Node, you will have access to the npm command. You will need to initialize the node package to start. This will create a package.json file in your directory.

3. Install JavaScript Packages

You will need several JavaScript packages to build your bundle. You will first want to install the dev dependencies. These are used to build your project.

Next, you'll want to install the universal-dashboard package along with any other packages you wish to use in your component. We are using React95 in this example. We will build a control based on that library.

4. Configure Babel

You will need to create a .babelrc file to configure Babel for React.

5. Configure Webpack

Webpack is extremely customizable and sometimes very hard to get right. Below is a basic webpack.config.js file you can use to configure Webpack. You can safely change the ud95 entry key name and library value to one that matches your library.

6. Component.jsx

Now you can build your first component. You will need to export a single function component from your component.jsx file. We suggest the use of functional React components rather than class-based React components. We need to wrap the component in withComponentFeatures to ensure the component has access to the Universal Dashboard platform features.

7. Index.js

Once your component is completed, you'll need to add it to an index.js file. The entry point for your library is the first place Webpack will look. It will discover all other components from import statements in your code. The index.js file is where you should register your components. You can use the registerComponent function to do so.

8. Bundle JavaScript

To bundle the JavaScript, run the following command to start webpack. This will output a file into the dist folder.

9. PowerShell Script

Now you will need to create a PowerShell script that registers and creates your component.

First, register the JavaScript with Universal Dashboard.

Next, create a function that returns a hashtable that defines which component we are creating and which props to set.

The type property of your hashtable needs to match with the first parameter of registerComponent that you called in your JavaScript.

10. InvokeBuild (optional)

We suggest the use of InvokeBuild to create a build script to run all the steps of packaging and staging your module. The below build script deletes the dist folder, runs an NPM install to install packages, runs an NPM build to bundle the JavaScript and then copies the PS module to the dist folder.

Props

Props are values that are either passed from the PowerShell hashtable provided by the user or by the Universal Dashboard withComponentsFeature high-order function.

Standard

The properties that you set in your hashtable in PowerShell will automatically be sent in as props to React component.

For example, if you set the text property of the hashtable like this.

Then you will have access to that prop in React.

Endpoints

Endpoints are special in the way they are registered and the way that they are passed as props to your component. You will need to call Register on the endpoint in PowerShell and pass in the Id and PSCmdlet variables.

Endpoints are created from ScriptBlocks and are executed when that event happens.

Universal Dashboard will automatically wire up the endpoint to a function within JavaScript. This means that you can use the props to call that endpoint.

Notice the props.onClick function call. This will automatically call the PowerShell script block on the server.

setState

The setState prop is used to set the state of the component. This ensures that the state is tracked and your component will work with Get-UDElement.

For example, with a text field, you'll want to call props.setState and pass in the new text value for the state.

children

The children prop is a standard React prop. If your component supports child items, such as a list or select box, you should use the standard props.children prop to ensure that the cmdlets Add-UDElement , Remove-UDElement and Clear-UDElement function correctly.

Publishing to the Marketplace

To publish to the Marketplace, you simply need to publish to the PowerShell Gallery but include the ud-component tag in your module manifest. The marketplace syncs with the Gallery every hour and your component will be enabled for anyone to find after that.

A dashboard can consist of one or more pages. A page can have a particular name and URL. You can define a URL that accepts one or more variables in the URL to define a dynamic page.

Basic Page

A basic page can be defined using the New-UDPage cmdlet. You could navigate to this page by visiting the /dashboard URL of your dashboard.

Dashboard with Multiple Pages

Dashboards can have multiple pages and those pages can be defined by passing an array of UDPages to New-UDDashboard

You may want to organize your dashboard into multiple PS1 files. You can do this using pages.

Page with a Custom URL

A page can have a custom URL by using the -Url parameter. You could navigate to this page by visiting the /db URL of your dashboard.

Page with Variables in URL

You can define a page with variables in the URL to create pages that adapt based on that URL.

Query string parameters

Query string parameters are passed to pages and other endpoints as variables.

For example, if you visited a page with the following query string parameter: http://localhost:5000/dashboard/Page1?test=123

You would then have access to a $Test variable that contained the value 123.

Role-Based Access

Navigation

Custom Navigation

Custom navigation can be defined with a list. List items can include children to create drop down sections in the navigation.

Dynamic Navigation

Dynamic navigation can be used to execute scripts during page load to determine which navigation components to show based on variables like the user, IP address or roles.

You can generate dynamic navigation by using the -LoadNavigation parameter. The value of the parameter should be a script block to execute when loading the navigation.

Layouts

The permanent layout creates a static navigation drawer on the left hand side of the page. It cannot be hidden by the user.

The temporary layout creates a navigation drawer that can be opened using a hamburger menu found in the top left corner. This is the default setting.

Logo

You can display a logo in the navigation bar by using the -Logo parameter.

Now, when creating your page, you can specify the path to the logo.

The logo will display in the top left corner.

API

New-UDPage

Creates a new page. Pass the results to New-UDDashboard -Pages

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.

API

New-UDHtml

Write raw HTML to your dashboard.