Downloads

Download the latest version of PowerShell Universal.

Scripts

Examples and full solutions for PowerShell Universal.

Blog

The Ironman Software blog has articles about PowerShell Universal.

Forums

Connect with the PowerShell Universal community.

Pricing

Purchase a license for the features of PowerShell Universal.

Issue Tracker

File a bug report or feature request for PowerShell Universal.

Install PowerShell Universal

You'll need to install the PowerShell Universal server. There are a lot of ways to do so, but you can use the command line below to get started quickly:

Install-Module Universal
Install-PSUServer

Install-Module Universal
Install-PSUServer

Install-Module Universal
Install-PSUServer -AddToPath
Start-PSUServer -Port 5000

wget https://imsreleases.blob.core.windows.net/universal/production/2.4.0/Universal.linux-arm.2.4.0.zip
unzip Universal.linux-arm.2.3.2.zip -d ./PSU
chmod +x ./PSU/Universal.Server
./PSU/Universal.Server

Open PowerShell Universal

By default, PowerShell Universal runs on port 5000 of localhost.

First Run Wizard

The first run wizard will step you through the basic settings of PowerShell Universal. This includes the default admin username and password, security settings, telemetry settings and license.

Admin Account

The admin account is used to login to PowerShell Universal. It will display a warning if the password does not match the complexity requirements. You can always change it later.

Security Settings

Select from the drop down of security settings. They tweak certain features of PowerShell Universal in different levels of security. If you plan on cloning from a git repository, skip this step or set it to default.

Telemetry

PowerShell Universal can send anonymous telemetry data if you opt-in to do so. If you plan to clone from a git repository, skip this setting.

License

Add your license file. This is optional and needs to be an account-based license key.

Create an API

APIs allow you to call PowerShell scripts over HTTP. To create an API, click API \ Endpoints and click Create New Endpoint. Specify a URL.

Next, click details on your new API and enter the following command into the editor:

Get-ComputerInfo

Save the script and then click the Execute button to test it out.

You can also execute the API via Invoke-RestMethod.

PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/hello-world

WindowsBuildLabEx                                       : 22000.1.amd64fre.co_release.210604-1628
WindowsCurrentVersion                                   : 6.3
WindowsEditionId                                        : Professional
WindowsInstallationType                                 : Client
WindowsInstallDateFromRegistry                          : 8/6/2021 4:05:12 PM
WindowsProductId                                        : 00330-52452-93139-AAOEM
WindowsProductName                                      : Windows 10 Pro
WindowsRegisteredOrganization                           :

Create a Script

To create a script, click Automation \ Scripts and then click Create New Script.

Enter the following script into the editor and save:

Read-Host "What should I say?"

1..100 | ForEach-Object {
    Write-Progress -PercentComplete $_ -Activity "Processing..."
}

Get-Service

Once the script is saved, click Run.

Create an App

To create a new PowerShell-based user interface (app), you can click User Interfaces \ Apps and then Create New App.

After clicking Ok, click the Details button to edit the PowerShell script. Add the following script to the editor:

New-UDApp -Title "Hello, World!" -Content {
    New-UDButton -Text "Click Me" -OnClick {
        Show-UDToast -Message 'Success!!'
    }
}

Save the app, click the Restart button and then click the View button. Click the Click Me button.

Learn more about the various features of PowerShell Universal:

• APIs

• Automation

• Apps

Docker

Confirming Docker is installed correctly

NOTE: Apple M1 devices: At the time of writing there are some issues on Apple M1 devices and, some ARM64/ARMv8 devices. Please review this forum thread before proceeding.

Docker

Run the following command to confirm Docker is installed:

docker version

Example Output:

Client: Docker Engine - Community
 Version:           23.0.1
 API version:       1.42
 Go version:        go1.19.5
 Git commit:        a5ee5b1
 Built:             Thu Feb  9 19:47:01 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          23.0.1
  API version:      1.42 (minimum version 1.12)
  Go version:       go1.19.5
  Git commit:       bc3805a
  Built:            Thu Feb  9 19:47:01 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.18
  GitCommit:        2456e983eb9e37e47538f59ea18f2043c9a73640
 runc:
  Version:          1.1.4
  GitCommit:        v1.1.4-0-g5fd4c4d
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Docker Compose

Docker Compose v1 uses the command docker-compose. As of June 2023, support ends for Docker Compose v1.

Docker Compose v2 uses the command docker compose.

If you are using Docker Compose v1 please adjust the commands accordingly. More information on Docker Compose can be found here.

Run one of the following commands to confirm that Docker Compose is installed:

Docker Compose v1:

docker-compose version

Docker Compose v2:

docker compose version

Example Output:

Docker Compose version v2.16.0

A Docker Hello-World

To ensure that Docker has the ability to pull and run container images run the following command:

docker run hello-world

Example Output:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
2db29710123e: Pull complete 
Digest: sha256:ffb13da98453e0f04d33a6eee5bb8e46ee50d08ebe17735fc0779d0349e889e9
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Installation

Using the pre-built Container

In order to run PowerShell Universal, use the provided container image. The docker image is available on Docker Hub.

The prebuilt version supports both free & paid features of PowerShell Universal.

Start the container by pulling the image and then running a container with the default port bound.

Running a basic image

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 5000:5000 ironmansoftware/universal

Present an image to a different port

If port 5000 is unavailable on your host, switch to another port.

e.g. Present on port 80

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 80:5000 ironmansoftware/universal

Mount a volume

The docker run command allows you to mount a volume for persistent storage. Mount the volume to the /root folder.

Mount a volume on container in Windows

The following command mounts the folder C:\docker\volumes\PSU to /root on your container:

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 5000:5000 -v C:\docker\volumes\PSU:/root ironmansoftware/universal 

Mount a volume on Container on Mac and Linux

The following command mounts the folder /docker/volumes/PSU to /root on your container:

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 5000:5000 -v /docker/volumes/PSU:/root ironmansoftware/universal 

Stopping a Container

The following command removes a stopped container named PSU:

docker stop PSU

Removing a Container

The following command stops a container named PSU:

docker rm PSU

The --force flag can remove a running container:

docker rm --force PSU

Docker Compose

Docker Compose allows you to use a yaml text file to standardize your build and script the deployment (or build) or multiple containers.

