Documentation walking through important steps for writing a New PowerToy #44242

Jaylyn-Barbee · 2025-12-12T15:37:53Z

Summary of the Pull Request

This new document serves as a handy guide, packed with key details and helpful tips to keep in mind when creating a new PowerToy.

doc/devdocs/development/new-powertoy.md

@@ -0,0 +1,258 @@
+# 🧭 Creating a New PowerToy: End-to-End Developer Guide
+
+First of all, thank you for wanting to contribute to PowerToys. The work we do would not be possible with out the support of community supporters like you.


doc/devdocs/development/new-powertoy.md

+
+### Writing your Module Interface
+Begin by setting up the [PowerToy module template project](https://github.com/microsoft/PowerToys/tree/main/tools/project_template). This will generate boilerplate for you to begin your new module. Below I will go through the key headers in the Module Interface (dllmain.cpp) and explain their purpose:
+1. This is where will will define all of our module settings. These can be any time from strings, bools, ints, and even custom Enums.


doc/devdocs/development/new-powertoy.md

+    // Can include the enabled variable, logic for event handlers, or hotkeys.
+  public:
+    // the public members of the class
+    // Will include the constructor and intialization logic.


doc/devdocs/development/new-powertoy.md

+}
+```
+
+4. `init_settings()` initializes the settings for the interface. Will either pull from exisiting settings.json or use defaults.


doc/devdocs/development/new-powertoy.md

+
+9. Hotkey functions control the status of the hotkey.
+```c++
+// takes the hotkey from settings into a format the interface can understand


doc/devdocs/development/new-powertoy.md

+
+---
+
+### Gotchas:


doc/devdocs/development/new-powertoy.md

+4. To set breakpoints in your service, press `Ctrl + Alt + P` and search for your service to attach to the runner.
+5. Use logs to document changes. The logs live at `%LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogs` and `%LOCALAPPDATA%\Microsoft\PowerToys\Module\Service\<version>` for the specific module.
+
+> **Gotcha:** PowerToys caches `.nuget` artifacts aggressively. Use `git clean -xfd` when builds behave unexpectedly.


doc/devdocs/development/new-powertoy.md

