Downloads

Download the latest version of PowerShell Universal.

Training

Watch our free PowerShell Universal training course.

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.

Samples

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

Videos

Check out video tutorials for PowerShell Universal.

SQL Server Support

You can now persist jobs, identities and app tokens in a SQL server database to allow for multi-node instances that provide high availability and load balancing.

Improved Editing Experience

Features such as live logging and advanced dashboard and repository editors of the admin console have been added to make editing scripts in PowerShell Universal easier to develop and debug.

Desktop Features

PowerShell Universal Desktop now offers integrations like file associations, hot keys, system events and custom protocols to trigger scripts when certain things happen on your system.

Translations

A built in translation provider is available in your dashboards, scripts, and APIs to provide the proper language when returning data back to your end users.

New Dashboard Components

New dashboard components such as the data grid, stack, badge, timeline and schema form allow you to bring even more functionality to your user interfaces.

MSI Install (Windows)

The MSI install will create a PowerShell Universal service. By default, PowerShell Universal will be listening on port 5000. You will be able to navigate to http://localhost:5000 and login with admin and password admin.

MSI downloads are available on our download page.

MSI Parameters

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

Example

Below is an example of how to run msiexec.exe to install PowerShell Universal and provide parameters to the installer.

 Start-Process msiexec.exe -ArgumentList "/I C:\Users\adamr\Downloads\PowerShellUniversal.3.5.1.msi /q /norestart /L*V `"C:\users\adamr\desktop\msi.log.txt`" STARTSERVICE=0" -Wait -NoNewWindow

ZIP Install

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

Windows

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

Expand-Archive -Path .\Universal.zip -DestinationPath .\Universal
Get-ChildItem .\Universal -Recurse | Unblock-File
Start-Process .\Universal\Universal.Server.exe

Linux

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

 wget https://imsreleases.blob.core.windows.net/universal/production/2.0.0/Universal.linux-x64.2.0.0.zip
 sudo apt install unzip 
 unzip Universal.linux-x64.2.0.0.zip -d PSU
 chmod +x ./PSU/Universal.Server
 ./PSU/Universal.Server

PowerShell Module

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

Install-Module Universal

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

Install-PSUServer -LatestVersion

If you run this command on Windows, a Windows service will be created and started on your machine. If you run this command on Linux, a systemd service will be created and started. If you run this command on Mac OS, the PowerShell Universal server will be downloaded and extracted.

Chocolatey Package (Windows)

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

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

choco install powershelluniversal

Docker

See the Docker page.

IIS Install

Please visit the IIS hosting documentation for information on how to configure PowerShell Universal as an IIS website.

Antivirus Configuration

PowerShell Universal takes full advantage of PowerShell and the PowerShell SDK. It includes PowerShell scripts directly in the product. You will want to consider configuring antivirus to allow for execution of PowerShell scripts in PowerShell Universal.

Directories

The following directories will contain scripts and executable files that may need to be excluded from antivirus checks.

The following are examples from a standard Windows system. Changing paths within appsettings.json or within the installer will require changing which directories are execluded.

Executables

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

Next Steps

At this point, Universal is up and running. You can navigate to the admin console by visiting http://localhost:5000 by default. The default username is admin with a password of admin.

Docker

Confirming Docker is installed correctly

NOTE: 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 accoridingly. More infromation on Docker Compose can be found here.

Run one of the following commands to check 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, you can use the provided container image. The docker image is available on Docker Hub .

The prebuilt version allows you to run all free and paid features of PowerShell Universal.

You can 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, this can be switched 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 will allow you to mount a volume for persistent storage. This needs to be mounted 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 be used to 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 will run a Powershell Universal container in Windows

version: "3.7"
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 will run a Powershell Universal container on Mac's and Linux

version: "3.7"
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. cd to the 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 Persistance

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

• Setting a node name

• Adding SQL persistance

• Adding a SQL Connection String

version: "3.7"
services:
  PSU:
    container_name: PSU
    image: ironmansoftware/universal:latest
    ports:
      - 5000:5000
    restart: unless-stopped
    environment:
      - TZ=Europe/London
      - Plugins:0=SQL
      - Data__ConnectionString=Server=ServerName; Database=DatabaseName; User Id=UserName; Password=UserPassword;Encrypt=False
      - NodeName=mynodename
    volumes:
      - /docker/volumes/PSU:/root

Building a Custom Container

In some cases, you may wish to build more features, modify, or hardcode Environment Variables into your container.

For that, you will need to 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, you can create a dockerfile like the one below.

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

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 /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 your Dockerfile is hosted in run the following command:

docker build . --tag=universal-persistent

Windows

FROM ironmansoftware/universal:1.3.1-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 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"]

You can run a build with the build command.

docker build . --tag=universal-persistent

You can 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, you can define the plugin and connection string as follows.

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

Time Zones

To properly support time zones on Linux when scheduling jobs, you will need to 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

Summary

This has been a very basic "How get get started" which allows you to get started running or building PSU Containers. All souces for commands have been linked in the referances session.

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/

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.

LiteDB

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

Windows

• %ProgramData%\PowerShellUniversal\database.db

Linux and Mac OS

• %HOME%/.PowerShellUniversal/database.db

SQL

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

IIS

You may need to uninstall the IIS App Pool and Website when removing PowerShell Universal.

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.

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.

LiteDB

By default, PowerShell Universal uses a single file database called LiteDB. 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 backup 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.

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.

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

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

ZIP

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

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

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

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.

Environments

Verify that all environments are listed in the Settings \ Environments page. Although upgrades may not necessarily cause a change in environments, restarting the PowerShell Universal service (without an environments.ps1 file) will cause PSU to rediscover environments. Updates to PowerShell outside of PSU may cause issues with PSU after it restarts.

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.

Dashboards

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

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

3.0 Breaking Changes

If you are upgrading from 2.x, you will have a couple of breaking changes.

Secret Variables Not Directly Defined

UD v2 Framework Removed

The UDv2 framework has been removed and is no longer supported. If you wish to use this framework, you can install it from the PowerShell Gallery.

IIS Hosting Package

PowerShell Support

PowerShell 7.2 or later is supported by PowerShell Universal v3.

Migrating from LiteDB to SQL

Once migrated, you will need to update the plugin setting within appsettings.json. Replace the UniversalAutomation.LiteDBv5 value with the string SQL. You can also set an environment variable to use the SQL plugin.

You'll also need to replace the connection string value with your SQL Data \ ConnectionString.

Similar to the plugin, you can use an environment variable instead of updating appsetings.json.

The step by step process is as follows:

1. Stop the PowerShell Universal service

2. Backup the database and repository

3. Run the data migration tool

4. Update the appsettings.json or environment variable to enable the SQL plugin and set the connection string.

5. Start the PowerShell Universal service

Once the service starts, it will be connected to SQL. Job data, identities, computers, and terminal instances will be stored in SQL.

A single pane of glass for managing and delegating access to your automation environment.

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

Featured Template: Active Directory

Curious what you can do with PowerShell Universal? Check out our featured Active Directory template.

This template includes features such as:

• Object Search

• User Management and Reports

• Group Management

• Infrastructure Reports

APIs

Expose scripts as RESTful HTTP APIs for integration from any platform.

• HTTP Endpoints

• Custom Responses

• Token-Based Authentication

• Rate Limiting

• Large File Support

• Open API Documentation

• File Hosting

Automation

Execute, schedule, secure and audit scripts in an easy-to-use, web-interface.

• Scheduling

• Run As Support

• Mutliple Environments

• Automatic Form Generation

• Feedback Integration

• Pipeline Output

• Event Triggers

• Concurrency Controls

• Ad-Hoc Terminals

User Interfaces

Build web-based tools for internal users with highly interactive user interfaces that run your scripts.

• Interactive Dashboards

• Input Forms

• Customizable Tables

• Charts

• Dynamic Regions

• Steppers (Wizards)

• Transitions

• Drag and Drop Pages

• Integration with Scripts and APIs

• Extensible Platform

• Custom Styling and Branding

Hosting

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

• Windows, Linux and Mac

• Docker Containers

• Azure and IIS

• Windows Service

• HTTPS

Security

Grant role-based access to different aspects of your automation environment with your choice of authentication and authorization integrations.

• OpenID Connect

• WS-Federation

• Basic Authentication

• Client Certificate

• SAML2

• Windows Authentication

• Script-Based Authorization

• Claims-Based Authorization

• Script Access Controls

• Custom and Built-In Roles

Desktop

Create desktop automation and user interfaces that integrate with features of Windows.

• File Associations

• Hotkeys

• Protocol Handlers

• System Events

• User Interfaces

Development

Take advantage of rich development tools such as IntelliSense, code formatting, error checking and debugger integration without leaving your browser.

• Rich Editing Experience

• Code-First Configuration

• Debugging Tools

• PowerShell Module

• Management API

• Visual Studio Code Extension

• Performance Profiler

• Desktop Mode

• Hotkeys

Platform

Configure the platform to meet the needs of your environment.

• PowerShell 7 Support

• Windows PowerShell Support

• PowerShell Modules

• Variables

• Password and Secret Management

• Git Integration

• Application Insights Integration

Community

Join the growing community of users managing their automation environments with PowerShell Universal.

• Forums

• Discord

• Templates

• Issue Tracker

Licensing

Universal is licensed per server. Visit our website for more information on pricing.

Many features of PowerShell Universal are free.

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 is running on port 5000 of localhost. You can access the admin console with the username admin and admin.

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 the API that was created an 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 a Dashboard

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

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

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

Save the dashboard, 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

• Dashboards

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.

Per Endpoint Environment

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

Performance

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

Variables

API

Windows

• Optional*: or greater

• Optional*: PowerShell v7.2 or greater

• (only for Windows PowerShell)

Linux

• Optional*: PowerShell v6.0 or greater

• Validated Distributions: Ubuntu 18.04

Mac OS

• Optional*: PowerShell v6.0 or greater

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

You can purchase a license on .

What's a server?

A server is a single running instance of PowerShell Universal.

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.

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.

Developer Licenses

When a server license is purchased, you will be able to generate developer licenses for users building solutions for your team. Developer licenses do not allow remote access and are intended to be used locally. Do not use developer licenses when hosting a server for remote access for testing or production.

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

• Enterprise Authorization

  • Access Controls

  • Custom Authorization Scripts

• Git Support

• Module Management

• Non-Database Credential Vaults

• SQL Support

• Triggers

• Terminals

• Custom Login Page

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

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

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.

New-PSUEndpoint -Url "/error" -Endpoint { 
   throw "Uh oh!"
} -ErrorAction stop

New-PSUEndpoint -Url /error2 -Endpoint {
    Write-Error "Whoa!"
} -ErrorAction Stop

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.

PS C:\Users\adamr> invoke-restmethod http://localhost:5000/error2
invoke-restmethod : The remote server returned an error: (500) Internal Server Error.
At line:1 char:1
+ invoke-restmethod http://localhost:5000/error2
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
   Exception
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

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

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error 

Invoke-RestMethod: Uh oh!
at , : line 2
at , : line 1

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error2

Invoke-RestMethod: Whoa
at , : line 2
at , : line 1

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

PS C:\Users\adamr> try { invoke-restmethod http://localhost:5000/error2 } catch { [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream()).ReadToEnd()}
Whoa!
at <ScriptBlock>, <No file>: line 2
at <ScriptBlock>, <No file>: line 1

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.

New-PSUEndpoint -Url /broken -Endpoint {
    New-PSUApiResponse -StatusCode 404 -Body 'Failed!'
}

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.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/broken

Invoke-RestMethod: Failed!

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

PS C:\Users\adamr> invoke-restmethod http://localhost:5000/broken
invoke-restmethod : The remote server returned an error: (404) Not Found.
At line:1 char:1
+ invoke-restmethod http://localhost:5000/broken
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
   Exception
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

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

New-PSUEndpoint -Url /user/:name -Endpoint {
    if ($Name -eq 'User')
    {
        @{ UserName = "Adam" }
    }
    else
    {
        New-PSUApiResponse -StatusCode 404 -Body 'Unknown user!'    
    }

}

API

• New-PSUEndpoint

• Get-PSUEndpoint

• Remove-PSUEndpoint

• New-PSUApiResponse

• Set-PSUSetting

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

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

Configuring Rate Limiting

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

Method

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

Endpoint

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

Limit

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

Period

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

Allow Lists

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

API

• New-PSURateLimit

• Set-PSUSetting

Run Scripts

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

Schedule Jobs

You can schedule jobs to run continuously, at certain times or even when events happen within the PowerShell Universal platform.

Ad-Hoc Commands

Run ad-hoc commands in terminals in any of your configured environments and, optionally, as alternate credentials.

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

Defining Secure Endpoints

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

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

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

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

• JWT App Tokens

• Windows Authentication

• Cookie Authentication

Accessing Secure Endpoints

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

Authenticating with tokens

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

Click Grant App Token to create a new one.

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

Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMWUyY2IzNzAtMmMyNS00ZDU5LTk4YzgtMzc5MTFjMDAyZmI5Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MDU2NjEyNTUsImV4cCI6MTYzNzM2NzI1OCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG" }

Authenticating with Windows Authentication

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

Invoke-RestMethod http://localhost:5000/auth -UseDefaultCredentials

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.

Invoke-WebRequest http://localhost:5000/api/v1/signin -Body (@{ 
    UserName = "Admin"
    Password = "Any"
} | ConvertTo-Json) -ContentType 'application/json' -SessionVariable mySession -Method POST

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

 Invoke-WebRequest http://localhost:5000/auth -WebSession $mySession

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

• New-PSUEndpoint

• Get-PSUEndpoint

• Remove-PSUEndpoint

• New-PSUApiResponse

• Set-PSUSetting

PowerShell scripts can be created within PowerShell Universal to execute manually, on a scheudle or when events happen within the platform. They are stored on disk and also persisted to a local or remote Git repository.

Add a New Script

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

Script Options

Name

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

Description

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

Disable Manual Invocation

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

Manual Time

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

Max Job History

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

Error Action

Changes how the script reacts when there is an error within the script. By default, terminating and non-terminating errors are ignored and the script will always be successful. You can change this setting to stop to cause scripts to fail immediately when an error is encountered.

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

Environment

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

Timeout

The number of minutes before the script will timeout. The default value of 0 means the script will run forever. Once a script reaches it's time out, it will be cancelled.

Anonymous

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

Discard Pipeline

When checked, this will disable the storage of pipeline output. This will greatly reduce the CPU and storage overhead of jobs. The script will still write to the information, warning, and error streams.

Concurrent Jobs

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

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

Running a Script

You can run a script in the UI by click the Run button the Automation / Scripts page or by clicking View and then Run. In each case, you will be presented with the Run Dialog that allows you to select various settings for the job.

Running a Script With Parameters

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

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

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

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

Running a Script as Another User

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

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

Running a Script on Another Computer

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

Running a Script on All Computers

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

Remoting

Note that you can use PowerShell remoting by taking advantage of Invoke-Command . We do not support the use of Enter-PSSession or Import-PSSession.

Comment-Based Help

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

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

This above will yield the following user interface. The synopsis will be shown as the short description and a longer description can be shown in the description section. Links will appear under the description.

API

• New-PSUScript

• Remove-PSUScript

• Set-PSUScript

• Get-PSUScript

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

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

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

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

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

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

Variable URL

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

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

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

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

Query String Parameters

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

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

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

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

Security Considerations

When accepting input via Query String parameters you may be vulnerable to CWE-914: Improper Control of Dynamically-Identified Variables. Consider using a param block to ensure that only valid parameters are provided to the endpoint.

Below is an example of CWE-914. A $IsChallengePassed query string parameter could be included to bypass the challenge.

New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Vulnerable to CWE-914" -Endpoint {
	if($ChallengeInputData -eq "AcceptableInput") {
		$IsChallengePassed = $true
	}
	if($IsChallengePassed) {
		"Challenge passed. Here is Sensitive Information"
	} else {
		"Challenge not passed"
	}
}

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

New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Not Vulnerable to CWE-914" -Endpoint {
	Param(
		$ChallengeInputData
	)
	if($ChallengeInputData -eq "AcceptableInput") {
		$IsChallengePassed = $true
	}
	if($IsChallengePassed) {
		"Challenge passed. Here is Sensitive Information"
	} else {
		"Challenge not passed"
	}
}

Headers

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

$Headers['Content-Type']

Cookies

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

$Cookies['Request-Cookie']

Request cookies can be sent back using the New-PSUApiResponse cmdlet. Use the -Cookies parameter with a supplied hashtable.

New-PSUApiResponse -StatusCode 200 -Cookies @{
    ResponseCookie = '123'
}

Body

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

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

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

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

Live Log

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

Form Data

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

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

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

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

JSON Data

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

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

You can then send JSON data to the endpoint.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
} | ConvertTo-Json) -ContentType 'application/json'

Param Block

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

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

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

Returning Data

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

Processing Files

Uploading Files

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

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

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

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

You could also save the file into a directory.

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

Downloading Files

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

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

Returning Custom Responses

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

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

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

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

Invoking the REST method will return the custom error code.

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

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

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

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

Documenting APIs

API documentation can be produced for your endpoints by creating a new OpenAPI definition and assigning endpoints to it. 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 page.

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

<# 
.SYNOPSIS
This is an endpoint

.DESCRIPTION
This is a description

.PARAMETER ID
This is an ID.

#>
param($ID)
    
$Id

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. You can create types in the read-only section of the PowerShell Universal configuration file.

#region PSUHeader 

[Documentation()]
class MyReturnType {
    [string]$Value
}

#endregion
New-PSUEndpoint -Url "/documented" -Method @('GET') -Endpoint {
<# 
.SYNOPSIS
This is an endpoint
    
.DESCRIPTION
This is a description

.PARAMETER Id
This is an ID.

.PARAMETER AnotherOne
This is AnotherOne

.OUTPUTS
    200:
        Description: This is an output value. 
        Content:
            application/json: MyReturnType

    400:
        Description: Invalid input
.INPUTS 
    Required: false
    Description: This is an input value.
    Content: 
        application/json: MyReturnType

#>
param($Id, $AnotherOne)
} -Authentication

Persistent Runspaces

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

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

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

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

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

Set-PSUSetting -ApiEnvironment 'Env'

Timeout

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

External Endpoint Content

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

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

New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"

Experimental Feature: C# APIs

As of PowerShell Universal 3.5.0, you can now enable C# APIs as an experimental feature. To learn more about enabling experimental features, click here. C# APIs are significantly faster than PowerShell APIs (5 - 20 times faster).

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

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

public class ApiRequest
{
    public long Id;
    public ICollection<KeyValue> Variables;
    public IEnumerable<ApiFile> Files { get; set; };
    public string Url;
    public ICollection<KeyValue> Headers;
    public byte[] Data;
    public int ErrorAction;
    public ICollection<KeyValue> Parameters;
    public string Method;
    public ICollection<KeyValue> Cookies;
    public string ClaimsPrincipal;
    public string ContentType;
}

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

var dm = ServiceProvider.GetService(typeof(IDashboardManager));
var dashboard = dm.GetDashboard(1);
dm.Restart(dashboard);

Some other useful services may include:

• IDatabase

• IApiService

• IConfigurationService

• IJobService

You can choose to return an ApiResponse from your endpoint.

return new ApiResponse {
    StatusCode = 404
};

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

New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#'

C# endpoints are compiled and run directly in the PowerShell Universal service.

API

• New-PSUEndpoint

• Get-PSUEndpoint

• Remove-PSUEndpoint

• New-PSUApiResponse

• Set-PSUSetting

System events subscribe to WMI events within Windows and run scripts. You can then take action by running scripts.

Defining a System Event

To define a system event, you can use the New-PSUSystemEvent cmdlet within the systemEvents.ps1 file. The following example triggers the systemEvent.ps1 script when a pwsh.exe process is started.

Accessing Event Data

When a script is executed, you will receive a $TargetInstance parameter. This contains the WMI object that caused the event to trigger.

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

• PowerShell Protect Event

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

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.

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.

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.

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.

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.

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

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.

API

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.

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.

String Arrays

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

Date and Time

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

Boolean

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

Integer

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

Switch Parameter

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

Enumerations

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

PSCredential

File

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

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.

Display Name

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

Help Messages

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

Required Parameters

You can use the Parameter attribute to define required parameters.

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.

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.

I could then invoke that script using this syntax.

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.

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

Scheduling a Job

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

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

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

Simple Schedules

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

CRON

One Time

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

Continuous

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

Parameters

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

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

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

Environments

Run As

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.

Computer

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

Conditions

Conditions can be defined 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 the current script and schedule as parameters. The condition scriptblock is run within the integrated environment.

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

Pausing Schedules

You can pause a schedule by setting the Paused property. When a schedule is paused, it will not run. This is useful to stop a schedule from running but not delete 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.

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.

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

Experimental Feature: 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

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.