The default name for any compose file is docker-compose.yml. It is recommended you use this as your compose filename.

Creating a Compose Script for Windows

The following compose file runs a Powershell Universal container in Windows:

version: "5.2.1"
services:
  PSU:
    container_name: PSU
    image: ironmansoftware/universal:latest
    ports:
      - 5000:5000
    restart: unless-stopped
    environment:
      - TZ=Europe/London
    volumes:
      - C:\docker\volumes\PSU:/root

Creating a Compose Script for Mac / Linux

The following compose file runs a Powershell Universal container on Mac and Linux:

version: "5.2.1"
services:
  PSU:
    container_name: PSU
    image: ironmansoftware/universal:latest
    ports:
      - 5000:5000
    restart: unless-stopped
    environment:
      - TZ=Europe/London
    volumes:
      - /docker/volumes/PSU:/root

Starting Containers using Compose Scripts

Using a Terminal shell or PowerShell for Windows. Use the cd command to change the working directory with your docker-compose.yml script.

Run the following command:

docker compose up -d

Example Output:

Creating network "PSU_default" with the default driver
Pulling PSU (ironmansoftware/universal:latest)...
latest: Pulling from ironmansoftware/universal
7608715873ec: Pull complete
4e66273c6cfb: Pull complete
2649c52300c2: Pull complete
a20175666bc7: Pull complete
65ce93bc0653: Pull complete
Digest: sha256:d7ff98e6197d21070aac325c2efbefa393a4952d2e8ba6b1327dc97824ec4d55
Status: Downloaded newer image for ironmansoftware/universal:latest
Creating PSU ... done

Stopping Containers using Compose Scripts

Using a Terminal shell, or PowerShell for Windows. cd to the directory with your docker-compose.yml script.

Run the following command

docker compose down

Example Output:

[+] Running 2/2
 ⠿ Container PSU         Removed                                           0.5s
 ⠿ Network PSU_default   Removed                                           0.4s

Using Environment Variables and SQL Persistence

You can add Environment variables into your Compose Scripts. Below is an example of:

• Setting a node name

• Adding SQL persistence

• Adding a SQL Connection String

version: "5.2.1"
services:
  PSU:
    container_name: PSU
    image: ironmansoftware/universal:latest
    ports:
      - 5000:5000
    restart: unless-stopped
    environment:
      - TZ=Europe/London
      - Plugins__0=SQL
      - Data__ConnectionString=Data Source=sql1.domain.com;Initial Catalog=PSUTicketBridge;User Id=psu_ticketbridge_dbo;Password=Password123;TrustServerCertificate=True;Trusted_Connection=True;integrated security=false;
      - NodeName=mynodename
    volumes:
      - /docker/volumes/PSU:/root

Using Environment Variables and PostgreSQL Persistence

You can add Environment variables into your Compose Scripts. Below is an example of:

• Setting a node name

• Adding PostgreSQL persistence

• Adding a PostgreSQL Connection String

version: "5.2.1"
services:
  PSU:
    container_name: PSU
    image: ironmansoftware/universal:latest
    ports:
      - 5000:5000
    restart: unless-stopped
    environment:
      - TZ=Europe/London
      - Plugins__0=PostgreSQL
      - Data__ConnectionString=Host=PGhostname; Database=PGdatabase; User Id=PGusername; Password=PGpassword!;Port=5432
      - NodeName=mynodename
    volumes:
      - /docker/volumes/PSU:/root

Building a Custom Container

If you wish to build more features, modify, or hardcode Environment Variables into your container, then create a Dockerfile

NOTE: Dockerfiles' are case-sensitive and must start with a capital 'D'.

To create a Docker image that can persist the Universal data, 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.

Writing a Dockerfile script for Linux

FROM ironmansoftware/universal:latest
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["/home/data"]
ENV Data__RepositoryPath /home/data/Repository
ENV Data__ConnectionString Data Source=/home/data/database.db
ENV UniversalDashboard__AssetsFolder /home/data/UniversalDashboard 
ENV Logging__Path /home/data/logs/log.txt
ENTRYPOINT ["./Universal/Universal.Server"]

Building a container

From the path that hosts your Dockerfile, run the following command:

docker build . --tag=universal-persistent

Windows

FROM ironmansoftware/universal:5.0.0-windowsservercore-1809
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["C:/data"]
ENV Data__RepositoryPath C:/data/Repository
ENV Data__ConnectionString Data Source=C:/data/database.db
ENV UniversalDashboard__AssetsFolder C:/data/UniversalDashboard 
ENV Logging__Path C:/data/logs/log.txt
ENTRYPOINT ["C:/ProgramData/Universal/Universal.Server.exe"]

Run a build with the build command:

docker build . --tag=universal-persistent

Start the docker container with the run command and make sure to specify the volume to mount:

docker run -it --name powershelluniversal --mount source=psudata,target=/home/data --rm -d  -p 5000:5000/tcp universal-persistent:latest

SQL

To use SQL persistence, define the plugin and connection string as follows:

ENV Data__ConnectionString=Data Source=ServerName; Initial Catalog=DatabaseName; Integrated Security=SSPI;
ENV Plugins:0=SQL

PostgreSQL

To use PostgreSQL persistence, define the plugin and connection string as follows:

ENV Data__ConnectionString=Host=PGhostname; Database=PGdatabase; User Id=PGusername; Password=PGpassword!;Port=5432
ENV Plugins:0=PostgreSQL

Time Zones

To properly support time zones on Linux when scheduling jobs, include the tzdata package in your dockerfile along with an environment variable that specifies the server time zone.

ENV TZ Europe/Amsterdam
RUN apt-get install -y tzdata

Tags

We publish the following tags to Docker Hub:

• latest - Current version using Ubuntu LTS

• 5.x-preview-modules - Nightly build of version 5 using Ubuntu LTS and select AZ modules

• 5.x-preview-<OS>-<PS> - Nightly build of version 5 with the specified OS and PS version

• 4.x-preview-<OS>-<PS> - Nightly build of version 4 with the specified OS and PS version

• 5.x-<OS>-<PS> - Production version 5 with the specified OS and PS version

• 5.x-modules - Current production version on Ubuntu LTS with select AZ modules installed

• 4.x-<OS>-<PS> - Current production version 4 with the specified OS and PS versions

Included Modules

The module container images include the following modules:

• Az.Accounts

