Overview

Windows Presentation Foundation (WPF) applications can leverage GPU acceleration in Citrix Virtual Apps and Desktops (CVAD) environments running Windows Multi-session OS. By enabling WPF rendering on the server’s GPU, this reduces CPU load and improves graphics performance for WPF applications.

This article provides a PowerShell script to configure the necessary registry settings and register specific WPF applications for GPU-based rendering in Citrix HDX environments.

Use this script if:

• You are running Citrix Virtual Apps and Desktops on a Multi-session OS (Windows Server).
• You want to enable WPF application rendering on the server GPU.
• You need to automate the registry configuration instead of manually setting values via regedit.

Important: Do not run this script on a Single-session OS (Windows 10/11 VDI) as it may cause connection issues or other unexpected behaviour.

Prerequisites

• Administrative privileges on the Virtual Delivery Agent (VDA).
• The system must be running Citrix Virtual Apps and Desktops.
• The target system must be a Multi-session OS.

Registry values

The following registry values will be configured under:
HKLM\Software\Citrix\CtxHook\AppInit_DLLs\Graphics Helper

For each WPF application, a sub-key must be created with the executable name:
HKLM\Software\Citrix\CtxHook\AppInit_DLLs\Graphics Helper\mywpfapp.exe

How to Use the Script

• Open PowerShell as Administrator.
  Execute the script:
  .\Enable-WPF-HDX.ps1
• Enter the WPF application path or name when prompted. Example inputs:
  • Full Path: C:\Program Files\MyApp\myapplication.exe
  • Executable Only: myapplication.exe

Script Actions

When executed, the script:

• Checks if the system is a Multi-session VDA (exits if not).
• Ensures the "Graphics Helper" registry key exists.
• Validates and configures the required registry values.
• Extracts and registers the WPF application under the registry.
• Prompts the user to reboot the server for the changes to take effect.

Reboot the Server

For the changes to take effect, restart the VDA after running the script.

Script

# Define the registry paths
$graphicsHelperPath = "HKLM:\SOFTWARE\Citrix\CtxHook\AppInit_DLLs\Graphics Helper"
$requiredSettings = @{ 
    "AdapterHandle" = 0x00000001
    "DevicePath" = 0x00000001
    "Flag" = 0x00000412
    "WPF" = 0x00000001
}

# Function to check if the system is a VDA and Multi-session OS
function Test-VdaMultiSession {
    $vdaKey = "HKLM:\SOFTWARE\Citrix\VirtualDesktopAgent"
    $multiSessionKey = "HKLM:\SYSTEM\CurrentControlSet\Control\Terminal Server\TSAppCompat"
    
    if (Test-Path $vdaKey) {
        $isMultiSession = (Get-ItemProperty -Path $multiSessionKey -Name "TSAppCompat" -ErrorAction SilentlyContinue).TSAppCompat
        if ($isMultiSession -eq 1) {
            return $true
        }
    }
    return $false
}

if (-not (Test-VdaMultiSession)) {
    Write-Host "This script should only be run on a Multi-session VDA. Exiting..." -ForegroundColor Red
    exit
}

# Ensure the Graphics Helper registry key exists
if (!(Test-Path $graphicsHelperPath)) {
    New-Item -Path $graphicsHelperPath -Force | Out-Null
    Write-Host "Created Graphics Helper registry key." -ForegroundColor Green
}

# Check and set required registry values
foreach ($key in $requiredSettings.Keys) {
    $existingValue = (Get-ItemProperty -Path $graphicsHelperPath -Name $key -ErrorAction SilentlyContinue).$key
    if ($existingValue -ne $requiredSettings[$key]) {
        Set-ItemProperty -Path $graphicsHelperPath -Name $key -Value $requiredSettings[$key] -Type DWord
        Write-Host "Set $key to $($requiredSettings[$key])" -ForegroundColor Green
    } else {
        Write-Host "$key is already set correctly." -ForegroundColor Yellow
    }
}

# Prompt the user for the application path or name
$appInput = Read-Host "Enter the application path or name (e.g., C:\\Path\\To\\App.exe or App.exe)"

# Extract only the executable name
$appName = [System.IO.Path]::GetFileName($appInput)

# Ensure the application name has .exe extension
if (![System.IO.Path]::HasExtension($appName) -or [System.IO.Path]::GetExtension($appName) -ne ".exe") {
    $appName = "$appName.exe"
}

if (-not $appName -or $appName -eq "") {
    Write-Host "Invalid input. Please enter a valid application name." -ForegroundColor Red
    exit
}

# Ensure the sub-key for the application exists
$appRegistryPath = "$graphicsHelperPath\\$appName"
if (!(Test-Path $appRegistryPath)) {
    New-Item -Path $appRegistryPath -Force | Out-Null
    Write-Host "Created registry key for $appName under Graphics Helper." -ForegroundColor Green
} else {
    Write-Host "$appName is already registered under Graphics Helper." -ForegroundColor Yellow
}

Write-Host "Reboot the server for the settings to take effect." -ForegroundColor Cyan

These software applications are provided to you as is with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities.NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.

For more information, refer to the official Citrix documentation: Windows Presentation Foundation (WPF) Rendering in HDX