> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/apps/custom-variable-scopes.md).

# Custom Scopes

Use cache, page, session, and UI scopes in PowerShell Universal apps to share state or interact with connected browser elements.

Universal Apps expose custom PowerShell providers for state that is scoped to an app, browser session, page, or connected UI element. Use the scope that matches the lifetime and visibility your app requires.

## UI scope

The `$UI:` scope provides direct access to an element in the connected browser by its ID. Read or set its state properties using PowerShell property syntax instead of `Get-UDElement` or `Set-UDElement`.

Use `$UI:` only in an app endpoint or interactive handler with an active browser connection. It cannot access elements from REST APIs, scheduled endpoints, or background work without a connected app client.

```powershell
New-UDTextbox -Id 'Name'

New-UDButton -Text 'Show name' -OnClick {
    Show-UDToast -Message $UI:Name.value
}
```

Set one or more properties on an element by assigning a property directly.

```powershell
$UI:Status.Text = 'Saved'
$UI:Status.Visible = $true
$UI:Status.Color = 'green'
```

The element ID follows `$UI:` and the property name maps to the component state property. For example, textboxes expose `value`, while a typography component exposes `Text`. Use the state properties supported by the component you are working with.

The following direct assignment is equivalent to calling `Set-UDElement` with a properties hashtable:

```powershell
$UI:Status.Text = 'Saved'

# Equivalent to:
Set-UDElement -Id 'Status' -Properties @{ Text = 'Saved' }
```

## Cache scope

Cache scope stores a variable that is available to every endpoint in the app. Use it for data that is shared by multiple controls or expensive to retrieve, such as Active Directory data or performance counters.

Like other PowerShell scopes, define a cache variable with a prefix and colon separator.

```powershell
$Cache:Computers = Get-ADComputer
```

Once assigned, the `$Cache:Computers` variable is available in any app endpoint.

```powershell
New-UDGauge -Value $Cache:Computers.Length -ValueMinimum 0 -ValueMaximum 100
```

## Page scope

Page scope stores variables for one browser tab or window. The state is removed when that tab or window closes; opening the app in another tab starts a separate page scope.

```powershell
New-UDForm -Content {
    New-UDTextbox -Id 'Name'
} -OnSubmit {
    $Page:Name = $EventData.Name
    Sync-UDElement -Id 'Name'
}

New-UDDynamic -Content {
    New-UDTypography $Page:Name
}
```

## Session scope

Session scope stores variables for one user's app session. A session begins when the user first visits the app and is identified by a browser cookie. Sessions have a 25-minute idle timeout.

```powershell
New-UDCheckbox -Label 'Show chart' -OnChange {
    $Session:ShowChart = $EventData
}
```

Once assigned, `$Session:ShowChart` is available in app event handlers. Session variables are not available in REST API endpoints or scheduled endpoints.

```powershell
New-UDGrid -Content {
    if ($Session:ShowChart) {
        $Data = @(
            [PSCustomObject]@{ Name = 'Available'; Value = 75 }
            [PSCustomObject]@{ Name = 'Used'; Value = 25 }
        )

        New-UDChartJS -Type 'doughnut' -Data $Data -DataProperty Value -LabelProperty Name
    }
}
```

Session variables are cleared when the session terminates.

### Storing credentials in session scope

Session scope is useful for credentials that must exist only for the duration of an active user session. This lets an app prompt for administrative credentials without persisting or sharing them.

```powershell
if (-not $Session:AdminCredentials) {
    $Session:AdminCredentials = Get-Credential -Message 'Enter administrator credentials'
}

New-UDButton -Text 'Check ACL' -OnClick {
    try {
        $result = Invoke-Command -Credential $Session:AdminCredentials -ScriptBlock {
            Get-Acl C:\SensitiveFolder
        }

        Show-UDToast -Message 'ACL retrieved successfully' -BackgroundColor Green
        Set-UDElement -Id 'aclOutput' -Content {
            $result | Out-String
        }
    }
    catch {
        Show-UDToast -Message "Failed: $($_.Exception.Message)" -BackgroundColor Red
    }
}

New-UDElement -Tag 'pre' -Id 'aclOutput'
```

Credentials in `$Session:AdminCredentials` are not persisted to disk or shared with other users, and are cleared when the session ends.

## See also

* [Devolutions Academy - User status/refresh user details](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/apps/custom-variable-scopes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.