• Az.Compute

• Az.KeyVault

• Az.Resources

• Invoke-SqlCmd2

Summary

This basic "How to Get Started" enables you to start running or building PSU Containers. This references section links all sources for commands:

References

Running Containers

https://docs.docker.com/engine/reference/commandline/run/

https://docs.docker.com/engine/reference/commandline/stop/

https://docs.docker.com/engine/reference/commandline/rm/

https://docs.docker.com/compose/

Building Containers

https://docs.docker.com/engine/reference/commandline/build/

New Admin Console

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

Portal

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

Pages and Widgets

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

PowerShell Universal Gallery

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

You can view the Gallery repository here.

Granular Permissions

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

PostgreSQL Support

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

Updated Runtimes

PowerShell Universal v5 is built on .NET 8 and PowerShell 7.4.

gRPC Cmdlets

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

Windows PowerShell 5.1 and PowerShell 7 Environments

The Agent environment has been replaced with Windows PowerShell 5.1 and PowerShell 7 environments. These environments host the PowerShell engine, but they allow for better control of assembly loading to ensure more modules are compatible with PowerShell Universal. While pwsh.exe is still supported, we suggest using PowerShell 7 when possible. The Windows PowerShell 5.1 environment is now a requirement for running this version of PowerShell, and powershell.exe is no longer supported.

Application Files

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

ZIP Installation

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

MSI Installation

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

Module Installation

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

Windows

• %ProgramData%\PowerShellUniversal

Linux and Mac OS

• %HOME%/.PowerShellUniversal

Configuration Files

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

Windows

• %ProgramData%\PowerShellUniversal

• %ProgramData%\UniversalAutomation

Linux

• %HOME%/.PowerShellUniversal/

Mac OS

• %HOME%/.PowerShellUniversal/

Desktop

• %AppData%\PowerShellUniversal

Database

Removing the database depends on the database type used.

SQLite

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

Windows

• %ProgramData%\PowerShellUniversal\database.db

Linux and Mac OS

• %HOME%/.PowerShellUniversal/database.db

PostgreSQL and SQL

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

IIS

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

It is often desirable to migrate a PowerShell Universal server configuration from one machine to another. This can be due to change of infrastructure or restoring from backup. This can be for operating system upgrades or general data center maintenance.

This document explains the steps necessary to migrate PowerShell Universal configuration to another machine.

We recommend stopping the PowerShell Universal service before performing the migration or restore.

Depending on the type of migration or restoration, you may not need to perform all of these actions.

Configuration Data

The configuration data files are stored in %ProgramData%\UniversalAutomation\Repository by default. These will consist of features such as APIs, Scripts and Apps. The entire directory is necessary for the configuration of the target system to function.

You can either copy the folder manually or via PowerShell. Ensure that you include all subdirectories.

Database

The database migration will depend on the type of database used.

SQLite

You will need to copy the SQLite database file to the configured, or default, database location. On a default installation, this will be %ProgramData%\UniversalAutomation\database.db. The target machine account or service account will need read and write access to this database file.

SQL and PostgreSQL

Because these databases are stored outside of the PowerShell Universal server, you do not need to perform a migration of the database itself. You will need to ensure that the target server has network access to the SQL host.

Application Settings

The PowerShell Universal appsettings.json file is necessary for providing the appropriate server settings to the platform. By default, this is stored in %ProgramData%\PowerShellUniversal\appsettings.json. You will need to copy this to the new server in the same location.

This file contains configuration settings such as HTTP certificate, authentication, git sync settings, API configuration options and more.

appsettings.json files do not change between upgrades and you likely not need to perform this action during a restore.

Secret Vaults

PowerShell Universal includes 3 built-in secret vaults that may need to be migrated. The database vault is included with the database migration and does not require extra steps. If you are performing a restore, it's unlikely you will need to perform these restore operations unless the secret vaults have become corrupted.

PSUSecretStore

The SecretStore module uses a user-specific storage location to ensure that ACLs are enforced on the files themselves. You will need to ensure that you copy the vault's contents to the account of the user that will be running PowerShell Universal on the new system.

BuiltInLocalVault

The BuiltInLocalVault is only available on Windows and uses Credential Manager to store secrets. You will need to recreate these secrets in the Credential Manager store on the new system.

Within Credential Manager, you will find PowerShell secrets stored with a ps: prefix.

While it's not possible to extract credentials directly from the Credential Manager UI, you can use the Secret Management modules directly. To retrieve secrets, you can do the following.

On the new server, you can do the reverse and call Set-Secret. Note that these commands need to run as the service account running PowerShell Universal in order to store them properly in the Credential Manager account for the user.

Authentication

Certain authentication types will require configuration outside of PowerShell Universal. Unless you are moving the machine running PowerShell Universal or changing the accessible URLs, you will not need to perform these actions.

OpenID Connect

Ensure that the proper sign-on URLs are configured in your Identity provider (e.g. Azure AD or Okta) if the host name of the server is changing. Without properly configured sign-on URLs, users will not be able to sign on the new system.

Windows

Other Resources and Considerations

There may be other resources that PowerShell Universal uses on the system that should be taken into account when migrating or restoring servers. Typically, you will not need to worry about these resources during a restore as they should remain the same if the machine has not changed.

• PowerShell Modules

• Environment Variables

• Local Account Privileges

• File System Permissions

• Proxy Configuration

• Certificates

• Git SSH keys or credentials

• DNS Settings

Application Files

MSI \ Kestrel

During the MSI install, leave all settings as default. We recommend leaving the service account blank and unchecking the box that states to start the PowerShell Universal service after the installation is complete.

After the installation completes, the service will be created but not running. Open Service Control Manager (services.msc) and set the service account for the PowerShell Universal service. Start the service.

Debugging Issues

When migrating a PowerShell Universal service, you may run into issues the arise from configuration differences between the two systems. The following are places to look for more information.

Event Viewer

if the service starts and stops, there may be an issue with the database access. We recommend looking in the Application log within Event Viewer. PowerShell Universal will report two application Errors that will include .NET in the name. The second of the two errors will provide a human readable exception with more details.

System Logs

PowerShell Universal will write system logs to the %ProgramData%\PowerShellUniversal directory. Search for strings starting with [ERR] to gather more information about issues with the installation.

Notifications

After migrating the service, check for any error notifications that may indicate misconfiguration of the system.

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

