PowerToys/doc/devdocs/processes/gpo.md

PowerToys GPO (Group Policy Objects) Implementation

Group Policy Objects (GPOs) allow system administrators to control PowerToys settings across an organization. This document describes how GPOs are implemented in PowerToys.

GPO Overview

GPO policies allow system administrators to control PowerToys settings. PowerToys ships GPO files as part of the release zip, not installed directly.

GPO File Structure

ADMX File

• Contains policy definitions
• Defines which versions support each policy
• Sets up folder structure
• Defines each policy with:
  • Name
  • Class (user scope or machine scope)
  • Description
  • Registry location where policy is stored
  • Enabled/disabled values

ADML File

• Contains localized strings for the ADMX file
• Contains revision number that must be updated when changes are made
• Stores strings for:
  • Folder names
  • Version definitions
  • Policy descriptions and titles
• Currently only ships English US version (no localization story yet)

Installation Process

• Files need to be placed in: C:\Windows\PolicyDefinitions\
• ADMX file goes in the root folder
• ADML file goes in the language subfolder (e.g., en-US)
• After installation, policies appear in the Group Policy Editor (gpedit.msc)

Registry Implementation

• Policies are stored as registry values
• Location: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys or HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys
• Machine scope takes precedence over user scope
• Policy states:
  • Enabled: Registry value set to 1
  • Disabled: Registry value set to 0
  • Not Configured: Registry value does not exist

Code Integration

Common Files

• Policy keys defined in common\utils\GPO.h
• Contains functions to read registry values and get configured values
• WinRT C++ adapter created for C# applications to access GPO settings

WPF Applications

• WPF applications cannot directly load WinRT C++ projects
• Additional library created to allow WPF applications to access GPO values

Module Interface

• Each module must implement policy checking in its interface
• Runner checks this to determine if module should be started or not

UI Implementation

• When a policy disables a utility:
  • UI is locked (cannot be enabled)
  • Settings page shows a lock icon
  • Dashboard hides the module button
  • If user tries to start the executable directly, it exits and logs a message

Types of GPO Policies

Basic Module Enable/Disable Policy

• Most common type
• Controls whether a module can be enabled or disabled
• Shared description text for these policies

Configuration Policies

• Example: Run at startup setting
• Controls specific settings rather than enabling/disabling modules
• Custom description text explaining what happens when enabled/disabled/not configured

Machine-Scope Only Policies

• Example: Mouse Without Borders service mode
• Only makes sense at machine level (not user level)
• Restricts functionality that requires elevated permissions

Steps to Add a New Policy

1. Update ADMX file:

   • Increase revision number
   • Add supported version definition
   • Define the policy with registry location

2. Update ADML file:

   • Increase revision number
   • Add strings for version, title, description

3. Update code:

   • Add to GPO.h
   • Add to GPO wrapper for C# access
   • Update module interface
   • Modify settings UI to show lock when policy applied
   • Add checks in executable to prevent direct launching
   • Update dashboard helper to respect policy

4. Add to bug report tool to capture policy state

Update-Related GPO Settings

• disable automatic update download - Prevents automatic downloading
• disable new update toast - Controls if toast notifications are shown
• suspend new update toast - Suspends toast notifications for 2 minor releases

Testing GPO Settings

To test GPO settings locally:

1. Run regedit as administrator
2. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys
3. Create a new DWORD value with the name of the policy
4. Set the value to 0 (disabled) or 1 (enabled)
5. Restart PowerToys to see the effect

For user-scope policies, use HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys instead.