Universal Dashboard exposes two custom variable scopes using custom providers. These providers allow you to store your variables in scopes that make sense for a web application. The cache scope is used to store variables that can be used within any endpoint inside a dashboard. The session scope is used to store variables that can be used for a single user's session of the dashboard.
Cache scope is used to store a variable that will be available in any endpoint. Cache scope is useful for storing data that make be shown in more than one control or may be time consuming to look up. This could be helpful for querying machine performance counters, Active Directory or Azure.
Just like any other scope, cache variables are defined with a prefix and a colon separator.
Once assigned, the $Cache:Computer variable is available within any endpoint.
Session scope is used to store a variable per session. A session is established when a user's browser first visit a dashboard. A cookie is stored in the user's browser that dictates that it is part of the session. Sessions have an idle timeout of 25 minutes.
Just like any other scope, cache variables are defined with a prefix and a colon separator.
Once assigned, the $Session:ShowChart variable is available in dashboard endpoints. Session variables are not available in REST API endpoints or scheduled endpoints.
Once a session is terminated, the session variables are cleared.
We recommend installing the PowerShell Universal Visual Studio Code extension. Read more about dashboard development here.
When building dashboards, you will pick one of the two built in dashboard frameworks. The components that are available for that framework will different. You can find examples of each of the frameworks at the below links.
All the documentation on this page will be referencing the v3 framework.
Dashboards can contain one or more pages. The simplest dashboard will contain a single page with some content. You can call any PowerShell cmdlet that is available on your machine to populate your dashboard.
Here's an example of simple dashboard that displays some text.
Components are the individual widgets that you can place on you dashboard. There are components for displaying data, taking user input, adding text and images and more. Components can be downloaded as PowerShell modules and added to your dashboard.
Examples of all of the components can be found on GitHub.
Components are be caused using the standard verb-name syntax for any PowerShell cmdlet.
You can specify multiple pages within a dashboard. Each page defines a route. As for v3, all pages are dynamic. PowerShell will execute on each page load to render the new page. Since UD is a single page application, the web browser does not need to refresh the entire web page when navigating between the different dashboard pages.
There are several built-in variables that are available in dashboards.
Name
Description
Type
$User
The user name of the logged in user. $Null if authentication is disabled.
String
$Roles
The roles that the user has been granted. $Null if authentication is disabled.
String[]
$RemoteIpAddress
The remote IP address of the connected user. Only available in the nightly build
String
$RmotePort
The remote port of the connected user. Only available in the nightly build
Int
When building a dashboard you will likely run into issues with cmdlet calls or syntax. Dashboards will auto reload as you make changes to the dashboard files. If a dashboard fails to start, you can navigate to the admin page, click Dashboards and click the Info button next to your dashboard.
The Log tab will show all the logging coming from the PowerShell execution from within in your dashboard. This should allow you to easily see errors and warnings coming from your dashboard.
You can use Write-Debug to add additional log messages to your dashboard. To enable debug logging, you will have to set the $DebugPreference variable at the top of your dashboard script.
Dashboards are individual websites created with Universal Dashboard. You can define settings for a dashboard and start and stop the dashboard from within the Universal administrative interface.
Dashboards can be added to Universal using the Add Dashboard button from the Dashboard / Dashboards page.
Name
Name is displayed throughout the UI and returned from the Universal cmdlets.
Base URL
The base URL is the URL that you will access to view this dashboard. This URL needs to be unique within this instance. You can specify the / root URL if you wish. You will have to visit /admin to login to the administrative page if you set the dashboard to the root URL.
File Name
The full file name to the dashboard file. This file needs to return a dashboard using New-UDDashboard.
Framework
The framework that the dashboard was designed for. By default, Universal Dashboard v2.9 and v3.0 are supported.
Environment
The environment to run the dashboard within.
Auth
Enables authentication for the dashboard.
Role
Defines the role that is required to access the dashboard.
AutoStart
Determines whether the dashboard should start (or restart) when the server starts or changes are made to the dashboard files.
Similar to jobs, dashboards run in separate PowerShell processes. You can start and stop a dashboard process by clicking the Start or Stop button from the Dashboards page.
You can view diagnostic information for a dashboard by clicking the Info button on the Dashboards page. This will show your start information for the dashboard as well as any error that were encountered when starting the dashboard.
You can view the dashboard by clicking the View button. This will take you to the Base URL for the dashboard.
On the dashboard information page, click on the Console tab to view the UD console. The console allows you to run scripts from within the UD runspace so you can better debug the state of your script. You can evaluate variables and run commands that are available to the dashboard. You will be running in the context of your user in regards to the runspace but the process will be running as the service account user.
Custom component libraries provide additional components to dashboards. There are three built in component libraries that are not automatically imported into your dashboards.
UniversalDashboard.Charts
UniversalDashboard.Map
UniversalDashboard.CodeEditor
To add these components to your dashboard, you can use the dashboard UI.
Click the info button on the dashboard page.
Next, click the components button in the top right of your dashboard.
Finally, check the component library you'd like added to your dashboard.
You can also add component libraries directly to your dashboards.ps1 script within the .unversal folder or when using single-file hosting and configuration.
Persistent runspaces allow you to maintain runspace state within your dashboard endpoints. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent calls.
By default, runspaces will be reset after each execution. This will cause variables, modules and functions defined during the execution of an endpoint.
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.
You will need to ensure that the environment is used by the dashboard.
You can automatically grant app tokens to users that visit dashboards. This is useful if you want to invoke the management API for PowerShell Universal from within a dashboard. Your dashboard will need to have authentication enabled and you will have to use the -GrantAppToken switch parameter on New-PSUDashboard.
From within your dashboard, you can now invoke the management API without having to worry about app token management. The API will be invoked in the context of the user that is visiting the dashboard.
PowerShell Universal Dashboard v2.9 is a PowerShell module that allows you to create dashboard with PowerShell script. It is the predecessor to PowerShell Universal. The technology the enabled UD has been migrated into PowerShell Universal. You should be able to run the same PowerShell scripts in PowerShell Universal that you would in Universal Dashboard with some minor modifications.
In Universal, all you need to do is return the result of New-UDDashboard from your script. There is no need to call Start-UDDashboard. The configuration of the webserver is taken place using the PSU appsetting.json file.
This cmdlet has been removed from Universal Dashboard. There is no longer a need to call it.
You do not need to pass the value of a scheduled endpoint to anything. You can just call New-UDEndpoint with a endpoint schedule and it will automatically be registered with PSU.
Authentication and authorization are now handled by PSU and there is no need to configure UD login pages. Authentication and authorization are configured with the PSU appsettings.json file. Dashboard's themselves can be either authenticated or not authenticated. A license is required to enable authenticated dashboards.
To enable role-based access controls, you can assign roles to pages and use the automatic $Roles variable to check which roles the user is a part of. The $User variable will provide the name of the user.
Authorizations policies in Universal work very similar to the ones in Universal Dashboard, you will define them using the New-PSURole cmdlet. When you define the role, you have the option to define a policy that will assign that role automatically to a user.
For example, let's adjust a claims policy from Universal Dashboard for Universal.
Universal Dashboard
Universal
Much like the Get-UDAuthorizationPolicy cmdlet in Universal Dashboard, you also have access to the assigned roles for users in Universal. Simply check the $Roles variable to see which roles the user has.
This section contains migration information for upgrading from UDv2 to UDv3. They are vastly different frameworks and will require rewriting your dashboard. Many of the concepts are the same.
Pages have a different behavior in v3. All pages are dynamic pages. This means that you don't have to worry about whether a page will be generated at run time or doing start up. Pages are always generated during runtime.
If you have a page such as this one:
You can convert it to a v3 page by changing the syntax to:
Rather than having two cmdlets for tables (New-UDTable and New-UDGrid). The New-UDTable in v3 provides the ability to display data in a table, filter, page, and sort it. It supports both client and server-side processing.
Unlike in v3, components do not have -Endpoint and -Content parameters. Each component will instead simply have a -Content parameter. To achieve dynamic sections of a page, you can instead use the New-UDDynamic cmdlet. This cmdlets let you define an entire section of a page as dynamic. It also provides auto refresh functionality so you can refresh sections of a page all at once.
New-UDGrid allows you to define a grid layout using the Material UI library. You use this single cmdlet to define rows and columns within your dashboard.
New-UDInput has been replaced by New-UDForm. The UDForm component allows far more configuration that UDInput did. You will use the standard controls like UDTextbox, UDCheckbox, and UDSelect instead of New-UDInputField. This means that there are a single set of input cmdlets to use for UD.
Instead of using New-UDSideNav, you will now use a combination of New-UDAppbar and New-UDDrawer. When New-UDAppBar is used with the default position, it will overlay the AppBar at the top of the page. You can then specify a drawer to customize the navigation experience within your dashboard.
The Nivo and sparklines controls are now open source and on the Universal Dashboard repository. You can now use them without purchasing a license.
The map control is also open source and on GitHub.
To learn more about APIs, .
to learn more about Published Folders in PowerShell Universal.
You can view examples of the .
You can view examples of the .
All of the input control examples can be .
You can see examples of how to do .
For more examples of Nivo and sparklines controls, .
You can find examples .