APIs

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

Automation

Streamline your automation with an intuitive web interface for executing, scheduling, securing, and auditing PowerShell scripts. Effortlessly manage tasks and access in-browser terminals to maximize efficiency and control in your automation workflows.

Apps

Create fully customizable, interactive web apps tailored for your internal users using PowerShell. With over 70 versatile controls and seamless integration to other PowerShell modules and scripts, you can build powerful interfaces to enhance productivity and collaboration.

Hosting

PowerShell Universal is cross-platform and can be hosted on-premises, in the cloud or even on a Raspberry Pi.

Security

PowerShell Universal is a versatile, cross-platform solution that adapts to your hosting needs. Deploy seamlessly on AWS, Azure, IIS, or your on-premises infrastructure—even on compact devices like a Raspberry Pi. Flexibility meets power for automation anywhere.

Development

PowerShell Universal delivers a seamless development experience with built-in tools like IntelliSense, syntax highlighting, error checking, formatting, and debugging—all accessible directly from your browser. Enhance productivity further with a dedicated VS Code extension and integrated Git support for streamlined version control.

Platform

With support for PowerShell 7 and Windows PowerShell, seamless integration with PowerShell modules, and powerful tools for variable and secret management, it adapts to your needs. Enjoy multilingual support, compatibility with multiple database types (SQLite, SQL Server, PostgreSQL), and built-in high availability and load balancing for enterprise-grade scalability.

Community

Join the thriving PowerShell Universal community and connect with like-minded professionals. Participate in our active forum for support and collaboration, explore our open-source gallery of pre-made solutions, and stay informed with our transparent roadmap and bug tracker.

Licensing

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

What's a server?

A server is a single running instance of PowerShell Universal.

What if I have multiple containers?

The license applies to each container instance and not the container host. For example, if you have 10 container instances running, you will need 10 licenses.

What if I have multiple sites on a single IIS server?

Each website running PowerShell Universal will need a license and not a single license for the entire IIS server.

Install a License

To install a license, click Settings \ License. Click the Add License button to upload your license file. You can also install licenses using the Set-PSULicense cmdlet. Offline licenses do not require an internet connection but will need to be reinstalled when the subscription expires, in you wish to update the version of PowerShell Universal. Online licenses require an internet connection and access to https://ironmansoftware.com in order to verify subscription status.

You can use the PSULICENSE environment variable to set a license. The value of this environment variable needs to be the contents of the license file.

Proxy configuration can be done by clicking Settings \ General and configuring the proxy URI and, optionally, credentials. You can also configure proxy settings with the Set-PSUSetting cmdlet.

Account-Based Licensing

When using account-based licensing, you will enter your account's license key. Whenever you activate a PowerShell Universal server, it will assign a license to computer. This license key does not change so there is no need to install a new license when renewing. You can view the assigned computers in your Ironman Software account.

The PowerShell Universal server needs to have access to ironmansoftware.com.

Offline Licenses

Offline license files are required for environments that do not have internet access. You will need to install a new license file when you plan to upgrade to a version past the expiration date of the license.

Online Licenses

Online licenses work the same as offline but check the subscription status on ironmansoftware.com. The license is tied to a specific subscription and may require a change after renewal. We recommend account-based licensing over online licenses.

Developer Licenses

When a server license is purchased, you will be able to generate developer licenses for users building solutions for your team. Their intent is to be used by individual developers in their local environments. Do not use developer licenses when hosting a server for remote access for testing or production. Instances of PowerShell Universal running with a Developer License will display a water mark in the admin console and any apps stating they are intended only for development purposes.

You can generate a developer license on the Settings \ License page by clicking the Generate Developer License button.

Licensed Features

The following features of PowerShell Universal require a license.

• Debugging Tools

• Enterprise Authentication

  • OpenID Connect

  • SAML2

  • WS-Federation

  • Windows Authentication

  • Custom Authentication Scripts

  • Client Certificate

  • App Tokens

• Enterprise Authorization

  • Permissions

  • Custom Authorization Scripts

• Platform

  • Git Support

  • Module Management

  • Non-Database Credential Vaults

  • SQL Support

  • PostgreSQL Support

  • Published Folders

  • Cache Management

  • Computer Groups

  • Translations

• Settings

  • Branding

  • Tags

• APIs

  • Event Hubs

  • OpenAPI Documentation

• Automation

  • Triggers

  • Terminals

  • Tests

• Apps

  • App Page Editor

  • App Function Editor

Configuration Files

Major versions may include breaking changes. Minor versions may have additional cmdlets or parameters but will not have any breaking changes.

It is much easier to restore from a backup of the configuration files before the upgrade rather than manually updating files.

Database

Below is an example of downgrading the schema of a SQLite database to version 5.3.0. You will need to stop the PowerShell Universal services before doing so.

You can downgrade a nightly build version of the database to a stable version of the database to allow for an upgrade to the stable build of the target version. You will lose any data found in new columns or tables.

Application Files

Downgrading the application files is typically a simple process and depends on how you installed the product. You will need to perform the configuration file and database downgrades before performing the application downgrade.

MSI

To downgrade an MSI installation, you will need to first uninstall the current version. PowerShell Universal will not allow you to run a downgrade. After the uninstall is complete, perform an installation of the target version.

ZIP

To downgrade a ZIP installation, simply delete the PowerShell Universal application files. Once the directory is clear unzip the target version's ZIP into the installation directory. Ensure that you run Get-ChildItem -Recurse | Unblock-File after doing so.

IIS

Similar to the ZIP installation, remove the old version's files and unzip and unblock the target version's files. Ensure that the web site and App Pool are stopped before attempting so.

Windows

• Optional*: Windows PowerShell v5.1 or later

• Optional*: PowerShell v7.2 or later

• .NET Framework v4.8.0 or later (only for Windows PowerShell)

Linux

• Optional*: PowerShell v7.2 or later

• Validated Distributions: Ubuntu 18.04 and 20.04

Mac OS

• Optional*: PowerShell v7.2 or later

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

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

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

• WebSocket

• CSS Flexbox

• Fetch

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

Execution Environment

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

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

Set-PSUSetting -ApiEnvironment '7.1'

Per Endpoint Environment

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

New-PSUEndpoint -Url /environment -Environment Integrated -Endpoint {
    $PSUEnvironment
}

