Setting up portable, side-by-side PowerShell Universal instances on the same machine

This post walks through how to set up isolated PowerShell Universal instances on the same machine. That is useful for testing different versions, trying different server configurations, or isolating resources across environments. We use this technique extensively in our testing and development environments.

Installation

The first step is to set up a folder to host your PowerShell Universal app and configuration files. Next, download the PowerShell Universal ZIP and place it in an App directory. You can use the following script to retrieve the latest version 4 build and extract it to a local directory. Create an update.ps1 script in your directory and run it.

$Version = (Invoke-WebRequest https://imsreleases.blob.core.windows.net/universal/production/v4-version.txt).Content

Write-Verbose "Downloading $Version..."

$Temp = [System.IO.Path]::GetTempPath()
$Zip = (Join-Path $Temp "Universal.$Version.zip")

if (Test-Path $Zip) {
    Remove-Item $Zip -Force
}

Invoke-WebRequest "https://imsreleases.blob.core.windows.net/universal/production/$version/Universal.win7-x64.$Version.zip" -OutFile $Zip
$AppPath = Join-Path $PSScriptRoot "App"
if (Test-Path $AppPath) {
    Remove-Item $AppPath -Recurse -Force
}

Expand-Archive -Path $Zip -DestinationPath $AppPath
Get-ChildItem $AppPath -Recurse | Unblock-File

If you want to use version 5, change the v4-version.txt portion of the version URL to v5-version.txt. You can also hard-code the version if you want a specific build. In the blob URL for the ZIP, you may have noticed the win7-x64 portion. That is the platform the ZIP is built for. You can change this to linux-x64 or osx-x64 if you are running on a different platform. Visit the download center to see how these URLs are formatted if the blob is not available.

The ZIP install docs also cover extracting, unblocking, and starting Universal.Server.exe.

Configuration

Next, create a run.ps1 in your directory to set up the configuration for your instance. The settings use relative paths for the repository, database, and log files. Below, we use environment variables to set the configuration based on the appsettings.json file in the App folder. Any environment variables override the settings in appsettings.json. See app settings for the full list.

param($Port = 5000)

$ENV:Data__RepositoryPath = "$PSScriptRoot\Repository"
$ENV:Data__ConnectionString = "Data Source=$PSScriptRoot\Database.db"
$ENV:Kestrel__Endpoints__HTTP__Url = "http://localhost:$Port"
$ENV:Plugins__0 = "SQLite"
$ENV:SystemLogPath = "$PSScriptRoot\Logs\SysLog.txt"

& "$PSScriptRoot\App\Universal.Server.exe"

This script sets the configuration for your instance. You can run it with a specific port to start the instance. Duplicate the script to another directory and change the port to run multiple instances. Each instance has its own configuration and data. You cannot share ports between instances unless you are using IIS.

Ready to build? Download PowerShell Universal.