PoshUI Canvas
Describe an app in plain PowerShell — get a real native Windows app. No XAML. No MVVM. No project scaffolding. No build step.
Canvas is the free-form authoring layer of PoshUI. A single .ps1 file is the application: you declare controls with ordinary PowerShell cmdlets, and the PoshUI engine renders them as real WPF controls and runs your PowerShell behind them.
Import-Module PoshUI.Canvas
New-PoshUICanvas -Title 'Hello' -Theme Dark
Add-UICanvasPage -Title 'Home' -Layout VStack
Add-UICanvasLabel 'What is your name?' -FontSize 18 -FontWeight Bold
Add-UICanvasTextBox -Name who -Value 'World'
Add-UICanvasButton 'Greet' -Style Accent -Action {
Show-UICanvasToast -Message ("Hello, " + (Get-UICanvasValue -Name who))
}
Show-PoshUICanvasThat is a complete, working, themed desktop application. Save it, run it, ship it.
Building with an AI assistant
Canvas needs no AI, but it works well with one: about 90 cmdlets with consistent parameters, one script, and no build step. Give your assistant the agent guide, describe the tool you want in plain English, save the .ps1 it returns, and run it. Iterate by describing changes.
How it works
Authoring (PowerShell). Each Add-UICanvas* call appends a control definition to an in-memory tree. The lifecycle is fixed and simple:
Import-Module → New-PoshUICanvas → [Set-UITheme] → Add-UICanvasPage → Add-UICanvas* … → Show-PoshUICanvasNothing renders until Show-PoshUICanvas, which serializes the tree and launches the engine.
Rendering (the engine). PoshUI.exe (.NET Framework 4.8 / WPF) reads the definition and builds genuine WPF controls through its control factory. It software-renders, so it does not depend on GPU compositing — it runs on virtual machines, remote sessions, and locked-down hardware where modern compositor-based UI stacks fall over.
The bridge (live interactivity). An in-process PowerShell runspace connects your scripts to the live UI. Inside any -Action, -OnChange, or refresh script you can read and drive the running app: Get-UICanvasValue, Set-UICanvasValue, Set-UICanvasProperty, reactive state, navigation, dialogs.
Where your code runs
Your code runs in one of three places. Picking the right one is what keeps an app responsive:
| Where | What runs there | Use it for |
|---|---|---|
| The UI's own PowerShell session | -Action, -OnChange, -Refresh | clicks, form submits, live labels — anything quick |
| A background session | Start-UICanvasAsync { }, Add-UICanvasScriptCard | long work: scans, API calls, installs |
| The workflow runner | Add-UICanvasWorkflow -Engine steps | multi-step jobs with progress, retry and reboot-resume |
The UI's session runs one thing at a time: while a slow action runs, other clicks wait and -Refresh ticks are skipped. So put anything slow in the background or in a workflow, and the window stays live.
What it can do
Controls — text, buttons, dropdowns, list boxes, radio groups, checkboxes, toggles, sliders, number boxes, password fields (DPAPI-protected), date/time pickers, color picker, rating, auto-suggest, file/folder pickers, markdown, images, hyperlinks, icons, badges, separators, shapes, consoles, data grids, tree views, progress bars/rings, banners, and menu bars.
Layout — Grid, VStack, HStack, Wrap, Dock, and absolute X/Y positioning, with Card / Panel / Expander / Tabs / Viewbox containers, a GridSplitter for resizable panes, and scrolling. (The full WPF panel set.)
Three app shapes, one toolkit:
- Forms & wizards — multi-page flows with gated Back/Next, required-field and custom validation, step indicators, navigation locking, and cascading dropdowns (
-DependsOn/-OptionsScript) that recompute their options when a parent field changes. - Dashboards — metric, status, table and chart cards that auto-refresh, reactive state binding, data-driven repeaters, and
Add-UICanvasScriptCard— an on-demand runner card that runs its script in the background and streams its output live, so a long job never freezes the rest of the dashboard. - Workflows — declare steps, get an engine-driven runner with live progress, retry, timeouts, skip conditions, and reboot-resume (state persists across a restart and the run continues where it left off).
Everything else — theming (dark/light, presets, per-slot overrides), charts (bar/line/area/donut/ sparkline), animation, toasts, dialogs, flyouts, secondary windows, keyboard shortcuts, and — for anything the cmdlets don't cover — a raw XAML escape hatch.
Deployment — a single script plus the engine. No external dependencies, no runtime to install, fully offline, and air-gap friendly.
Sizing, DPI & multiple monitors
Every size you write is a logical unit, not a physical pixel. -Width 600, -FontSize 14, -StepsHeight 300, -X/-Y — all device-independent units (1/96"). The engine scales them for you, so a Canvas app renders correctly and crisply at 125% / 150% / 200% display scaling with no work on your part.
The engine declares Per-Monitor V2 DPI awareness, so a window moved between monitors with different scaling re-renders at the new monitor's DPI rather than being bitmap-stretched, and it adapts live if you change display scaling while the app is running.
The one thing to design for: logical space shrinks as scaling rises
Higher scaling means fewer logical units to lay out in — this catches people out:
| Physical resolution | Scaling | Logical space you actually get |
|---|---|---|
| 1920 × 1080 | 100% | 1920 × 1080 |
| 1920 × 1080 | 150% | 1280 × 720 |
| 2560 × 1440 | 150% | 1707 × 960 |
| 3840 × 2160 | 200% | 1920 × 1080 |
A 1080p laptop at 150% gives you only 720 logical pixels of height. So New-PoshUICanvas -Width 1280 -Height 740 — which looks modest — will not fit on that display.
Rules that hold up across monitors
- Budget for the smallest logical size you'll target — ~
1280 × 700is a safe floor if laptops are in scope. Don't size against physical pixels. - Prefer proportional layout over fixed sizes. Grid star sizing (
-ColumnWidths '3*,*'),Dock, andHAlign/VAlign = 'Stretch'reflow as space changes; fixed-Heightvalues clip. - Set window minimums so the window can't be dragged into a broken state:
New-PoshUICanvas -Width 1100 -Height 700 -MinWidth 900 -MinHeight 600. - Scroll the tall region, not the page. Give the one growable list a fixed height with internal scrolling (e.g. a workflow's
-StepsHeight 300, or-Properties @{ Scroll = 'Vertical' }) so the surrounding layout stays put. - Test at 150%. It's the most common laptop default and the tightest realistic case.
The escape hatch: raw XAML
Canvas says "no XAML" because you never have to write it — the cmdlets cover the common surface. But the door is open when you need it, and that's what makes the parity claim literal: anything WPF can render, Canvas can render.
Add-UICanvasXaml splices raw WPF markup straight into the control tree. Crucially, any element you give an x:Name is registered with the bridge, so it behaves like a first-class control — Get-UICanvasValue, Set-UICanvasValue and Set-UICanvasProperty all work on it.
# No cmdlet wraps MediaElement, so drop to XAML for it - and still drive it from PowerShell.
Add-UICanvasXaml -Markup @'
<StackPanel>
<MediaElement x:Name="player" Height="240" LoadedBehavior="Manual" />
<TextBlock x:Name="nowPlaying" Margin="0,8,0,0" Text="nothing loaded" />
</StackPanel>
'@
# The x:Name'd elements are live controls - drive them like any other:
Add-UICanvasButton 'Load clip' -Style Accent -Action {
$f = Select-UICanvasFile -Title 'Pick a video' -Filter 'Video (*.mp4)|*.mp4'
if ($f) {
Set-UICanvasProperty -Name player -Property Source -Value $f
Set-UICanvasValue -Name nowPlaying -Value "loaded $f"
}
}The root element's xmlns is added automatically if you omit it, and -Path loads markup from a file instead of inline. (Tabs, menus and splitters now have native cmdlets — see above — so reach for XAML for things like MediaElement, custom control templates and styles, or anything else you'd use in a normal WPF app.) Then go straight back to cmdlets for the rest of the page: mixing the two freely is the intended workflow, not a fallback.
Using it
A form that does something
Import-Module PoshUI.Canvas
New-PoshUICanvas -Title 'Service Restart' -Theme Dark
Add-UICanvasPage -Title 'Main' -Layout VStack
Add-UICanvasLabel 'Restart a service' -FontSize 20 -FontWeight Bold
Add-UICanvasDropdown -Name svc -Choices (Get-Service | Select-Object -First 20 -Expand Name)
Add-UICanvasButton 'Restart' -Style Accent -Action {
$s = Get-UICanvasValue -Name svc
Restart-Service -Name $s -ErrorAction Stop
Show-UICanvasToast -Message "$s restarted" -Severity success
}
Show-PoshUICanvasA dashboard that stays responsive
# Live, polled value
Add-UICanvasLabel -Name clock -Label { Get-Date -Format 'HH:mm:ss' } -Refresh 1
# On-demand work that runs in the background and streams its output
Add-UICanvasScriptCard 'Collect logs' -Detail 'Zips the last 24h of logs' -Script {
"starting..."
# ...real work; every line appears in the card's console as it runs
"done"
}A workflow with retry and live progress
Add-UICanvasWorkflowStep 'Download' -ExpectedSeconds 30 -Retry 2 -Script {
1..10 | ForEach-Object { $wf.UpdateProgress($_ * 10, "downloading $($_*10)%"); Start-Sleep 1 }
}
Add-UICanvasWorkflowStep 'Install' -ExpectedSeconds 60 -Script {
$wf.WriteOutput('installing...', 'INFO')
}
Add-UICanvasWorkflow -Engine -Name deploy -StateFile 'C:\ProgramData\MyApp\state.json'Steps receive $wf (the workflow context): UpdateProgress, WriteOutput, GetValue/SetValue for canvas controls, SetData/GetData to pass data between steps, SkipTask, and RequestReboot — which saves state so the run resumes automatically after a restart.
Cascading fields
Add-UICanvasDropdown -Name region -Choices 'US','EU','APAC'
Add-UICanvasDropdown -Name dc -DependsOn region -OptionsScript {
switch (Get-UICanvasValue -Name region) {
'US' { 'us-east-1','us-west-2' }
'EU' { 'eu-central-1','eu-west-1' }
'APAC' { 'ap-southeast-1' }
}
}Two rules that prevent most problems
- Save scripts as UTF-8 with BOM if they contain any non-ASCII character (—, ●, emoji, accents). Windows PowerShell 5.1 misreads UTF-8 without a BOM and the app breaks.
- Don't reference a local
$Nameinside a-Children { }block — container cmdlets have their own-Nameparameter which shadows it. Alias it first ($myName = $Name).
The agent guide has the complete list.
Handing it to users
Users shouldn't have to run a .ps1. New-PoshUIApp turns the script into its own exe: a copy of the signed PoshUI.exe named after the app, plus a MyApp.app.json that names the script, icon, whether it needs admin, and the shortcuts to create.
New-PoshUIApp -Config .\MyApp.app.json -Destination D:\Out\MyApp
D:\Out\MyApp\MyApp.exe --create-shortcutsDouble-clicking MyApp.exe (or its shortcut) runs the script inside PoshUI: no console window, one process, your icon on the window and taskbar. → Staging & Delivery
Next steps
- Agent Authoring Guide — the full LLM context pack: architecture, every control, the runtime, charts, theming, flows, gotchas, and a cheatsheet.
- Capability Reference — terse index of every capability.