Performance

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

See https://blog.ironmansoftware.com/webapp-benchmark-siege/ for detailed information about benchmark tests on Universal APIs.

Variables

Variables are listed on the variables page.

API

• New-PSUEndpoint

• Get-PSUEndpoint

• Remove-PSUEndpoint

• Set-UASetting

About

Management API Documentation

You can view the Managment API documentation by visiting the built in Swagger dashboard.

Create an OpenAPI Document

To create an OpenAPI definition, click APIs \ Documentation and then Create new Endpoint Documentation. You can set the name, URL, description and authentication details for the documentation.

Once created, you can assign endpoints to the documentation by editing the endpoint.

The documentation for your endpoint will appear within the Swagger dashboard. Select the definition with the Select a definition dropdown.

All your custom endpoints will be listed.

Help Text

You can specify help text for your APIs using comment-based help. Including a synopsis, description and parameter descriptions will result in each of those pieces being documented in the OpenAPI documentation and Swagger age.

For example, with a simple /get/:id endpoint, we could have comment-based help such as this.

The resulting Swagger page will show each of these descriptions.

Input and Output Types

Types can be defined within an endpoint documentation ScriptBlock. Click the Edit Details button on the API documentation record.

APIs can also be documented using input and output types by creating a PowerShell class and referencing it within your comment-based help. PowerShell Universal takes advantage of the .INPUTS and .OUTPUTS sections to specify accepted formats and define status code return values.

Within the .INPUTS and .OUTPUTS , you will define a YAML block to provide this information. To create types, use the Endpoint Documentation editor. This file is loaded when reading OpenAPI documents. This information is stored in endpointsDocumentation.ps1.

Inputs

Input types are defined in the .INPUTS section. This section is a YAML block that defines if the input is required, provides a description and specifies the content type. This is a content type followed by the PowerShell class you defined in the endpoint documentation.

Outputs

Output types are similar to input but are specified on return codes as well as their content type and PowerShell class. The below example returns an ADAccountType class when a HTTP OK (200) is returned from the API. A 400 (Bad Request) does not return data but does provide a description that will be displayed in the API documentation.

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

Creating an Event Hub

To create an event hub, click APIs \ Event Hub and click Create New Event Hub. Event Hubs are named and can choose to enforce authentication and authorization.

Agent

Send Events

From within the PowerShell Universal server, you can send events from a hub to connected clients using the Send-PSUEvent cmdlet.

The -Data parameter accepts an object and will be serialized using CLIXML and send to the client. The data will be deserialized before passing to the script block.

You can also run commands. This does not require defining a script on the event hub client. You can also use the Invoke-PSUCommand alias to mimic native PowerShell behavior.

Receive Data from Clients

This feature is only available when sending data to an individual client, rather than all clients connected to a hub.

Example: Running Scripts on Remote Machines

This example allows for sending scripts to remote machines and executing them with a generic event hub script.

First, create an event hub in PowerShell Universal. This example does not use authentication.

Next, install the Event Hub Client on the remote machine. Create a configuration file in %ProgramData%\PowerShellUniversal\eventHubClient.json.

Next, create a helper script.ps1 to receive the event hub data and process requests from PSU to invoke scripts. It creates a new temporary PS1 file and uses the $EventData passed down from the event hub message with the contents and parameters for the script.

In PowerShell Universal, add a script that you want to run on the remote machine. In this example, it simply starts a process.

Finally, add another script that sends the event down to the client. This could be from an API or an App as well. It uses Get-PSUEventHubConnection to get the target computer’s connection ID and then sends an event with the contents of a script and any parameters for that script. Because the script on event hub side is generic, it will just run whatever is passed to it.

From here you could event use the script to schedule jobs to run on the remote machines using the event hub client.

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 will endpoint authentication and authorization under the Security tab of an endpoint's properties.

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

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

Hover over your user name in the top right of the admin console, click Tokens and click Create Application Token.

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.

API

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.

API

Run Scripts

Schedule Jobs

Ad-Hoc Commands

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

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

Configuring Rate Limiting

To configure rate limiting, 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 * , this rule affects all HTTP methods. 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 defining the relative path: /api/user.

Limit

This is the number of requests in the time frame before rate limiting kicks in.

Period

This is 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, add them to the rate limiting allow lists. Find these by clicking the settings button.

API

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

Viewing Jobs

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

View Job Output

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

View Job Pipeline Output

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

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

Viewing Errors

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

Status

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

• ErrorActionPreference

• WarningActionPreference

The following table describes how PowerShell Universal treats statuses.

Feedback

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

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

Invoking Jobs from PowerShell

Call Scripts from Scripts

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

Waiting for a Script to Finished

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

Return Pipeline Data

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

Returning the last job's output

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

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.

If you are using PowerShell Universal 2.4 or later, you can use the -Wait parameter of Invoke-PSUScript to achieve this.

Integrated Mode

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

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

The following cmdlets support integrated mode.

• Get-PSUScript

• Invoke-PSUScript

• Get-PSUJob

• Get-PSUJobOutput

• Get-PSUJobPipelineOutput

• Get-PSUJobFeedback

• Set-PSUJobFeedback

• Wait-PSUJob

Invoking Jobs with REST

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

Call Scripts with REST

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

Providing Parameters

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

Setting the Environment

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

Setting the Run As account

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

Variables Defined in Jobs

Job Run ID

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

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

You will need to enable this feature to use it.

API

MSI Install (Windows)

The MSI install creates a PowerShell Universal service. By default, PowerShell Universal listens on port 5000. You can navigate to http://localhost:5000

System installs run as a Windows service. User installs run when the user logs in to the machine. The user install runs in the user's context.

MSI Parameters

The following table contains the parameters you can specify if running msiexec against our MSI install for automation purposes:

Example

The example below shows how to run msiexec.exe to install PowerShell Universal and provide parameters to the installer:

ZIP Install

Windows

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

Linux

You can use the following command line on Linux to install and start PowerShell Universal:

Linux Service

You can use systemd to start PowerShell Universal as a service. The below script is an example of downloading a version of PowerShell Universal and installing it as a service:

PowerShell Module

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

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

Running this command on Windows creates and starts a Windows service on your machine. Running this command on Linux creates and starts a systemd service on your machine. Running this command on Mac OS downloads and extracts the PowerShell Universal server.

