[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-09-02 07:25:10 +00:00 · 2025-07-01 14:27:34 +02:00
parent 9c2e83d6eb
commit 725535b760
102 changed files with 5361 additions and 325 deletions
--- a/doc/devdocs/tools/bug-report-tool.md
+++ b/doc/devdocs/tools/bug-report-tool.md
@@ -1,24 +1,56 @@
-# [Bug report tool](/tools/BugReportTool/)
+# Bug Report Tool

-This tool is used to collect logs and system information for bug reports. The bug report is then saved as a zip file on the desktop.
+The Bug Report Tool is a utility that collects logs and system information to help diagnose issues with PowerToys. It creates a comprehensive report that can be shared with developers to help troubleshoot problems.

-## Launching
+## Location and Access

-It can launch from the PowerToys tray icon by clicking "Report Bug", by clicking the bug report icon in the PowerToys flyout  or by running the executable directly.
+- Source code: `/tools/BugReportTool/`
+- Users can trigger the tool via:
+  - Right-click on PowerToys tray icon → Report Bug
+  - Left-click on tray icon → Open Settings → Bug Report Tool

-## Included files
+## What It Does

-The bug report includes the following files:
+The Bug Report Tool creates a zip file on the desktop named "PowerToys_Report_[date]_[time].zip" containing logs and system information. It:
+
+1. Copies logs from PowerToys application directories
+2. Collects system information relevant to PowerToys functionality
+3. Redacts sensitive information
+4. Packages everything into a single zip file for easy sharing
+
+## Information Collected
+
+### Logs
+- Copies logs from:
+  - `%LOCALAPPDATA%\Microsoft\PowerToys\Logs` - Regular logs
+  - `%USERPROFILE%\AppData\LocalLow\Microsoft\PowerToys` - Low-privilege logs
+
+### System Information
+- Windows version and build information
+- Language and locale settings
+- Monitor information (crucial for FancyZones and multi-monitor scenarios)
+- .NET installation details
+- PowerToys registry entries
+- Group Policy Object (GPO) settings
+- Application compatibility mode settings
+- Event Viewer logs related to PowerToys executables
+- PowerToys installer logs
+- Windows 11 context menu package information
+
+### PowerToys Configuration
+- Settings files
+- Module configurations
+- Installation details
+- File structure and integrity (with hashes)
+
+## Key Files in the Report

-* Settings files of the modules.
-* Logs of the modules and the runner.
-* Update log files.
 * `compatibility-tab-info.txt` - Information about [compatibility settings](https://support.microsoft.com/windows/make-older-apps-or-programs-compatible-with-windows-783d6dd7-b439-bdb0-0490-54eea0f45938) set for certain PowerToys executables both in the user and system scope.
 * `context-menu-packages.txt` - Information about the packages that are registered for the new Windows 11 context menu.
 * `dotnet-installation-info.txt` - Information about the installed .NET versions.
 * `EventViewer-*.xml` - These files contain event logs from the Windows Event Viewer for the executable specified in the file name.
 * `EventViewer-Microsoft-Windows-AppXDeploymentServer/Operational.xml` - Contains event logs from the AppXDeployment-Server which are useful for diagnosing MSIX installation issues.
-* `gpo-configuration-info.txt` - Information about the configured [GPO](/doc/gpo/README.md).
+* `gpo-configuration-info.txt` - Information about the configured [GPO](doc/devdocs/processes/gpo.md).
 * `installationFolderStructure.txt` - Information about the folder structure of the installation. All lines with files have the following structure: `FileName Version MD5Hash`.
 * `last_version_run.json` - Information about the last version of PowerToys that was run.
 * `log_settings.json` - Information about the log level settings.
@@ -30,3 +62,58 @@ The bug report includes the following files:
 * `UpdateState.json` - Information about the last update check and the current status of the update download.
 * `windows-settings.txt` - Information about the Windows language settings.
 * `windows-version.txt` - Information about the Windows version.
+
+## Privacy Considerations
+
+The tool redacts certain types of private information:
+- Mouse Without Borders security keys
+- FancyZones app zone history
+- User-specific paths
+- Machine names
+
+## Implementation Details
+
+The tool is implemented as a C# console application that:
+1. Creates a temporary directory
+2. Copies logs and configuration files to this directory
+3. Runs commands to collect system information
+4. Redacts sensitive information
+5. Compresses everything into a zip file
+6. Cleans up the temporary directory
+
+### Core Components
+
+- `BugReportTool.exe` - Main executable
+- Helper classes for collecting specific types of information
+- Redaction logic to remove sensitive data
+
+## Extending the Bug Report Tool
+
+When adding new PowerToys features, the Bug Report Tool may need to be updated to collect relevant information. Areas to consider:
+
+1. New log locations to include
+2. Additional registry keys to examine
+3. New GPO values to report
+4. Process names to include in Event Viewer data collection
+5. New configuration files to include
+
+## Build Process
+
+The Bug Report Tool is built separately from the main PowerToys solution:
+
+1. Path from root: `tools\BugReportTool\BugReportTool.sln`
+2. Must be built before building the installer
+3. Built version is included in the PowerToys installer
+
+### Building from the Command Line
+
+```
+nuget restore .\tools\BugReportTool\BugReportTool.sln
+msbuild -p:Platform=x64 -p:Configuration=Release .\tools\BugReportTool\BugReportTool.sln
+```
+
+### Building from Visual Studio
+
+1. Open `tools\BugReportTool\BugReportTool.sln`
+2. Set the Solution Configuration to `Release`
+3. Build the solution
--- a/doc/devdocs/tools/debugging-tools.md
+++ b/doc/devdocs/tools/debugging-tools.md
@@ -0,0 +1,111 @@
+# PowerToys Debugging Tools
+
+PowerToys includes several specialized tools to help with debugging and troubleshooting. These tools are designed to make it easier to diagnose issues with PowerToys features.
+
+## FancyZones Debugging Tools
+
+### FancyZones Hit Test Tool
+
+- Location: `/tools/FancyZonesHitTest/`
+- Purpose: Tests FancyZones layout selection logic
+- Functionality:
+  - Simulates mouse cursor positions
+  - Highlights which zone would be selected
+  - Helps debug zone detection issues
+
+### FancyZones Draw Layout Test
+
+- Location: `/tools/FancyZonesDrawLayoutTest/`
+- Purpose: Tests FancyZones layout drawing logic
+- Functionality:
+  - Visualizes how layouts are drawn
+  - Helps debug rendering issues
+  - Tests different monitor configurations
+
+### FancyZones Zonable Tester
+
+- Location: `/tools/FancyZonesZonableTester/`
+- Purpose: Tests if a window is "zonable" (can be moved to zones)
+- Functionality:
+  - Checks if windows match criteria for zone placement
+  - Helps debug why certain windows can't be zoned
+
+## Monitor Information Tools
+
+### Monitor Info Report
+
+- Location: `/tools/MonitorPickerTool/`
+- Purpose: Diagnostic tool for identifying WinAPI bugs related to physical monitor detection
+- Functionality:
+  - Lists all connected monitors
+  - Shows detailed monitor information
+  - Helps debug multi-monitor scenarios
+
+## Window Information Tools
+
+### Styles Report Tool
+
+- Location: `/tools/StylesReportTool/`
+- Purpose: Collect information about an open window
+- Functionality:
+  - Reports window styles
+  - Shows window class information
+  - Helps debug window-related issues in modules like FancyZones
+
+### Build Process
+
+The Styles Report Tool is built separately from the main PowerToys solution:
+
+```
+nuget restore .\tools\StylesReportTool\StylesReportTool.sln
+msbuild -p:Platform=x64 -p:Configuration=Release .\tools\StylesReportTool\StylesReportTool.sln
+```
+
+## Shell-Related Debugging Tools
+
+### PowerRenameContextMenu Test
+
+- Location: `/tools/PowerRenameContextMenuTest/`
+- Purpose: Tests PowerRename context menu integration
+- Functionality:
+  - Simulates right-click context menu
+  - Helps debug shell extension issues
+
+## Verification Tools
+
+### Verification Scripts
+
+- Location: `/tools/verification-scripts/`
+- Purpose: Scripts to verify PowerToys installation and functionality
+- Functionality:
+  - Verify binary integrity
+  - Check registry entries
+  - Test module loading
+
+## Other Debugging Tools
+
+### Clean Up Tool
+
+- Location: `/tools/CleanUp/`
+- Purpose: Clean up PowerToys installation artifacts
+- Functionality:
+  - Removes registry entries
+  - Deletes settings files
+  - Helps with clean reinstallation
+
+### Using Debugging Tools
+
+1. Most tools can be run directly from the command line
+2. Some tools require administrator privileges
+3. Tools are typically used during development or for advanced troubleshooting
+4. Bug Report Tool can collect and package the output from several of these tools
+
+## Adding New Debugging Tools
+
+When creating new debugging tools:
+
+1. Place the tool in the `/tools/` directory
+2. Follow existing naming conventions
+3. Document the tool in this file
+4. Include a README.md in the tool's directory
+5. Consider adding the tool's output to the Bug Report Tool if appropriate
--- a/doc/devdocs/tools/fancyzones-draw-layout-test.md
+++ b/doc/devdocs/tools/fancyzones-draw-layout-test.md
@@ -1,7 +0,0 @@
-# [FancyZones_DrawLayoutTest](/tools/FancyZones_DrawLayoutTest/)
-
-This test tool is created in order to debug issues related to the drawing of zone layout on screen.
-
-Currently, only column layout is supported with modifiable number of zones. Pressing **w** key toggles zone appearance on primary screen (multi monitor support not yet in place). Pressing **q** key exits application.
-
-Application is DPI unaware which means that application does not scale for DPI changes and it always assumes to have a scale factor of 100% (96 DPI). Scaling will be automatically performed by the system.
--- a/doc/devdocs/tools/fancyzones-hit-test.md
+++ b/doc/devdocs/tools/fancyzones-hit-test.md
@@ -1,5 +0,0 @@
-# [FancyZone hit test tool](/tools/FancyZone_HitTest/)
-
-![Image of the FancyZones hit test tool](/doc/images/tools/fancyzones-hit-test.png)
-
-This tool tests the FancyZones layout selection logic. It displays a window with 5 zones. By hovering the mouse over the zones, the zone under the mouse cursor is highlighted. The sidebar shows different metrics that are used to determine which zone is under the mouse cursor.
--- a/doc/devdocs/tools/fancyzones-zonable-tester.md
+++ b/doc/devdocs/tools/fancyzones-zonable-tester.md
@@ -1,13 +0,0 @@
-# [FancyZones_zonable_tester](/tools/FancyZones_zonable_tester/)
-
-![Image of the FancyZones zonable tester](/doc/images/tools/fancyzones-zonable-tester.png)
-
-This command line application tests if the window where the mouse cursor is located is zonable. It also adds additional information about the window to the console output:
-
-* The HWND (window handle) of the window
-* The process ID of the window
-* The HWND of the window in the foreground
-* The style of the window
-* The exStyle of the window
-* The window class
-* The path of the process that created the window
--- a/doc/devdocs/tools/fuzzingtesting.md
+++ b/doc/devdocs/tools/fuzzingtesting.md
@@ -0,0 +1,243 @@
+# Fuzzing Testing in PowerToys
+
+## Overview
+
+Fuzzing is an automated testing technique that helps identify vulnerabilities and bugs by feeding random, invalid, or unexpected data into the application. This is especially important for PowerToys modules that handle file input/output or user input, such as Hosts File Editor, Registry Preview, and others.
+
+PowerToys integrates Microsoft's OneFuzz service to systematically discover edge cases and unexpected behaviors that could lead to crashes or security vulnerabilities. Fuzzing testing is a requirement from the security team to ensure robust and secure modules.
+
+## Why Fuzzing Matters
+
+- **Security Enhancement**: Identifies potential security vulnerabilities before they reach production
+- **Stability Improvement**: Discovers edge cases that might cause crashes
+- **Automated Bug Discovery**: Finds bugs that traditional testing might miss
+- **Reduced Manual Testing**: Automates the process of testing with unusual inputs
+
+## Types of Fuzzing in PowerToys
+
+PowerToys supports two types of fuzzing depending on the module's implementation language:
+
+1. **.NET Fuzzing** - For C# modules (using [OneFuzz](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code))
+2. **C++ Fuzzing** - For native C++ modules using [libFuzzer](https://llvm.org/docs/LibFuzzer.html)
+
+## Setting Up .NET Fuzzing Tests
+
+### Step 1: Add a Fuzzing Test Project
+
+Create a new test project within your module folder. Ensure the project name follows the format `*.FuzzTests`.
+
+### Step 2: Configure the Project
+
+1. Set up a `.NET 8 (Windows)` project
+   - Note: OneFuzz currently supports only .NET 8 projects. The Fuzz team is working on .NET 9 support.
+
+2. Add the required files to your fuzzing test project:
+   - Create fuzzing test code
+   - Add `OneFuzzConfig.json` configuration file
+
+### Step 3: Configure OneFuzzConfig.json
+
+The `OneFuzzConfig.json` file provides critical information for deploying fuzzing jobs. For detailed guidance, see the [OneFuzzConfig V3 Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/onefuzzconfig/onefuzzconfigv3).
+
+```json
+{
+  "fuzzers": [
+    {
+      "name": "YourModuleFuzzer",
+      "fuzzerLibrary": "libfuzzer-dotnet",
+      "targetAssembly": "YourModule.FuzzTests.dll",
+      "targetClass": "YourModule.FuzzTests.FuzzTestClass",
+      "targetMethod": "FuzzTest",
+      "FuzzingTargetBinaries": [
+        "YourModule.FuzzTests.dll"
+      ]
+    }
+  ],
+  "adoTemplate": [
+    {
+      "AssignedTo": "PowerToys@microsoft.com",
+      "jobNotificationEmail": "PowerToys@microsoft.com"
+    }
+  ],
+  "oneFuzzJobs": [
+    {
+      "projectName": "PowerToys",
+      "targetName": "YourModule",
+      "jobDependencies": {
+        "binaries": [
+          "PowerToys\\x64\\Debug\\tests\\YourModule.FuzzTests\\net8.0-windows10.0.19041.0\\**"
+        ]
+      }
+    }
+  ],
+  "configVersion": "3.0.0"
+}
+```
+
+Key fields to update:
+1. Update the `targetAssembly`, `targetClass`, `targetMethod`, and `FuzzingTargetBinaries` fields
+2. Set the `AssignedTo` and `jobNotificationEmail` to your Microsoft email
+3. Update the `projectName` and `targetName` fields
+4. Define job dependencies pointing to your compiled fuzzing tests
+
+### Step 4: Configure the OneFuzz Pipeline
+
+Modify the patterns in the job steps within [job-fuzz.yml](https://github.com/microsoft/PowerToys/blob/main/.pipelines/v2/templates/job-fuzz.yml) to match your fuzzing project name:
+
+```yaml
+- download: current
+  displayName: Download artifacts
+  artifact: $(ArtifactName)
+  patterns: |-
+    **/tests/*.FuzzTests/**
+```
+
+## Setting Up C++ Fuzzing Tests
+
+### Step 1: Create a New C++ Project
+
+- Use the **Empty Project** template
+- Name it `<ModuleName>.FuzzingTest`
+
+### Step 2: Update Build Configuration
+
+- In **Configuration Manager**, uncheck Build for both Release|ARM64, Debug|ARM64 and Debug|x64 configurations
+- ARM64 is not supported for fuzzing tests
+
+### Step 3: Enable ASan and libFuzzer in .vcxproj
+
+Edit the project file to enable fuzzing:
+
+```xml
+<PropertyGroup>
+  <EnableASAN>true</EnableASAN>
+  <EnableFuzzer>true</EnableFuzzer>
+</PropertyGroup>
+```
+
+### Step 4: Add Fuzzing Compiler Flags
+
+Add these to `AdditionalOptions` under the `Fuzzing` configuration:
+
+```xml
+/fsanitize=address
+/fsanitize-coverage=inline-8bit-counters
+/fsanitize-coverage=edge
+/fsanitize-coverage=trace-cmp
+/fsanitize-coverage=trace-div
+%(AdditionalOptions)
+```
+
+### Step 5: Link the Sanitizer Coverage Runtime
+
+In `Linker → Input → Additional Dependencies`, add:
+
+```text
+$(VCToolsInstallDir)lib\$(Platform)\libsancov.lib
+```
+
+### Step 6: Copy Required Runtime DLL
+
+Add a `PostBuildEvent` to copy the ASAN DLL:
+
+```xml
+<Command>
+  xcopy /y "$(VCToolsInstallDir)bin\Hostx64\x64\clang_rt.asan_dynamic-x86_64.dll" "$(OutDir)"
+</Command>
+```
+
+### Step 7: Add Preprocessor Definitions
+
+To avoid annotation issues, add these to the `Preprocessor Definitions`:
+
+```text
+_DISABLE_VECTOR_ANNOTATION;_DISABLE_STRING_ANNOTATION
+```
+
+### Step 8: Implement the Entry Point
+
+Every C++ fuzzing project must expose this function:
+
+```cpp
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
+{
+    std::string input(reinterpret_cast<const char*>(data), size);
+
+    try
+    {
+        // Call your module with the input here
+    }
+    catch (...) {}
+
+    return 0;
+}
+```
+
+## Running Fuzzing Tests
+
+### Running Locally (.NET)
+
+To run .NET fuzzing tests locally, follow the [Running a .NET Fuzz Target Locally](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code#extra-running-a-net-fuzz-target-locally) guide:
+
+```powershell
+# Instrument the assembly
+.\dotnet-fuzzing-windows\sharpfuzz\SharpFuzz.CommandLine.exe path\to\YourModule.FuzzTests.dll
+
+# Set environment variables
+$env:LIBFUZZER_DOTNET_TARGET_ASSEMBLY="path\to\YourModule.FuzzTests.dll"
+$env:LIBFUZZER_DOTNET_TARGET_CLASS="YourModule.FuzzTests.FuzzTestClass"
+$env:LIBFUZZER_DOTNET_TARGET_METHOD="FuzzTest"
+
+# Run the fuzzer
+.\dotnet-fuzzing-windows\libfuzzer-dotnet\libfuzzer-dotnet.exe --target_path=dotnet-fuzzing-windows\LibFuzzerDotnetLoader\LibFuzzerDotnetLoader.exe
+```
+
+### Running in the Cloud
+
+To submit a job to the OneFuzz cloud service, follow the [OneFuzz Cloud Testing Walkthrough](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/faq/notwindows/walkthrough):
+
+1. Run the pipeline:
+   - Navigate to the [fuzzing pipeline](https://microsoft.visualstudio.com/Dart/_build?definitionId=152899&view=runs)
+   - Click "Run pipeline"
+   - Choose your branch and start the run
+
+2. Alternative: Use [OIP (OneFuzz Ingestion Preparation) tool](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/oip/onefuzzingestionpreparationtool):
+   ```
+   oip submit --config .\OneFuzzConfig.json --drop-path <your_submission_directory> --platform windows --do-not-file-bugs --duration 1
+   ```
+   - Use `--do-not-file-bugs` to prevent automatic bug creation during initial testing
+   - `--duration` specifies the number of hours (default is 48 if not specified)
+
+3. OneFuzz will send you an email when the job has started with a link to view results
+
+## Reviewing Results
+
+1. You'll receive an email notification when your fuzzing job starts
+2. Click the link in the email to view the job status on the [OneFuzz Web UI](https://onefuzz-ui.microsoft.com/)
+3. The OneFuzz platform will show statistics like inputs processed, coverage, and any crashes found
+4. If the final status is "success," your fuzzing test is working correctly
+
+## Current Status
+
+PowerToys has implemented fuzzing for several modules:
+- Hosts File Editor
+- Registry Preview
+- Fancy Zones
+
+Modules that still need fuzzing implementation:
+- Environmental Variables
+- Keyboard Manager
+
+## Requesting Access to OneFuzz
+
+To log into the production instance of OneFuzz with the [CLI](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/downloading-cli), you must request access. Visit the [OneFuzz Access Request Page](https://myaccess.microsoft.com/@microsoft.onmicrosoft.com#/access-packages/6df691eb-e3d1-444b-b4b2-9e944dc794be).
+
+## Resources
+
+- [OneFuzz Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/fuzzing-dotnet-code)
+- [OneFuzzConfig V3 Documentation](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/onefuzzconfig/onefuzzconfigv3)
+- [OneFuzz Ingestion Preparation Tool](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/oip/onefuzzingestionpreparationtool)
+- [OneFuzz CLI Setup Guide](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/howto/downloading-cli)
+- [OneFuzz Web UI](https://onefuzz-ui.microsoft.com/)
+- [libFuzzer Documentation](https://llvm.org/docs/LibFuzzer.html)
+- [OneFuzz Cloud Testing Walkthrough](https://eng.ms/docs/cloud-ai-platform/azure-edge-platform-aep/aep-security/epsf-edge-and-platform-security-fundamentals/the-onefuzz-service/onefuzz/faq/notwindows/walkthrough)
--- a/doc/devdocs/tools/readme.md
+++ b/doc/devdocs/tools/readme.md
@@ -11,9 +11,6 @@ Following tools are currently available:
 * [BugReportTool](bug-report-tool.md) - A tool to collect logs and system information for bug reports.
 * [Build tools](build-tools.md) - A set of scripts that help building PowerToys.
 * [Clean up tool](clean-up-tool.md) - A tool to clean up the PowerToys installation.
-* [FancyZones hit test](fancyzones-hit-test.md) - A tool to test FancyZones layout selection logic.
-* [FancyZones draw layout test](fancyzones-draw-layout-test.md) - A tool to test FancyZones layout drawing logic.
-* [FancyZones zonable tester](fancyzones-zonable-tester.md) - A tool to test if a window is zonable.
 * [Monitor info report](monitor-info-report.md) - A small diagnostic tool which helps identifying WinAPI bugs related to the physical monitor detection.
 * [project template](/tools/project_template/README.md) - A Visual Studio project template for a new PowerToys project.
 * [StylesReportTool](styles-report-tool.md) - A tool to collect information about an open window.