+### Add Your Module to Installer
+
+1. Install [`WixToolset.Heat`](https://www.nuget.org/packages/WixToolset.Heat/) for Wix5 via nuget
+2. Inside `installer\PowerrToysInstallerVNext` add a new file for your module: `Module.wxs`


doc/devdocs/development/new-powertoy.md

+```bash
+# Module Name
+Generate-FileList -fileDepsJson "" -fileListName <Module>Files -wxsFilePath $PSScriptRoot\<Module>.wxs -depsPath "$PSScriptRoot..\..\..\$platform\Release\<ModuleServiceName>"
+Generate-FileComponents -fileListName "<Module>Files" -wxsFilePath $PSScriptRoot\<Module>.wxs -regroot $registryroot


doc/devdocs/development/new-powertoy.md

+```bash
+# Module Name
+Generate-FileList -fileDepsJson "" -fileListName <Module>Files -wxsFilePath $PSScriptRoot\<Module>.wxs -depsPath "$PSScriptRoot..\..\..\$platform\Release\<ModuleServiceName>"
+Generate-FileComponents -fileListName "<Module>Files" -wxsFilePath $PSScriptRoot\<Module>.wxs -regroot $registryroot


github-actions · 2025-12-12T15:42:16Z

@check-spelling-bot Report

🔴 Please review

See the 📂 files view, the 📜action log, or 📝 job summary for details.

Unrecognized words (6)

exisiting
gotcha
intialization
Powerr
registryroot
regroot

These words are not needed and should be removed

CLITo CVS Notavailable toolgood Uninitializes

To accept these unrecognized words as correct and remove the previously acknowledged and now absent words, you could run the following commands

... in a clone of the git@github.com:Jaylyn-Barbee/PowerToys.git repository
on the jay/new-powertoys-doc branch (ℹ️ how do I use this?):

curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/c635c2f3f714eec2fcf27b643a1919b9a811ef2e/apply.pl' |
perl - 'https://github.com/microsoft/PowerToys/actions/runs/20171785434/attempts/1' &&
git commit -m 'Update check-spelling metadata'

Forbidden patterns 🙅 (3)

In order to address this, you could change the content to not match the forbidden patterns (comments before forbidden patterns may help explain why they're forbidden), add patterns for acceptable instances, or adjust the forbidden patterns themselves.

These forbidden patterns matched content:

Articles generally shouldn't be used without a noun and a verb

Perhaps you're missing a verb between the noun and the second article.
Or, perhaps you should remove the first verb and treat the intervening word as a verb?
In some cases you should add a , between the noun and the second article.

\s(?:an?|the(?! action))\s(?!way|wh|how\b)[A-Za-z][a-z]+[a-qs-z]\s(?:a(?! bit)n?|the)\s

Should be `without` (unless `out` is a modifier of the next word)

\bwith out\b(?!-)

In English, duplicated words are generally mistakes

There are a few exceptions (e.g. "that that").
If the highlighted doubled word pair is in:

code, write a pattern to mask it.
prose, have someone read the English before you dismiss this error.

\s([A-Z]{3,}|[A-Z][a-z]{2,}|[a-z]{3,})\s\g{-1}\s

Errors ❌ (1)

See the 📂 files view, the 📜action log, or 📝 job summary for details.

❌ Errors	Count
❌ forbidden-pattern	3

See ❌ Event descriptions for more information.

If the flagged items are 🤯 false positives

If items relate to a ...

binary file (or some other file you wouldn't want to check at all).

Please add a file path to the excludes.txt file matching the containing file.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).
well-formed pattern.

If you can write a pattern that would match it,
try adding it to the patterns.txt file.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

niels9001 · 2025-12-12T15:49:49Z

doc/devdocs/development/new-powertoy.md

+3. To simulate a "new user" you can delete the PowerToys folder from `%LOCALAPPDATA%\Microsoft`
+---
+## 9. Out-of-Box Experience (OOBE) page
+The OOBE page is a custom settings page that gives the user at a glance information about each module. This Window opens first before the Settings application for new users and after updates. Create `OOBE<ModuleName>.xaml` at ` src\settings-ui\Settings.UI\SettingsXAML\OOBE\Views`. You will also need to add your module name to the enum at `src\settings-ui\Settings.UI\OOBE\Enums\PowerToysModules.cs`


The body text is rendering in H2

niels9001 · 2025-12-12T15:51:27Z

doc/devdocs/development/new-powertoy.md

+---
+## 9. Out-of-Box Experience (OOBE) page
+The OOBE page is a custom settings page that gives the user at a glance information about each module. This Window opens first before the Settings application for new users and after updates. Create `OOBE<ModuleName>.xaml` at ` src\settings-ui\Settings.UI\SettingsXAML\OOBE\Views`. You will also need to add your module name to the enum at `src\settings-ui\Settings.UI\OOBE\Enums\PowerToysModules.cs`
+--


A few things that come to mind that are missing (in Step 10):

Module Icon

Module Image

OOBE Image

Docs

I'd maybe call these out as something to consider but we can handle those for the sake of consistency.

niels9001 · 2025-12-12T15:51:52Z

doc/devdocs/development/new-powertoy.md

+### Requirements
+
+* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) (Desktop & C++ workloads)
+* .NET 8 SDK


8 or 9? I dunno, was just wondering :).

Also, does this need to be installed manually? Wouldn't just setting up VS the right way have everything you'd need?

niels9001 · 2025-12-12T15:52:17Z

doc/devdocs/development/new-powertoy.md