Chocolatey Package (Windows)

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

Docker

IIS Install

Antivirus Configuration

PowerShell Universal takes full advantage of PowerShell and the PowerShell SDK. It includes PowerShell scripts directly in the product. Consider configuring antivirus to allow execution of PowerShell scripts in PowerShell Universal.

Directories

The following directories contain examples from a standard Windows system of scripts and executable files that you may need to exclude from antivirus checks. Changing paths within appsettings.json or within the installer requires changing which directories are excluded.

Executables

It may be necessary to exclude certain executables that run PowerShell scripts. The below is a list of executables that run PowerShell from PowerShell Universal.

Default Admin Name and Password

You can use the $ENV:PSUDefaultAdminName and $ENV:PSUDefaultAdminPassword environment variables to change this behavior. These values are only used if no administrator account already exists. This is useful for cloud-based installations.

Agent

The PowerShell Universal Agent executes Event Hub actions. Install it depending on your environment:

Windows (MSI)

ZIP

ZIP files for each platform we support are on our downloads page. Each ZIP contains a PowerShellUniversal.Agent.exe or PowerShellUniversal.Agent file that can start an agent. Run the process as a service for it to start whenever the machine reboots.

Next Steps

At this point, Universal is up and running. Visit http://localhost:5000 or your default port to navigate to the admin console. Log in with the default admin name and password or create a default admin account.

You can work with tests by visiting Automation \ Tests.

Test Discovery

Tests files are located based on file name. Any files found in the respository that end in .Tests.ps1 will be listed in the Test Files tab. You can create new test files on the Automation \ Scripts page.

Test Execution

Tests can be run by clicking the Run Test or Run All Tests buttons. Run Test will run the individual Test Files and Run All Tests will run all the Test Files.

You will have the option to select the environment, credential and computer to run the tests.

Test Results

Test Results are produced after the test run finishes. You will be able to see the overal status of the test run and the result of individual test suites and cases.

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

• User Login

• Use of a Revoked App Token

• API Authentication Failed

• API Error

• New User Login

• Git Sync

• License Expired

• License Expiring

New User Login

The user login event takes place when a user accesses PowerShell Universal. The script will receive a $Userparameter with user information.

@{
    Name = "username"
    Roles = @()
}

User Login

The user login event takes place when a user accesses PowerShell Universal. The script will receive a $data parameter with user information. The data structure is shown below.

@{
    UserName = 'username'
    RemoteIpAddress = ''
    LocalPort = ''
    RemotePort = ''
}

Use of a Revoked App Token

The app token event takes place when a revoked app token is used. The script will receive a $data parameter that contains the contents of the app token as a string.

Git Sync

This trigger occurs when a git sync is run. This trigger will fire for both successful and unsuccessful git syncs.

You will receive the following object in the $data parameter.

public class GitStatus 
{
    public long Id { get; set; }
    public string CommitId { get; set; }
    public DateTime Timestamp { get; set; }
    public TimeSpan SyncTime { get; set; }
    public int Changes { get; set; }
    public string Location { get; set; }
    public string Remote { get; set; }
    public GitStatusResult Result { get; set; }
    public string ResultMessage { get; set; }
    public string ComputerName { get; set; }
}

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.

Conditions

Using the -Condition parameter of New-PSUTrigger, you can determine whether or not a trigger should be run based on local conditions on the server. Return $true or $false from the condition.

For example, you can disable a trigger if the Environment environment variable is not set to production.

New-PSUTrigger -Condition {
   $Env:Environment -eq 'production'
}

API

• New-PSUTrigger

• Remove-PSUTrigger

• Set-PSUTrigger

• Get-PSUTrigger

Overview

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

1. Data Backup

2. Upgrade Process

3. Upgrade Validation

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

Recommendations

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

1. Data Backup

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

Database

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

SQLite

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

SQL

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

Configuration Scripts

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

2. Upgrade Progress

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

MSI

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

appsettings.json

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

Service Account

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

Upgrade Process

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

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

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

IIS

Below you will find information about upgrading an IIS install.

web.config

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

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

Upgrade Process

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

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

Universal Module

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

Follow the backup procedures above and then perform the upgrade.

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

Update-Module Universal
Import-Module Universal -PassThru

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

Update-PSUServer

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

ZIP

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

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

Get-ChildItem -Recurse | Unblock-File

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

3. Upgrade Validation

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

Notifications

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

Modules

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

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

Apps

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

Nightly Builds

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

.\psu.exe db schema --schema-version 5.4.0

Common Upgrade Issues

IIS App Pool Does Not Start After Upgrade

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

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

Command Not Found Errors

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

Table\Column Not Found Error when using SQL Persistence

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

Breaking App Component Change

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

License Issues after Upgrade

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

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

5.0 Breaking Changes

Removal of Pages

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

Removal of App Pages Designer

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

Removal of Access Controls

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

Cmdlet Communication Channel and Authorization Changes

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

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

Please review the Module documentation for more information.

Common cmdlet errors you may encounter during upgrade

HTTP Status Code 403

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

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

URI Not Defined

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

{
   "API" : {
      "URL": "http://localhost:5000"
   }
}

SSL Certificate Error

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

PowerShell.exe is no longer used

The Windows PowerShell 5.1 environment no longer uses PowerShell.exe directly. It instead uses a .NET Framework version of the Universal.Agent.exe executable. This allows for the greatest compatibility with PowerShell Universal libraries and other modules. The agent still uses the PowerShell assemblies found on the executing machine.

PowerShell.exe is no longer supported. It can be used in minimal environments.

PowerShell 7 Environment No longer Uses Pwsh.exe

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

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

IIS Hosting Package

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

Integrated Environment PowerShell Version

The integrated environment now uses PowerShell 7.4.

SQLite by Default

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

LiteDB Support Removed

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

.\psudb.exe --Path "$ENV:ProgramData\UniversalAutomation\database.db"

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

Converting a Database for a MSI Upgrade

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

1. Download the ZIP package for Windows and extract to a local directory.

2. Stop the PowerShell Universal service

3. Run the psudb.exe command from the ZIP directory, as stated above, to convert the database file in %ProgramData%\UniversalAutomation

4. Update the %ProgramData%\PowerShellUniversal\appsettings.json file to use the SQLite plugin rather than the LiteDB plugin

