For the complete documentation index, see llms.txt. This page is also available as Markdown.

Interaction

Invoke-UDRedirect https://devolutions.net/powershell-universal/

Universal Apps enables the ability to create interactive websites with PowerShell. Several cmdlets provide feedback to the user, update components, read component state, and persist browser-local preferences.

Clipboard

You can set string data into the user's clipboard with Set-UDClipboard.

New-UDButton -Text 'Clipboard' -OnClick {
    Set-UDClipboard -Data 'Hello, there!'
}

API

  • Set-UDClipboard

Downloads

You can start a download within the user's browser by using Start-UDDownload. Due to browser security, the user needs to take an action, such as clicking a button, to allow the download. Start-UDDownload is not suited for large file downloads.

New-UDButton -Text 'Download' -OnClick {
    Start-UDDownload -StringData 'Hello, World!'
}

Local storage

Use Set-UDLocalStorage and Get-UDLocalStorage to persist a user's app preferences in browser local storage. Values remain available after a page reload and when the user opens the same app later in the same browser profile.

PowerShell Universal scopes stored values to the dashboard and browser. They are not shared with other users, browsers, or dashboards. Use these cmdlets from an interactive event handler so PowerShell Universal can communicate with the connected browser.

Values are serialized with the PowerShell serializer before they are stored, so you can save and retrieve PowerShell objects and hashtables. Get-UDLocalStorage returns $null when the item does not exist.

Browser local storage is readable and modifiable by code running in the page. Do not store passwords, credentials, API keys, tokens, or other sensitive data in it. Treat stored values as user-controlled input.

API

  • Set-UDLocalStorage

  • Get-UDLocalStorage

Event Handlers

Many components support event handlers in the form of script blocks. You may also see these referred to as endpoints, as that is what they were called in Universal Dashboard v2. These event handlers allow you to invoke PowerShell scripts when certain actions take place on the page.

For example, you may have a button click that calls an event handler. This button shows a toast when clicked. You can include any valid PowerShell cmdlet within the event handler code.

Variable Scope

Variables are automatically scoped into event handlers. You can access variables that you define outside of the event handler.

Event Data

Some event handlers provide data as a string or as a hashtable. This depends on the event handler you are using. For example, the New-UDButton -OnClick event handler does not provide data. On the other hand, the New-UDSelect -OnChange provides event data.

You can access the event data by using the $Body variable as a string, sometimes formatted as JSON, or by using the $EventData variable as a hashtable.

Forms

Submit a Form

You can force a form to submit using the Invoke-UDForm cmdlet. You can optionally enforce validation by including the -Validate parameter.

Validate a Form

You can force a form to validate by using Test-UDForm.

JavaScript

You can invoke JavaScript from PowerShell by using the Invoke-UDJavaScript cmdlet.

API

  • Invoke-UDJavaScript

Toast

Show a toast

You can use the Show-UDToast cmdlet to create a toast message that appears on the end user's webpage. It happens over a WebSocket and shows the toast immediately.

Show a toast with an icon

Toasts support icons as strings. You can use all FontAwesome v5 icons.

Hide a toast

Hide a toast based on the specified ID.

API

  • Show-UDToast

  • Hide-UDToast

Redirect

You can redirect users to different pages using the Invoke-UDRedirect cmdlet. It happens over a WebSocket and redirects as soon as the cmdlet is called.

Invoke-UDRedirect automatically redirects to pages in the dashboard when using a relative path.

If you would like to redirect to a local path outside of the dashboard, use the -Native parameter.

API

  • Invoke-UDRedirect

You can open a modal using the Show-UDModal cmdlet. It opens as soon as you call it. You can include whatever components you like within the modal.

Read more about Modals here.

Managing Component State

You can manage component state dynamically by using the UDElement commands.

Getting Component State

You can receive the state of an element using Get-UDElement. The state is returned as a hashtable. This is primarily useful for input components.

Setting Component State

Alternatively, you can set component state using Set-UDElement. You need to specify an ID and a hashtable of properties to set on the component. All built-in components support Set-UDElement.

Removing a component

You can remove components from the page using Remove-UDElement. The component no longer appears on the page.

Adding a component

Add a child component to an existing parent component.

Clear a component

You can remove all child components from an existing component by using Clear-UDElement.

Reloading a component

Some components support reloading. You can trigger a reload of a component using Sync-UDElement.

Select a component

You can select a component with Select-UDElement.

PowerShell Host Integration

Dashboards integrate directly with the PowerShell host to provide features based on standard cmdlets.

Read-Host

Using the Read-Host cmdlet causes a dialog to show on the user's dashboard. The text entered is returned by the cmdlet.

Get-Credential

Using Get-Credential causes a dialog to show that accepts a username and password. A PSCredential object is returned from the cmdlet.

Write-Progress

Cmdlets that use the progress stream or Write-Progress result in a progress dialog. The popup shows the activity, percent completed, and current operation.

You can disable the Write-Progress integration by setting $ProgressPreference to SilentlyContinue.

Prompt for choice

You can use the $Host.UI.PromptForChoice function to display a multi-select dialog.

Write-Host

Write-Host within apps writes to the Log tab in the Admin Console for the app. To receive these log messages in your browser's developer-tools console, enable console logging in appsettings.json.

API

  • Get-UDElement

  • Set-UDElement

  • Clear-UDElement

  • Remove-UDElement

  • Sync-UDElement

  • Select-UDElement

See also

Last updated

Was this helpful?