+
+* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) (Desktop & C++ workloads)
+* .NET 8 SDK
+* [WiX v5 toolset](https://github.com/microsoft/PowerToys/tree/main)


For creating a new module you wouldn't need this do you?

niels9001 · 2025-12-12T15:52:36Z

doc/devdocs/development/new-powertoy.md

+* .NET 8 SDK
+* [WiX v5 toolset](https://github.com/microsoft/PowerToys/tree/main)
+* [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) cloned locally
+* [Able to build and run](https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/development/debugging.md) `PowerToys.slnx`.


Suggested change

* [Able to build and run](https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/development/debugging.md) `PowerToys.slnx`.

* [Validate that you are able to build and run](https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/development/debugging.md) `PowerToys.slnx`.

niels9001 · 2025-12-12T15:53:03Z

doc/devdocs/development/new-powertoy.md

+* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) (Desktop & C++ workloads)
+* .NET 8 SDK
+* [WiX v5 toolset](https://github.com/microsoft/PowerToys/tree/main)
+* [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) cloned locally


Suggested change

* [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) cloned locally

* Clone the [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) locally

niels9001 · 2025-12-12T15:55:35Z

doc/devdocs/development/new-powertoy.md

+
+First of all, thank you for wanting to contribute to PowerToys. The work we do would not be possible with out the support of community supporters like you.
+
+This guide documents the process of building a new PowerToys utility from scratch, including architecture decisions, integration steps, and common pitfalls.


Will we reference this somewhere, like https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/readme.md#how-to-create-new-powertoys?

niels9001 · 2025-12-12T15:58:48Z

doc/devdocs/development/new-powertoy.md

+
+### Requirements
+
+* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) (Desktop & C++ workloads)


We need to be exact on what to install / configure.

We also have this Winget config file (I do not know if this is up to date):

PowerToys/.config/configuration.winget

Line 13 in e13d6a7

- resource: Microsoft.WinGet.DSC/WinGetPackage

Maybe something like

"Make sure you have the right dev environment set up:

Visual Studio

List of components to check in VS

or use this Winget config file:

winget config linktofile blabla

Jaylyn-Barbee added 6 commits October 27, 2025 14:58

starting new powertoy guide

f2c9ab6

updates to document

0d11e9c

Updating doc (Thanks Jessica!)

3a374a5

Updating doc (thakns Jessica!)

a03f75a

Updating doc (Thanks Jessica!)

201fe49

Update new-powertoy.md

4a62754

github-advanced-security bot found potential problems Dec 12, 2025

View reviewed changes

niels9001 requested changes Dec 12, 2025

View reviewed changes

		@@ -0,0 +1,258 @@
		# 🧭 Creating a New PowerToy: End-to-End Developer Guide

		First of all, thank you for wanting to contribute to PowerToys. The work we do would not be possible with out the support of community supporters like you.

	* [Able to build and run](https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/development/debugging.md) `PowerToys.slnx`.
	* [Validate that you are able to build and run](https://github.com/microsoft/PowerToys/blob/main/doc/devdocs/development/debugging.md) `PowerToys.slnx`.

	* [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) cloned locally
	* Clone the [PowerToys repository](https://github.com/microsoft/PowerToys/tree/main) locally


		First of all, thank you for wanting to contribute to PowerToys. The work we do would not be possible with out the support of community supporters like you.

		This guide documents the process of building a new PowerToys utility from scratch, including architecture decisions, integration steps, and common pitfalls.


		### Requirements

		* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) (Desktop & C++ workloads)

Documentation walking through important steps for writing a New PowerToy #44242

Are you sure you want to change the base?

Documentation walking through important steps for writing a New PowerToy #44242

Conversation

Jaylyn-Barbee commented Dec 12, 2025

Summary of the Pull Request

Uh oh!

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

Check failure

github-actions bot commented Dec 12, 2025

@check-spelling-bot Report

🔴 Please review

See the 📂 files view, the 📜action log, or 📝 job summary for details.

Unrecognized words (6)

Articles generally shouldn't be used without a noun and a verb

Should be without (unless out is a modifier of the next word)

In English, duplicated words are generally mistakes

See the 📂 files view, the 📜action log, or 📝 job summary for details.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Should be `without` (unless `out` is a modifier of the next word)