5. Run the PowerShell Universal v5 installer to upgrade the application files.

Desktop Mode Removed

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

Install-PSUServer on Windows Installs from the MSI

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

Install-Module Universal -RequiredVersion 4.4.0
Remove-PSUServer

Open a new command prompt and run the following.

Uninstall-Module Universal
Install-Module Universal
Install-PSUServer

Git Database Storage Removed

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

Removed Heatmap and Marker Cluster from New-UDMap

Maps no longer support heatmaps or marker clusters.

A Universal app is composed of components. When building an app, you can simply call the PowerShell cmdlets within your app script to create a new component.

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

Component Types

There are over 50 components that you can use in your apps. Some of the commonly used components include:

• Data Display

  • Alerts

  • Tables

  • Timeline

• Data Visualization

  • Charts

  • Maps

• Feedback

  • Modal

  • Progress

• Inputs

  • Button

  • Form

  • Textbox

  • Switch

• Navigation

  • Menu

  • Stepper

  • Tabs

• Layout

  • Grid

  • Stack

• Utilities

  • Dynamic

  • Element

  • HTML

• Surfaces

  • Card

  • Expansion Panel

Assign schedules to scripts to define frequency and other parameters for a script, such as run as credentials.

Scheduling a Job

To schedule a job, go to the Automation / Schedules page and click the New Schedule button. To schedule a script, go to the script's page and click Schedule.

You can define schedules 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 under which user the scheduled job runs, as well as which PowerShell version it uses.

Simple Schedules

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

CRON

CRON schedules use CRON expressions to define schedules. PowerShell Universal takes advantage of Chronos. For examples of valid expressions, click here.

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 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 can 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 can 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 as which user to run the schedule by using the Run As selector in the UI. The Run As selector contains a list of PSCredential variables you have defined. You need to define a PSCredential variable before the Run As selector is visible. By default, scheduled jobs 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'

Computer

You can select the computer or computers on which to run the schedule. By default, schedules run on any available computer. If you select All Computers, the schedule runs on all computers connected to the PSU cluster. If you select a specific computer, the schedule runs on only that computer.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Computer 'PSUNODE1'

Conditions

You can define conditions that determine whether a schedule should be run. This is useful if you are using the same repository scripts for multiple environments. Currently, conditions cannot be defined within the admin console. Conditions are passed to the current script and schedule as parameters. The condition scriptblock runs within the integrated environment.

The condition needs to return true or false. Below is an example of a condition where the schedule only runs if there is an environment variable named Slot that contains the value production.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Condition {
  $ENV:Slot -eq 'production'
}

Pausing Schedules

You can pause a schedule by setting the Paused property. When a schedule is paused, it does not run. This is useful to stop a schedule from running without deleting it.

Time Out

You can set a time out for scheduled jobs. The time out is the number of minutes before the scheduled job is canceled.

Random Delay

The Random Delay property causes a schedule to start anywhere between 0 and 60 seconds from the scheduled time. This is useful when running many schedules at the same time. For example, if you had 10 schedules that start at midnight, you may want to set a random delay to limit resource contention on the PowerShell Universal service.

Available in Branch

In multi-branch environments, it may be necessary to avoid running schedules based on the branch that is loaded in PowerShell Universal. You can use the -AvailableInBranchoption on New-PSUSchedule to avoid having a schedule run when running in a certain branch. This value is also available in the admin console under the schedule settings when git is enabled.

API

• New-PSUSchedule

• Get-PSUSchedule

• Remove-PSUSchedule

You can create PowerShell scripts within PowerShell Universal to execute manually, on a schedule, or when events happen within the platform. They are stored on disk and they persist to a local or remote Git repository.

Add a New Script

To add a new script, click the New Script button within the Automation / Scripts page. There are various settings you can provide for the script.

Script Options

Name

This is the name of the script as shown in Universal Automation. This is also the name used to persist the script to disk. The name needs to be unique within the current folder.

Module and Command

See Modules and Commands below.

Description

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

Disable Manual Invocation

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

Max Job History

The max job history defines the amount of jobs stored when running this script. It defaults to 100. Jobs are also cleaned up based on the server-wide job retention duration setting from the Settings / General page.

Error Action

The error action changes how the script reacts when it has an error. By default, terminating and non-terminating errors are ignored and the script always succeeds. You can change this setting to stop to cause scripts to fail immediately when an error is encountered.

If you wish to write errors directly to the error pane without causing changes in how the script is handled (for example in an exception handler), use Write-PSUError to output the error record and it appears in the job's error tab.

Environment

This allows you to define the required PowerShell environment for the script. By default, it uses the server-wide default PowerShell environment. PowerShell environments are automatically located the first time the Universal Server starts up or read from the environments.ps1 file. You can also add Environment on the Settings / Environments page.

Timeout

The number of minutes before the script times out. The default value of 0 means the script will run forever. Once a script reaches its timeout, it is canceled.

Discard Pipeline

When checked, this disables pipeline output storage. This greatly reduces jobs' CPU and storage overhead, but the script still writes to the information, warning, and error streams.

Concurrent Jobs

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

New-PSUScript -Name Script.ps1 -Path Script.Ps1 -ConcurrentJobs 1

Running a Script

You can run a script in the UI from the Automation / Scripts page by clicking Run or by clicking View and then Run. In each case, the Run Dialog appears, allowing you to select various settings for the job.

Running a Script With Parameters

PowerShell Universal automatically determines the parameters as defined within your scripts. It takes advantage of static code analysis to determine the type, default values and some validation that is then presented within the UI.

For example, you may have a script with the following parameters:

param(
    $Test,
    [DateTime]$Time, 
    [int]$Number,
    [PSCredential]$Credential,
    [System.ConsoleColor]$Color
)

The result is a set of input options based on the types of parameters.

Running a Script as Another User

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

1. Create a new PSCredential secret variable.

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

1. Run the Script and select the credential

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

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

Running a Script on Another Computer

You can use the Computer dropdown to select other machines on which to run a script. The default value is to run on any available computer.

Running a Script on All Computers

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

Load Balancing

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

Remoting

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

Comment-Based Help

You can use comment-based help to define the description, a synopsis, parameter-based help, and links for your scripts. These will be displayed within the PowerShell Universal UI.

<#
.SYNOPSIS 

This is a script for pinging other computers. 

