newplus.md
1 # NewPlus Module 2 3 [Public overview - Microsoft Learn](https://learn.microsoft.com/en-us/windows/powertoys/newplus) 4 5 ## Quick Links 6 7 [All Issues](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3AProduct-New%2B)<br> 8 [Bugs](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3AIssue-Bug%20label%3AProduct-New%2B)<br> 9 [Pull Requests](https://github.com/microsoft/PowerToys/pulls?q=is%3Apr+is%3Aopen+label%3AProduct-New%2B+) 10 11 ## Overview 12 13 NewPlus is a PowerToys module that provides a context menu entry for creating new files directly from File Explorer. Unlike some other modules, NewPlus implements a different approach to context menu registration to avoid duplication issues in Windows 11. 14 15 ## Context Menu Implementation 16 17 NewPlus implements two separate context menu handlers: 18 19 1. **Windows 10 Handler** (`NewPlus.ShellExtension.win10.dll`) 20 - Implements "old-style" context menu handler for Windows 10 compatibility 21 - Not shown in Windows 11 (this is intentional and controlled by a condition in `QueryContextMenu`) 22 - Registered via registry keys 23 24 2. **Windows 11 Handler** (`NewPlus.ShellExtension.dll`) 25 - Implemented as a sparse MSIX package for Windows 11's modern context menu 26 - Only registered and used on Windows 11 27 28 This implementation differs from some other modules like ImageResizer which register both handlers on Windows 11, resulting in duplicate menu entries. NewPlus uses selective registration to provide a cleaner user experience, though it can occasionally lead to issues if the Windows 11 handler fails to register properly. 29 30 ## Project Structure 31 32 - **NewPlus.ShellExtension** - Windows 11 context menu handler implementation 33 - **NewPlus.ShellExtension.win10** - Windows 10 "old-style" context menu handler implementation 34 35 ## Debugging NewPlus Context Menu Handlers 36 37 ### Debugging the Windows 10 Handler 38 39 1. Update the registry to point to your debug build: 40 ``` 41 Windows Registry Editor Version 5.00 42 43 [HKEY_CLASSES_ROOT\CLSID\{<NewPlus-CLSID>}] 44 @="PowerToys NewPlus Extension" 45 46 [HKEY_CLASSES_ROOT\CLSID\{<NewPlus-CLSID>}\InprocServer32] 47 @="x:\GitHub\PowerToys\x64\Debug\PowerToys.NewPlusExt.win10.dll" 48 "ThreadingModel"="Apartment" 49 50 [HKEY_CURRENT_USER\Software\Classes\Directory\Background\shellex\ContextMenuHandlers\NewPlus] 51 @="{<NewPlus-CLSID>}" 52 ``` 53 54 2. Restart Explorer: 55 ``` 56 taskkill /f /im explorer.exe && start explorer.exe 57 ``` 58 59 3. Attach the debugger to explorer.exe 60 4. Add breakpoints in the NewPlus code 61 5. Right-click in File Explorer to trigger the context menu handler 62 63 ### Debugging the Windows 11 Handler 64 65 Debugging the Windows 11 handler requires signing the MSIX package: 66 67 1. Build PowerToys to get the MSIX packages 68 69 2. **Create certificate** (if you don't already have one): 70 ```powershell 71 New-SelfSignedCertificate -Subject "CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" ` 72 -KeyUsage DigitalSignature ` 73 -Type CodeSigningCert ` 74 -FriendlyName "PowerToys SelfCodeSigning" ` 75 -CertStoreLocation "Cert:\CurrentUser\My" 76 ``` 77 78 3. **Get the certificate thumbprint**: 79 ```powershell 80 $cert = Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object { $_.FriendlyName -like "*PowerToys*" } 81 $cert.Thumbprint 82 ``` 83 84 4. **Install the certificate in the Trusted Root** (requires admin Terminal): 85 ```powershell 86 Export-Certificate -Cert $cert -FilePath "$env:TEMP\PowerToysCodeSigning.cer" 87 Import-Certificate -FilePath "$env:TEMP\PowerToysCodeSigning.cer" -CertStoreLocation Cert:\LocalMachine\Root 88 ``` 89 90 Alternatively, you can manually install the certificate using the Certificate Import Wizard: 91 92  93  94  95  96 97 5. Sign the MSIX package: 98 ```powershell 99 SignTool sign /fd SHA256 /sha1 <THUMBPRINT> "x:\GitHub\PowerToys\x64\Debug\WinUI3Apps\NewPlusPackage.msix" 100 ``` 101 102 Note: SignTool might not be in your PATH, so you may need to specify the full path, e.g.: 103 ```powershell 104 & "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe" sign /fd SHA256 /sha1 <THUMBPRINT> "x:\GitHub\PowerToys\x64\Debug\WinUI3Apps\NewPlusPackage.msix" 105 ``` 106 107 6. Check if the NewPlus package is already installed and remove it if necessary: 108 ```powershell 109 Get-AppxPackage -Name Microsoft.PowerToys.NewPlusContextMenu 110 Remove-AppxPackage Microsoft.PowerToys.NewPlusContextMenu_<VERSION>_neutral__8wekyb3d8bbwe 111 ``` 112 113 7. Install the new signed MSIX package (optional if launching PowerToys settings first): 114 ```powershell 115 Add-AppxPackage -Path "x:\GitHub\PowerToys\x64\Debug\WinUI3Apps\NewPlusPackage.msix" -ExternalLocation "x:\GitHub\PowerToys\x64\Debug\WinUI3Apps" 116 ``` 117 118 Note: If you prefer, you can simply launch PowerToys settings and enable the NewPlus module, which will install the MSIX package for you. 119 120 8. Restart Explorer to ensure the new context menu handler is loaded: 121 ```powershell 122 taskkill /f /im explorer.exe && start explorer.exe 123 ``` 124 125 9. Run Visual Studio as administrator (optional) 126 127 10. Set breakpoints in the code (e.g., in [shell_context_menu.cpp#L45](/src/modules/NewPlus/NewShellExtensionContextMenu/shell_context_menu.cpp#L45)) 128 129 11. Right-click in File Explorer and attach the debugger to the `DllHost.exe` process (with NewPlus title) that loads when the context menu is invoked 130  131 132 12. Right-click again (quickly) after attaching the debugger to trigger the breakpoint 133 134 Note: The DllHost process loads the DLL only when the context menu is triggered and unloads after, making debugging challenging. For easier development, consider using logging or message boxes instead of breakpoints. 135 136 ## Common Issues 137 138 - If the Windows 11 context menu entry doesn't appear, it may be due to: 139 - The package not being properly registered 140 - Explorer not being restarted after registration 141 - A signature issue with the MSIX package 142 143 - For development and testing, using the Windows 10 handler can be easier since it doesn't require signing.