HowTo: Create Common User Settings with PowerShell¶
This guide shows common User Settings created with the AppVentiX PowerShell module: drive mappings, printer mappings, environment variables, registry settings, files and folders, and global User State Roaming rules. Each example is a typical real-world requirement, from creating the setting to assigning it.
Overview¶
| User Setting | Command |
|---|---|
| Drive Mapping | New-AppVentiXDriveMappingUserSetting |
| Printer Mapping | New-AppVentiXPrinterMappingUserSetting |
| Environment Variables | New-AppVentiXEnvironmentVariableUserSetting |
| Registry Settings | New-AppVentiXRegistryUserSetting |
| Files and Folders | New-AppVentiXFilesAndFoldersUserSetting |
| Global User State Roaming | New-AppVentiXGlobalUserSetting |
| Assign to a user group | Set-AppVentiXUserSettingsAssignment |
| Put in a folder | Set-AppVentiXUserSettingFolder |
Every New-AppVentiX*UserSetting command returns an object with the Id of the new setting. Store it in a variable, you need it to assign the setting and to move it into a folder.
About the examples
Each example starts with a scenario to show when a setting is useful. Server names, shares, printers, groups, machine groups and paths are placeholders. Replace them with the values from your own environment, and only use the examples that fit your situation.
Prerequisites¶
- AppVentiX PowerShell module version 2026.1117.1700 or later
- A valid AppVentiX license
- Write access to the AppVentiX Configuration Store
- User Settings enabled in the Agent Settings of the machine groups
Import-Module AppVentiX
# Optional: select the site to work in, when you have more than one
Get-AppVentiXSite
Set-AppVentiXSite -Name 'Test'
Settings that apply to all types¶
| Parameter | Default | Purpose |
|---|---|---|
-MachineGroupFriendlyName |
All machine groups | Apply the setting only on machines in these machine groups. |
-ProcessAtLogin |
$true |
Apply at login. |
-ProcessAtRefresh |
$true |
Also apply when the user refreshes the workspace. Central View enables only login for new settings. |
-ProcessAtReconnectAndUnlock |
$false |
Also apply when the user reconnects or unlocks the session. |
-ExecutionOrder |
100 |
Lower numbers run first. Same default as Central View. |
-Description |
empty | Free text shown in Central View. |
Warning
Check machine group names with Get-AppVentiXMachineGroup | Select-Object FriendlyName before you use -MachineGroupFriendlyName. A name that does not exist is skipped without a warning. When none of the names exist, the setting has no machine group and is not applied anywhere.
Reuse common parameters with splatting¶
When you create several settings with the same options, put those options in a hashtable once and pass it to each command with @ (splatting). You can combine a splatted hashtable with normal parameters.
Scenario: all settings for developers should only apply on the Developer Desktops machine group, only at login (like Central View), and run after the settings with the default Execution Order (100):
$developerDefaults = @{
MachineGroupFriendlyName = 'Developer Desktops'
ProcessAtRefresh = $false
ExecutionOrder = 200
}
$sourceDrive = New-AppVentiXDriveMappingUserSetting @developerDefaults -FriendlyName 'S: Source' `
-DriveLetter 'S:' -NetworkPath '\\fileserver.domain.local\Source$' -Label 'Source'
$sourceVariable = New-AppVentiXEnvironmentVariableUserSetting @developerDefaults -FriendlyName 'SOURCE_ROOT' `
-EnvironmentVariables @(@{ Name = 'SOURCE_ROOT'; Value = 'S:\' })
Changing the machine group or Execution Order for all of them is now a change in one place.
Drive mappings¶
Map a department share¶
Scenario: a project team needs its share on P:. Only members of the Projects group should get the drive.
$projects = New-AppVentiXDriveMappingUserSetting -FriendlyName 'P: Projects' `
-DriveLetter 'P:' -NetworkPath '\\fileserver.domain.local\Projects$' -Label 'Projects'
Set-AppVentiXUserSettingsAssignment -Id $projects.Id -ADGroup 'Projects' -Type DriveMapping
Set-AppVentiXUserSettingFolder -FolderName 'Drives' -Id $projects.Id
Drive mappings are tracked. When you later unassign the setting, the drive is removed from the users automatically. See Tracked User Settings.
Hide a local drive¶
Scenario: the session hosts have a D: drive with a temporary or data disk that users should not browse.
$hideD = New-AppVentiXDriveMappingUserSetting -FriendlyName 'Hide D:' -DriveLetter 'D:' -HideDrive $true
Set-AppVentiXUserSettingsAssignment -Id $hideD.Id -ADGroup 'Everyone' -Type DriveMapping
Only set a label¶
Scenario: the D: drive should stay visible, but with a clearer name. To set a label without mapping anything, use -DoNotExecute:
$labelD = New-AppVentiXDriveMappingUserSetting -FriendlyName 'Label D: Local Data' `
-DriveLetter 'D:' -Label 'Local Data' -DoNotExecute $true
Printer mappings¶
Default printer per location¶
Scenario: the machines on the second floor of an office are in a machine group named Office Floor 2. Whoever logs on to one of those machines should get the printer on that floor as default printer.
$printer = @{
FriendlyName = 'Printer Floor 2'
PrinterPath = '\\printserver.domain.local\Floor2-MFP'
SetAsDefault = $true
MachineGroupFriendlyName = 'Office Floor 2'
}
$floor2 = New-AppVentiXPrinterMappingUserSetting @printer
Set-AppVentiXUserSettingsAssignment -Id $floor2.Id -ADGroup 'Everyone' -Type PrinterMapping
Set-AppVentiXUserSettingFolder -FolderName 'Printers' -Id $floor2.Id
To connect a printer only when a specific application is started, link the printer mapping to the shortcut instead of assigning it. See Configure Prelaunch and Postlaunch Settings with PowerShell.
Environment variables¶
Each variable takes a Name and Value. Optional are AppendToExisting (default $false) and Scope, User (default) or System.
Add a tools folder to the user PATH¶
Scenario: command line tools are installed in C:\Tools and users should be able to run them from any folder.
$toolsPath = New-AppVentiXEnvironmentVariableUserSetting -FriendlyName 'PATH: Company tools' `
-EnvironmentVariables @(
@{ Name = 'Path'; Value = 'C:\Tools'; AppendToExisting = $true }
)
Tip
Test an appended variable on one machine first ($env:Path -split ';' in a new session) to confirm the result is what you expect before you assign it to everyone.
Several variables in one setting¶
Scenario: developers need JAVA_HOME on their machines, and a user variable that points their scripts to a shared source location:
$devVariables = New-AppVentiXEnvironmentVariableUserSetting -FriendlyName 'Developer variables' `
-MachineGroupFriendlyName 'Developer Desktops' `
-EnvironmentVariables @(
@{ Name = 'JAVA_HOME'; Value = 'C:\Program Files\Eclipse Adoptium\jdk-21'; Scope = 'System' }
@{ Name = 'SOURCE_ROOT'; Value = '\\fileserver.domain.local\Source$' }
)
Set-AppVentiXUserSettingsAssignment -Id $devVariables.Id -ADGroup 'Developers' -Type EnvironmentVariables
Registry settings¶
Each entry needs a RootKey (HKCU or HKLM) and a KeyPath. Optional are ValueName, ValueData, ValueType and Action.
ValueType |
Registry type |
|---|---|
String |
REG_SZ (default) |
ExpandString |
REG_EXPAND_SZ |
DWord |
REG_DWORD |
MultiString |
REG_MULTI_SZ |
Binary |
REG_BINARY |
Action is Set (default) to create or change a value, or Remove to delete it. With Remove and no ValueName the whole key is removed.
Note
Central View also supports REG_QWORD. Create those entries in Central View.
Show file extensions in File Explorer¶
Scenario: users should see file extensions in File Explorer, so they can tell a .pdf from a .pdf.exe.
$fileExtensions = New-AppVentiXRegistryUserSetting -FriendlyName 'Explorer: show file extensions' `
-RegistryEntries @(
@{ RootKey = 'HKCU'; KeyPath = 'Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced'; ValueName = 'HideFileExt'; ValueData = '0'; ValueType = 'DWord' }
)
Set-AppVentiXUserSettingsAssignment -Id $fileExtensions.Id -ADGroup 'Everyone' -Type RegistrySettings
Stop OneDrive from starting at login¶
Scenario: OneDrive is not used on the shared session hosts, so it should not start at login. Remove its autostart entry for the user:
$noOneDrive = New-AppVentiXRegistryUserSetting -FriendlyName 'OneDrive: no autostart' `
-RegistryEntries @(
@{ RootKey = 'HKCU'; KeyPath = 'Software\Microsoft\Windows\CurrentVersion\Run'; ValueName = 'OneDrive'; Action = 'Remove' }
)
Files and folders¶
A Files and Folders User Setting copies or deletes one or more files or folders. Each operation has an Action:
| Action | Keys |
|---|---|
Copy |
SourcePath and DestinationPath (file or folder). Optional AlwaysOverwrite and OnlyNewer, the Overwrite and Only Newer options in Central View. By default only OnlyNewer is set. |
Delete |
Path, the file or folder to delete. |
Use -RunOnce $true to run the operations only once per user. As a best practice, keep Copy and Delete actions in separate User Settings.
Distribute Word templates¶
Scenario: the organization maintains its Word templates on a file share. Users should get new and updated templates, without a full copy at every login.
$templates = New-AppVentiXFilesAndFoldersUserSetting -FriendlyName 'Word templates' `
-FileOperations @(
@{ Action = 'Copy'; SourcePath = '\\fileserver.domain.local\Templates$\Word'; DestinationPath = '%APPDATA%\Microsoft\Templates' }
)
Set-AppVentiXUserSettingsAssignment -Id $templates.Id -ADGroup 'Everyone' -Type ManageFiles
The copy uses the default Only Newer option, so only files that changed on the share are copied again.
Provide a starting configuration once¶
Scenario: new users should start with the default settings file of an application, but they may change it afterwards. The file is copied once and never overwritten again for that user.
$appDefaults = New-AppVentiXFilesAndFoldersUserSetting -FriendlyName 'App defaults (once)' -RunOnce $true `
-FileOperations @(
@{ Action = 'Copy'; SourcePath = '\\fileserver.domain.local\Defaults$\App\settings.json'; DestinationPath = '%APPDATA%\App\settings.json' }
)
Clean up after a migration¶
Scenario: an application was replaced, and its old data folder in the user profile only takes up space. The folder is removed once per user.
$cleanup = New-AppVentiXFilesAndFoldersUserSetting -FriendlyName 'Remove OldApp data' -RunOnce $true `
-FileOperations @(
@{ Action = 'Delete'; Path = '%LOCALAPPDATA%\OldApp' }
)
Set-AppVentiXUserSettingsAssignment -Id $cleanup.Id -ADGroup 'Everyone' -Type ManageFiles
To clean up after a specific application closes, link a Files and Folders setting to its shortcut as postlaunch setting. See Configure Prelaunch and Postlaunch Settings with PowerShell.
Global User State Roaming rules¶
Roaming rules can be part of a Shortcuts User Setting, see Create Managed Shortcuts with PowerShell. Global rules are not tied to a shortcut, which suits tools that are part of the base image.
Scenario: Windows Terminal is part of the base image of non-persistent machines, and users want to keep their terminal settings between sessions:
New-AppVentiXGlobalUserSetting -Type UserStateRoaming -Settings @{
Name = 'Windows Terminal'
Description = 'Roam Windows Terminal settings'
CaptureRules = @(
@{ Kind = 'Folder'; Path = '%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState' }
)
}
Assignments¶
Set-AppVentiXUserSettingsAssignment assigns a setting to an Active Directory group or to Everyone. The -Type must match the type of the setting:
| User Setting | -Type |
|---|---|
| Drive Mapping | DriveMapping |
| Printer Mapping | PrinterMapping |
| Environment Variables | EnvironmentVariables |
| Registry Settings | RegistrySettings |
| Shortcuts | Shortcuts |
| Group Policy | GroupPolicy |
| External Tasks | ExternalTasks |
| Files and Folders | ManageFiles |
The domain is added to the group name when you leave it out. Entra ID groups can be assigned in Central View. A setting that is linked to a shortcut as prelaunch or postlaunch setting cannot be assigned to user groups.
Combine settings with Execution Order¶
Settings run from the lowest to the highest Execution Order. Give settings that others depend on a lower number.
Scenario: a reporting application writes its output to the path in the REPORT_OUTPUT variable, which points to a mapped drive. The drive is mapped first, then the variable is set:
$dataDrive = New-AppVentiXDriveMappingUserSetting -FriendlyName 'R: Reports' `
-DriveLetter 'R:' -NetworkPath '\\fileserver.domain.local\Reports$' -ExecutionOrder 10
$reportVariable = New-AppVentiXEnvironmentVariableUserSetting -FriendlyName 'REPORT_OUTPUT' `
-EnvironmentVariables @(@{ Name = 'REPORT_OUTPUT'; Value = 'R:\Output' }) -ExecutionOrder 20
Find and review settings¶
# All User Settings
Get-AppVentiXUserSettings | Select-Object FriendlyName, Type, Id
# One or more types
Get-AppVentiXUserSettings -Type DriveMapping, PrinterMapping
# By name, wildcards are allowed
Get-AppVentiXUserSettings -FriendlyName 'P: Projects'
Get-AppVentiXUserSettings -FriendlyName 'Printer*'
# By Id
Get-AppVentiXUserSettings -Id $projects.Id
# Only drive mappings, with their details
Get-AppVentiXUserSettings -Type DriveMapping | ForEach-Object {
[PSCustomObject]@{
Name = $_.FriendlyName
Drive = $_.Settings.DriveMapping.DriveLetter
NetworkPath = $_.Settings.DriveMapping.NetworkPath
}
}
Tip
-Type and -Id only read the matching files, which is noticeably faster with many User Settings, especially on an Azure Blob Configuration Store. Combine -Type with -FriendlyName when you know the type.