.DESCRIPTION

This script can ping other computers. 

.PARAMETER HostName

The host name or address to ping. 

.LINK
https://www.ironmansoftware.com
#>
param($HostName)

Test-NetConnection $HostName

The above yields the following user interface. The synopsis displays as the short description, and a longer description displays in the description section. Links appear under the description.

Modules and Commands

Commands and cmdlets found in modules can be used as the target for scripts rather than authoring the script directly.

Let's assume that we have a module called PSUModule that contains the following function.

function Show-HelloWorld {
    param($Name)
    "Hello, $Name!"
}

It's possible to expose this function as a script by using the following syntax in scripts.ps1.

New-PSUScript -Module 'PSUModule' -Command 'Show-HelloWorld'

The function surfaces just like other scripts within the admin console. Parameters, help text and other PSU features work the same as with scripts.

Statistics

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

Start-Job Support

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

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

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

API

• New-PSUScript

• Remove-PSUScript

• Set-PSUScript

• Get-PSUScript

Parameters

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

Basic Parameters

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

param($Test)

$Test

Parameters Types

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

String

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

param(
    [String]$Textbox,
    $Textbox2
)

String Arrays

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

param([String[]]$Array)

Date and Time

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

param([DateTime]$DateTime)

Boolean

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

param([Bool]$Switch)

Integer

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

param([Int]$Number)

Switch Parameter

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

param([Switch]$Switch)

Enumerations

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

param([System.DayOfWeek]$DayOfWeek)

PSCredential

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

param(
    [PSCredential]$Credential
)

File

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

param(
    [File]$File
)

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

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

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

Display Name

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

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

Help Messages

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

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

Required Parameters

You can use the Parameter attribute to define required parameters.

param(
    [Parameter(Mandatory)]
    $RequiredParameter
)

$RequiredParameter

Default Value

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

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

$Parameter
$ExecutionTime

ValidateSet

The ValidateSet attribute is used to enforce which values can be passed to a parameter. Learn about ValidateSet here. PowerShell Universal will automatically create a drop-down menu with the values provided to the ValidateSet attribute for parameters.

For example, a script could define a param block as follows.

param(
    [ValidateSet("Steve", "Mary")]
    [string]$Name
)

The result is shown below.

Passing Parameters from PowerShell

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

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

param($MyParameter)

$MyParameter

I could then invoke that script using this syntax.

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

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

Parameter Sets

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

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

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

Configure A Terminal

You can configure a new terminal by navigating to Automation \ Terminals and clicking Create New Terminal. You'll be able to select the environment and credential to run the terminal as.

Use a Terminal

To use a terminal, click the Open Terminal button for the terminal you wish to launch. Depending on your configuration, this may start a new PowerShell process based on the environment you selected.

Once the terminal has launched, you'll be able to issue commands.

Stop a Terminal

To stop a terminal, you can navigate to the terminal instances tab on the Terminals page. Click the trash can to stop the terminal.

Reconnect to a Terminal

If you navigate away from PowerShell Universal, the terminal will go idle. You can reconnect to a terminal by clicking the Open Terminal button for the idle terminal instance.

Terminals will time out automatically after 5 minutes. You can customize the timeout by setting the -IdleTimeout parameter of New-PSUTerminal.

History

Terminal history can be enabled per terminal configuration.

When terminal history is enabled, you will be able to view the history of all commands that were executed within the terminal. Click the View Command History button for the instance in question.

You will be able to review what the command was that ran, when it was ran, who started the terminal and what the output of the command was.

Create An App

The first step is to create an app in PowerShell Universal. This is the container for all your pages and components for your app website. We recommend running apps in external environments, like PowerShell 7, to ensure they are isolated from the rest of the server. To create an app, click Apps \ Apps and then Create New App.

You will need to provide a unique name and URL for the app when creating it. All other properties are optional. After creating the app, you can edit the app code. For example, try adding a component to your app.

New-UDApp -Content {
   New-UDButton -Text 'Click Me' -OnClick {
       Show-UDToast "Ouch!"
   }
}

Once you've saved your app, you can click the globe icon to view the result. Clicking the button will display a toast message in your browser.

New-UDApp

The top-level cmdlet for dashboards is New-UDApp. You need to call it when returning an app. You can use it with or without pages.

Content

The content of the app is a series of components to display on the page. It's a script block that will return all the components in the order they will be rendered on the page. You can use the Grid component to layout items and display things like text with typography.

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

Header Customization

You can customize the header of the app using several parameters.

To change the navigation layout, use the -Navigation and -NavigationLayout parameters.

New-UDApp -Content {
} -Navigation (
    New-UDList -Children {
        New-UDListItem -Label "Home"
        New-UDListItem -Label "Getting Started" -Children {
            New-UDListItem -Label "Installation" -OnClick {}
            New-UDListItem -Label "Usage" -OnClick {}
            New-UDListItem -Label "FAQs" -OnClick {}
            New-UDListItem -Label "System Requirements" -OnClick {}
            New-UDListItem -Label "Purchasing" -OnClick {}
        }
    }
) -NavigationLayout permanent

Components

Components are the individual widgets that you can place on you app. 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 app.

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

New-UDPage -Content {
    New-UDTextbox
}

Learn more about components here.

Pages

You can specify multiple pages within an app. 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 app pages.

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

Learn more about Pages here.

Module

Apps will automatically have access to any commands available within the PSModulePath as well as modules you load directly into the app itself. That said, you can also define functions within the app itself. These functions will be included with a module that is stored alongside your app code. Any functions defined within this file will be automatically included with your app.

Within the PowerShell Universal admin console, define functions, variables and aliases in the Module tab. Any functions defined with be written to a PSM1 file in the same directory as the application code.

Built-in Variables

Built-in variables can be found on the variables page.

Debugging

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

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

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

$DebugPreference = 'Continue'

Menu

You can customize the appmenu by using the -Menu parameter.

New-UDApp -Title 'App' -Content {

} -Menu {
    New-UDMenuItem -Text 'Profile' -OnClick {
        Show-UDModal -Content {
            New-UDTypography -Text 'Welcome to your profile!'
        }
    }
}

Starting and Stopping Apps

Similar to jobs, apps can run in separate PowerShell processes. You can start and stop an app process by clicking the Start or Stop button from the Apps page.

Persistent Runspaces