[WindowsSettings] DevDocs + JSON schema (#13510)

* #10997 - Added JSON schema and extra shell class

* #13510 - Address feedback and fix wrong typo for a member

* #13510 - Add DevDoc (first version)

* #13510 - make spellcheck happy

* #13510 Address feedback, add scores, replace todos

* Make build server happy

* #13510 - Address feedback - Extra table for keys

* #13510 - Address feedback

* #13510 -Address feedback, add language specified

Co-authored-by: Sekan, Tobias <tobias.sekan@axp-consulting.de>

doc/devdocs/modules/launcher/plugins/windowssettings.md

@@ -0,0 +1,155 @@
+# Windows Settings Plugin
+
+The Windows settings Plugin allows users to search the Windows settings.
+
+## Special functions (differ from the regular functions)
+
+* Support modern Windows settings (Windows 10+)
+* Support legacy Windows settings (Windows 7, 8.1)
+* Support extra programs for setting (like ODBC)
+
+* Support search by the area of the setting (like `Privacy`)
+* Support search for alternative names of a setting
+
+## How to add a new Windows Setting or change one
+
+All Windows settings are located in `WindowsSettings.json` in root folder of the project.
+The `WindowsSettings.json` use a JSON schema file that make it easier to edit it.
+
+| Key                 | Optional | Value type        | String prefix |
+| ------------------- | -------- | ----------------- | ------------- |
+| `Name`              | **No**   | String            |               |
+| `Type`              | **No**   | String            | `App`         |
+| `Command`           | **No**   | String            |               |
+| `Areas`             | Yes      | List with strings | `Area`        |
+| `AltNames`          | Yes      | List with strings |               |
+| `Note`              | Yes      | String            | `Note`        |
+| `IntroducedInBuild` | Yes      | Integer           |               |
+| `DeprecatedInBuild` | Yes      | Integer           |               |
+
+A minimum entry for the `WindowsSettings.json` looks like:
+
+```json
+  {
+    "Name": "mySetting",
+    "Type": "AppSettingsApp",
+    "Command": "ms-settings:mySetting"
+  }
+```
+
+A full entry for the `WindowsSettings.json` looks like:
+
+```json
+  {
+    "Name": "mySetting",
+    "Type": "AppSettingsApp",
+    "Command": "ms-settings:mySetting",
+    "Areas": [ "AreaMySettingArea" ],
+    "AltNames": [ "NiceSetting" ],
+    "Note": "NoteMySettingNote",
+    "IntroducedInBuild" : 1903,
+    "DeprecatedInBuild" : 2004
+  }
+```
+
+### Remarks
+
+* The `Command` for modern Windows settings should start with `ms-settings:`
+* The `Command` for legacy Windows settings should start with `control`
+* The integer value for `IntroducedInBuild` and  `DeprecatedInBuild` must be in range of `0` to `4294967295`
+* The strings for `Name`, `AltNames`, `Areas`, `Type` and `Note` must not contain whitespace(s) or special characters (#, €, $, etc.)
+* The strings for `Name`, `AltNames`, `Areas`, `Type` and `Note` are used as ids for the resource file under `Properties\Resources.resx`
+* When you add new strings make sure you have add add all translations for it.
+
+## Scores
+
+There are three different score types with different start values.
+
+| Score type   | Start value  |
+| ------------ | ------------ |
+| High score   | 10000        |
+| Medium score |  5000        |
+| Low score    |  1000        |
+
+Each score will decreased by one when a condition match.
+
+| Priority | Condition                                                         | Score type   |
+| -------- | ----------------------------------------------------------------- | ------------ |
+| 1.       | Settings name starts with the search value                        | High score   |
+| 2.       | Settings name contain the search value                            | Medium score |
+| 3.       | Setting has no area                                               | Low score    |
+| 4.       | One area of the settings starts with the search value             | Low score    |
+| 5.       | Setting has no alternative name                                   | Low score    |
+| 6.       | One alternative name of the settings starts with the search value | Medium score |
+| x.       | no condition match                                                | Low score    |
+
+## Important for developers
+
+### General
+
+* The assembly name is cached into `_assemblyName` (to avoid to many calls of `Assembly.GetExecutingAssembly()`)
+
+## Microsoft.PowerToys.Run.Plugin.WindowsSettings project
+
+### Important plugin values (meta-data)
+
+| Name            | Value                                                |
+| --------------- | ---------------------------------------------------- |
+| ActionKeyword   | `$`                                                  |
+| ExecuteFileName | `Microsoft.PowerToys.Run.Plugin.WindowsSettings.dll` |
+| ID              | `5043CECEE6A748679CBE02D27D83747A`                   |
+
+### Interfaces used by this plugin
+
+The plugin use only these interfaces (all inside the `Main.cs`):
+
+* `Wox.Plugin.IPlugin`
+* `Wox.Plugin.IContextMenu`
+* `Wox.Plugin.IPluginI18n`
+
+### Program files
+
+| File                                  | Content                                                                 |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `Classes\WindowsSetting.cs`           | A class that represent one Windows setting                              |
+| `Classes\WindowsSettings.cs`          | A wrapper class that only contains a list with Windows settings (see 1) |
+| `Helper\ContextMenuHelper.cs`         | All functions to build the context menu (for each result entry)         |
+| `Helper\JsonSettingsListHelper.cs`    | All functions to load the windows settings from a JSON file             |
+| `Helper\ResultHelper.cs`              | All functions to convert internal results into WOX results              |
+| `Helper\TranslationHelper.cs`         | All functions to translate the result in the surface language           |
+| `Helper\UnsupportedSettingsHelper.cs` | All functions to filter not supported Windows settings out              |
+| `Helper\WindowsSettingsPathHelper.cs` | All functions to build the area paths                                   |
+| `Images\WindowsSettings.dark.png`     | Symbol for the results for the dark theme                               |
+| `Images\WindowsSettings.light.png`    | Symbol for the results for the light theme                              |
+| `Properties\Resources.Designer.resx`  | File that contain all translatable keys                                 |
+| `Properties\Resources.resx`           | File that contain all translatable strings in the neutral language      |
+| `GlobalSuppressions.cs`               | Code suppressions (no real file, linked via *.csproj)                   |
+| `Main.cs`                             | Main class, the only place that implement the WOX interfaces            |
+| `plugin.json`                         | All meta-data for this plugin                                           |
+| `StyleCop.json`                       | Code style (no real file, linked via *.csproj)                          |
+
+1. We need this extra wrapper class to make it possible that the JSON file can have and use a JSON schema file.
+Because the JSON file must have a object as root type, instead of a array.
+
+### Important project values (*.csproj)
+
+| Name            | Value                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------- |
+| TargetFramework | `netcoreapp3.1` (means .NET Core 3.1)                                                               |
+| Platforms       | `x64`                                                                                               |
+| Output          | `..\..\..\..\..\x64\Debug\modules\launcher\Plugins\Microsoft.PowerToys.Run.Plugin.WindowsSettings\` |
+| RootNamespace   | `Microsoft.PowerToys.Run.Plugin.WindowsSettings`                                                    |
+| AssemblyName    | `Microsoft.PowerToys.Run.Plugin.WindowsSettings`                                                    |
+
+### Project dependencies
+
+#### Packages
+
+| Package                                                                               | Version |
+| ------------------------------------------------------------------------------------- | ------- |
+| [`StyleCop.Analyzers`](https://github.com/DotNetAnalyzers/StyleCopAnalyzers)          | 1.1.118 |
+
+#### Projects
+
+* `Wox.Infrastructure`
+* `Wox.Plugin`

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Classes/WindowsSettings.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings
+{
+    /// <summary>
+    /// A class that contain all possible windows settings
+    /// </summary>
+    internal class WindowsSettings
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WindowsSettings"/> class with an empty settings list.
+        /// </summary>
+        public WindowsSettings()
+        {
+            Settings = Enumerable.Empty<WindowsSetting>();
+        }
+
+        /// <summary>
+        /// Gets or sets a list with all possible windows settings
+        /// </summary>
+        public IEnumerable<WindowsSetting> Settings { get; set; }
+    }
+}

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Helper/JsonSettingsListHelper.cs

@@ -27,12 +27,12 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
         /// Read all possible Windows settings.
         /// </summary>
         /// <returns>A list with all possible windows settings.</returns>
-        internal static IEnumerable<WindowsSetting> ReadAllPossibleSettings()
+        internal static WindowsSettings ReadAllPossibleSettings()
         {
             var assembly = Assembly.GetExecutingAssembly();
             var type = assembly.GetTypes().FirstOrDefault(x => x.Name == nameof(Main));
 
-            IEnumerable<WindowsSetting>? settingsList = null;
+            WindowsSettings? settings = null;
 
             try
             {
@@ -49,14 +49,14 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
                 using var reader = new StreamReader(stream);
                 var text = reader.ReadToEnd();
 
-                settingsList = JsonSerializer.Deserialize<IEnumerable<WindowsSetting>>(text, options);
+                settings = JsonSerializer.Deserialize<WindowsSettings>(text, options);
             }
             catch (Exception exception)
             {
                 Log.Exception("Error loading settings JSON file", exception, typeof(JsonSettingsListHelper));
             }
 
-            return settingsList ?? Enumerable.Empty<WindowsSetting>();
+            return settings ?? new WindowsSettings();
         }
     }
 }

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Helper/TranslationHelper.cs

@@ -16,17 +16,17 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
     internal static class TranslationHelper
     {
         /// <summary>
-        /// Translate all settings of the given list with <see cref="WindowsSetting"/>.
+        /// Translate all settings of the settings list in the given <see cref="WindowsSettings"/> class.
         /// </summary>
-        /// <param name="settingsList">The list that contains <see cref="WindowsSetting"/> to translate.</param>
+        /// <param name="windowsSettings">A class that contain all possible windows settings.</param>
-        internal static void TranslateAllSettings(in IEnumerable<WindowsSetting>? settingsList)
+        internal static void TranslateAllSettings(in WindowsSettings windowsSettings)
         {
-            if (settingsList is null)
+            if (windowsSettings?.Settings is null)
             {
                 return;
             }
 
-            foreach (var settings in settingsList)
+            foreach (var settings in windowsSettings.Settings)
             {
                 // Translate Name
                 if (!string.IsNullOrWhiteSpace(settings.Name))

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Helper/UnsupportedSettingsHelper.cs

@@ -19,15 +19,14 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
         private const string _keyNameBuildNumber = "CurrentBuildNumber";
 
         /// <summary>
-        /// Remove all <see cref="WindowsSetting"/> of the given list that are not present on the current used Windows build.
+        /// Remove all <see cref="WindowsSetting"/> from the settings list in the given <see cref="WindowsSetting"/> class.
         /// </summary>
-        /// <param name="settingsList">The list with <see cref="WindowsSetting"/> to filter.</param>
+        /// <param name="windowsSettings">A class that contain all possible windows settings.</param>
-        /// <returns>A new list with <see cref="WindowsSetting"/> that only contain present Windows settings for this OS.</returns>
+        internal static void FilterByBuild(in WindowsSettings windowsSettings)
-        internal static IEnumerable<WindowsSetting> FilterByBuild(in IEnumerable<WindowsSetting>? settingsList)
         {
-            if (settingsList is null)
+            if (windowsSettings?.Settings is null)
             {
-                return Enumerable.Empty<WindowsSetting>();
+                return;
             }
 
             var currentBuild = GetNumericRegistryValue(_keyPath, _keyNameBuild);
@@ -48,13 +47,13 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
                 ? currentBuild
                 : currentBuildNumber;
 
-            var filteredSettingsList = settingsList.Where(found
+            var filteredSettingsList = windowsSettings.Settings.Where(found
                 => (found.DeprecatedInBuild == null || currentWindowsBuild < found.DeprecatedInBuild)
                 && (found.IntroducedInBuild == null || currentWindowsBuild >= found.IntroducedInBuild));
 
             filteredSettingsList = filteredSettingsList.OrderBy(found => found.Name);
 
-            return filteredSettingsList;
+            windowsSettings.Settings = filteredSettingsList;
         }
 
         /// <summary>

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Helper/WindowsSettingsPathHelper.cs

@@ -19,17 +19,17 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
         private const string _pathDelimiterSequence = "\u0020\u0020\u02C3\u0020\u0020"; // = "<space><space><arrow><space><space>"
 
         /// <summary>
-        /// Generates the values for <see cref="WindowsSetting.JoinedAreaPath"/> and <see cref="WindowsSetting.JoinedFullSettingsPath"/> on all settings of the given list with <see cref="WindowsSetting"/>.
+        /// Generates the values for <see cref="WindowsSetting.JoinedAreaPath"/> and <see cref="WindowsSetting.JoinedFullSettingsPath"/> on all settings of the list in the given <see cref="WindowsSettings"/> class.
         /// </summary>
-        /// <param name="settingsList">The list that contains <see cref="WindowsSetting"/> to translate.</param>
+        /// <param name="windowsSettings">A class that contain all possible windows settings.</param>
-        internal static void GenerateSettingsPathValues(in IEnumerable<WindowsSetting>? settingsList)
+        internal static void GenerateSettingsPathValues(in WindowsSettings windowsSettings)
         {
-            if (settingsList is null)
+            if (windowsSettings?.Settings is null)
             {
                 return;
             }
 
-            foreach (var settings in settingsList)
+            foreach (var settings in windowsSettings.Settings)
             {
                 // Check if type value is filled. If not, then write log warning.
                 if (string.IsNullOrEmpty(settings.Type))
@@ -52,9 +52,9 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings.Helper
                 // Generating path values.
                 if (!(settings.Areas is null) && settings.Areas.Any())
                 {
-                    var areaValue = string.Join(WindowsSettingsPathHelper._pathDelimiterSequence, settings.Areas);
+                    var areaValue = string.Join(_pathDelimiterSequence, settings.Areas);
                     settings.JoinedAreaPath = areaValue;
-                    settings.JoinedFullSettingsPath = $"{settings.Type}{WindowsSettingsPathHelper._pathDelimiterSequence}{areaValue}";
+                    settings.JoinedFullSettingsPath = $"{settings.Type}{_pathDelimiterSequence}{areaValue}";
                 }
                 else
                 {

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/Main.cs

@@ -49,9 +49,9 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings
         private bool _disposed;
 
         /// <summary>
-        /// List that contain all settings.
+        /// A class that contain all possible windows settings.
         /// </summary>
-        private IEnumerable<WindowsSetting>? _settingsList;
+        private WindowsSettings? _windowsSettings;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="Main"/> class.
@@ -82,11 +82,12 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings
             _context.API.ThemeChanged += OnThemeChanged;
             UpdateIconPath(_context.API.GetCurrentTheme());
 
-            _settingsList = JsonSettingsListHelper.ReadAllPossibleSettings();
+            _windowsSettings = JsonSettingsListHelper.ReadAllPossibleSettings();
-            _settingsList = UnsupportedSettingsHelper.FilterByBuild(_settingsList);
 
-            TranslationHelper.TranslateAllSettings(_settingsList);
+            UnsupportedSettingsHelper.FilterByBuild(_windowsSettings);
-            WindowsSettingsPathHelper.GenerateSettingsPathValues(_settingsList);
+
+            TranslationHelper.TranslateAllSettings(_windowsSettings);
+            WindowsSettingsPathHelper.GenerateSettingsPathValues(_windowsSettings);
         }
 
         /// <summary>
@@ -96,12 +97,12 @@ namespace Microsoft.PowerToys.Run.Plugin.WindowsSettings
         /// <returns>A filtered list, can be empty when nothing was found.</returns>
         public List<Result> Query(Query query)
         {
-            if (_settingsList is null)
+            if (_windowsSettings?.Settings is null)
             {
                 return new List<Result>(0);
             }
 
-            var filteredList = _settingsList
+            var filteredList = _windowsSettings.Settings
                 .Where(Predicate)
                 .OrderBy(found => found.Name);
 

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/WindowsSettings.json

@@ -1,4 +1,6 @@
-[
+{
+  "$schema" : "./WindowsSettings.schema.json",
+  "Settings": [
     {
         "Name": "AccessWorkOrSchool",
         "Areas": [ "AreaAccounts" ],
@@ -1734,4 +1736,4 @@
     "AltNames": [ "wgpocpl.cpl" ],
     "Command": "control Wgpocpl.cpl"
   }
-]
+]}

src/modules/launcher/Plugins/Microsoft.PowerToys.Run.Plugin.WindowsSettings/WindowsSettings.schema.json

@@ -0,0 +1,65 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "additionalProperties": false,
+    "required": [ "Settings" ],
+    "properties": {
+        "Settings": {
+            "description": "A list with all possible windows settings.",
+            "type": "array",
+            "items": {
+                "additionalProperties": false,
+                "required": [ "Name", "Command", "Type" ],
+                "type": "object",
+                "properties": {
+                    "Name": {
+                        "description": "The name of this setting.",
+                        "type": "string"
+                    },
+                    "Areas": {
+                        "description": "A list of areas of this setting",
+                        "type": "array",
+                        "items": {
+                            "description": "A area of this setting",
+                            "type": "string",
+                            "pattern": "^Area"
+                        }
+                    },
+                    "Type": {
+                        "description": "The type of this setting.",
+                        "type": "string",
+                        "pattern": "^App"
+                    },
+                    "AltNames": {
+                        "description": "A list with alternative names for this setting",
+                        "type": "array",
+                        "items": {
+                            "description": "A alternative name for this setting",
+                            "type": "string"
+                        }
+                    },
+                    "Command": {
+                        "description": "The command for this setting.",
+                        "type": "string"
+                    },
+                    "Note": {
+                        "description": "A additional note for this setting.",
+                        "type": "string",
+                        "pattern": "^Note"
+                    },
+                    "DeprecatedInBuild": {
+                        "description": "The Windows build since this settings is not longer present.",
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 4294967295
+                    },
+                    "IntroducedInBuild": {
+                        "description": "The minimum need Windows build for this setting.",
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 4294967295
+                    }
+                }
+            }
+        }
+    }
+}