mir/PowerToys
2
0
Fork 0
mirror of https://github.com/microsoft/PowerToys synced 2025-08-22 01:58:04 +00:00
Code Issues Actions 17 Packages Projects Releases Wiki Activity
PowerToys/doc/devdocs/common/context-menus.md
Gleb Khmyznikov 725535b760
Some checks failed
Spell checking / Check Spelling (push) Has been cancelled
Details
Spell checking / Report (Push) (push) Has been cancelled
Details
Spell checking / Report (PR) (push) Has been cancelled
Details
Spell checking / Update PR (push) Has been cancelled
Details
[DevDocs] More content and restructure (#40165) 
## Summary of the Pull Request
Accumulated information from internal transition about the modules
development, and reworked it to be added in dev docs. Also the dev docs
intself was restructured to be more organized. New pages was
verified by transition team.

## PR Checklist
- [x] **Dev docs:** Added/updated

---------

Co-authored-by: Zhaopeng Wang (from Dev Box) <zhaopengwang@microsoft.com>
Co-authored-by: Hao Liu <liuhao3418@gmail.com>
Co-authored-by: Peiyao Zhao <105847726+zhaopy536@users.noreply.github.com>
Co-authored-by: Mengyuan <162882040+chenmy77@users.noreply.github.com>
Co-authored-by: zhaopeng wang <33367956+wang563681252@users.noreply.github.com>
Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com>
2025-07-01 14:27:34 +02:00

4.0 KiB
Raw Permalink Blame History

PowerToys Context Menu Handlers

This document describes how context menu handlers are implemented in PowerToys, covering both Windows 10 and Windows 11 approaches.

Context Menu Implementation Types

PowerToys implements two types of context menu handlers:

  1. Old-Style Context Menu Handlers

    • Used for Windows 10 compatibility
    • Registered via registry entries
    • Implemented as COM objects exposing the IContextMenu interface
    • Registered for specific file extensions

  2. Windows 11 Context Menu Handlers

    • Implemented as sparse MSIX packages
    • Exposing the IExplorerCommand interface
    • Located in PowerToys\x64\Debug\modules\<module>\<module>.msix
    • Registered for all file types and filtered in code
    • Requires signing to be installed

Context Menu Handler Registration Approaches

PowerToys modules use two different approaches for registering context menu handlers:

1. Dual Registration (e.g., ImageResizer, PowerRename)

  • Both old-style and Windows 11 context menu handlers are registered
  • Results in duplicate entries in Windows 11's expanded context menu
  • Ensures functionality even if Windows 11 handler fails to appear
  • Old-style handlers appear in the "Show more options" expanded menu

2. Selective Registration (e.g., NewPlus)

  • Windows 10: Uses old-style context menu handler
  • Windows 11: Uses new MSIX-based context menu handler
  • Avoids duplicates but can cause issues if Windows 11 handler fails to register

Windows 11 Context Menu Handler Implementation

Package Registration

  • MSIX packages are defined in AppManifest.xml in each context menu project
  • Registration happens in DllMain of the module interface DLL when the module is enabled
  • Explorer restart may be required after registration for changes to take effect
  • Registration can be verified with Get-AppxPackage PowerShell command: 
    Get-AppxPackage -Name *PowerToys*

Technical Implementation

  • Handlers implement the IExplorerCommand interface
  • Key methods:
    • GetState: Determines visibility based on file type
    • Invoke: Handles the action when the menu item is clicked
    • GetTitle: Provides the text to display in the context menu
  • For selective filtering (showing only for certain file types), the logic is implemented in the GetState method

Example Implementation Flow

  1. Build generates an MSIX package from the context menu project
  2. When the module is enabled, PowerToys installs the package using PackageManager.AddPackageAsync
  3. The package references the DLL that implements the actual context menu handler
  4. When the user right-clicks, Explorer loads the DLL and calls into its methods

Debugging Context Menu Handlers

Debugging Old-Style (Windows 10) Handlers

  1. Update the registry to point to your debug build
  2. Restart Explorer
  3. Attach the debugger to explorer.exe
  4. Set breakpoints and test by right-clicking in File Explorer

Debugging Windows 11 Handlers

  1. Build PowerToys to get the MSIX packages
  2. Sign the MSIX package with a self-signed certificate
  3. Replace files in the PowerToys installation directory
  4. Use PowerToys to install the package
  5. Restart Explorer
  6. Run Visual Studio as administrator
  7. Set breakpoints in relevant code
  8. Attach to DllHost.exe process when context menu is triggered

Debugging Challenges

  • Windows 11 handlers require signing and reinstalling for each code change
  • DllHost loads the DLL only when context menu is triggered and unloads after
  • For efficient development, use logging or message boxes instead of breakpoints
  • Consider debugging the Windows 10 handler by removing OS version checks

Common Issues

  • Context menu entries not showing in Windows 11
    • Usually due to package not being removed/updated properly on PowerToys update
    • Fix: Uninstall and reinstall the package or restart Explorer
  • Registering packages requires signing
    • For local testing, create and install a signing certificate
  • Duplicate entries in Windows 11 context menu
    • By design for some modules to ensure availability if Windows 11 handler fails