|
| 1 | +--- |
| 2 | +name: winmd-api-search |
| 3 | +description: 'Find and explore Windows desktop APIs. Use when building features that need platform capabilities — camera, file access, notifications, UI controls, AI/ML, sensors, networking, etc. Discovers the right API for a task and retrieves full type details (methods, properties, events, enumeration values).' |
| 4 | +license: Complete terms in LICENSE.txt |
| 5 | +--- |
| 6 | + |
| 7 | +# WinMD API Search |
| 8 | + |
| 9 | +This skill helps you find the right Windows API for any capability and get its full details. It searches a local cache of all WinMD metadata from: |
| 10 | + |
| 11 | +- **Windows Platform SDK** — all `Windows.*` WinRT APIs (always available, no restore needed) |
| 12 | +- **WinAppSDK / WinUI** — bundled as a baseline in the cache generator (always available, no restore needed) |
| 13 | +- **NuGet packages** — any additional packages in restored projects that contain `.winmd` files |
| 14 | +- **Project-output WinMD** — class libraries (C++/WinRT, C#) that produce `.winmd` as build output |
| 15 | + |
| 16 | +Even on a fresh clone with no restore or build, you still get full Platform SDK + WinAppSDK coverage. |
| 17 | + |
| 18 | +## When to Use This Skill |
| 19 | + |
| 20 | +- User wants to build a feature and you need to find which API provides that capability |
| 21 | +- User asks "how do I do X?" where X involves a platform feature (camera, files, notifications, sensors, AI, etc.) |
| 22 | +- You need the exact methods, properties, events, or enumeration values of a type before writing code |
| 23 | +- You're unsure which control, class, or interface to use for a UI or system task |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +- **.NET SDK 8.0 or later** — required to build the cache generator. Install from [dotnet.microsoft.com](https://dotnet.microsoft.com/download) if not available. |
| 28 | + |
| 29 | +## Cache Setup (Required Before First Use) |
| 30 | + |
| 31 | +All query and search commands read from a local JSON cache. **You must generate the cache before running any queries.** |
| 32 | + |
| 33 | +```powershell |
| 34 | +# All projects in the repo (recommended for first run) |
| 35 | +.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1 |
| 36 | +
|
| 37 | +# Single project |
| 38 | +.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1 -ProjectDir <project-folder> |
| 39 | +``` |
| 40 | + |
| 41 | +No project restore or build is needed for baseline coverage (Platform SDK + WinAppSDK). For additional NuGet packages, the project needs `dotnet restore` (which generates `project.assets.json`) or a `packages.config` file. |
| 42 | + |
| 43 | +Cache is stored at `Generated Files\winmd-cache\`, deduplicated per-package+version. |
| 44 | + |
| 45 | +### What gets indexed |
| 46 | + |
| 47 | +| Source | When available | |
| 48 | +|--------|----------------| |
| 49 | +| Windows Platform SDK | Always (reads from local SDK install) | |
| 50 | +| WinAppSDK (latest) | Always (bundled as baseline in cache generator) | |
| 51 | +| WinAppSDK Runtime | When installed on the system (detected via `Get-AppxPackage`) | |
| 52 | +| Project NuGet packages | After `dotnet restore` or with `packages.config` | |
| 53 | +| Project-output `.winmd` | After project build (class libraries that produce WinMD) | |
| 54 | + |
| 55 | +> **Note:** This cache directory should be in `.gitignore` — it's generated, not source. |
| 56 | +
|
| 57 | +## How to Use |
| 58 | + |
| 59 | +Pick the path that matches the situation: |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +### Discover — "I don't know which API to use" |
| 64 | + |
| 65 | +The user describes a capability in their own words. You need to find the right API. |
| 66 | + |
| 67 | +**0. Ensure the cache exists** |
| 68 | + |
| 69 | +If the cache hasn't been generated yet, run `Update-WinMdCache.ps1` first — see [Cache Setup](#cache-setup-required-before-first-use) above. |
| 70 | + |
| 71 | +**1. Translate user language → search keywords** |
| 72 | + |
| 73 | +Map the user's daily language to programming terms. Try multiple variations: |
| 74 | + |
| 75 | +| User says | Search keywords to try (in order) | |
| 76 | +|-----------|-----------------------------------| |
| 77 | +| "take a picture" | `camera`, `capture`, `photo`, `MediaCapture` | |
| 78 | +| "load from disk" | `file open`, `picker`, `FileOpen`, `StorageFile` | |
| 79 | +| "describe what's in it" | `image description`, `Vision`, `Recognition` | |
| 80 | +| "show a popup" | `dialog`, `flyout`, `popup`, `ContentDialog` | |
| 81 | +| "drag and drop" | `drag`, `drop`, `DragDrop` | |
| 82 | +| "save settings" | `settings`, `ApplicationData`, `LocalSettings` | |
| 83 | + |
| 84 | +Start with simple everyday words. If results are weak or irrelevant, try the more technical variation. |
| 85 | + |
| 86 | +**2. Run searches** |
| 87 | + |
| 88 | +```powershell |
| 89 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action search -Query "<keyword>" |
| 90 | +``` |
| 91 | + |
| 92 | +This returns ranked namespaces with top matching types and the **JSON file path**. |
| 93 | + |
| 94 | +If results have **low scores (below 60) or are irrelevant**, fall back to searching online documentation: |
| 95 | + |
| 96 | +1. Use web search to find the right API on Microsoft Learn, for example: |
| 97 | + - `site:learn.microsoft.com/uwp/api <capability keywords>` for `Windows.*` APIs |
| 98 | + - `site:learn.microsoft.com/windows/windows-app-sdk/api/winrt <capability keywords>` for `Microsoft.*` WinAppSDK APIs |
| 99 | +2. Read the documentation pages to identify which type matches the user's requirement. |
| 100 | +3. Once you know the type name, come back and use `-Action members` or `-Action enums` to get the exact local signatures. |
| 101 | + |
| 102 | +**3. Read the JSON to choose the right API** |
| 103 | + |
| 104 | +Read the file at the path(s) from the top results. The JSON has all types in that namespace — full members, signatures, parameters, return types, enumeration values. |
| 105 | + |
| 106 | +Read and decide which types and members fit the user's requirement. |
| 107 | + |
| 108 | +**4. Look up official documentation for context** |
| 109 | + |
| 110 | +The cache contains only signatures — no descriptions or usage guidance. For explanations, examples, and remarks, look up the type on Microsoft Learn: |
| 111 | + |
| 112 | +| Namespace prefix | Documentation base URL | |
| 113 | +|-----------------|----------------------| |
| 114 | +| `Windows.*` | `https://learn.microsoft.com/uwp/api/{fully.qualified.typename}` | |
| 115 | +| `Microsoft.*` (WinAppSDK) | `https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/{fully.qualified.typename}` | |
| 116 | + |
| 117 | +For example, `Microsoft.UI.Xaml.Controls.NavigationView` maps to: |
| 118 | +`https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationview` |
| 119 | + |
| 120 | +**5. Use the API knowledge to answer or write code** |
| 121 | + |
| 122 | +--- |
| 123 | + |
| 124 | +### Lookup — "I know the API, show me the details" |
| 125 | + |
| 126 | +You already know (or suspect) the type or namespace name. Go direct: |
| 127 | + |
| 128 | +```powershell |
| 129 | +# Get all members of a known type |
| 130 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action members -TypeName "Microsoft.UI.Xaml.Controls.NavigationView" |
| 131 | +
|
| 132 | +# Get enum values |
| 133 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action enums -TypeName "Microsoft.UI.Xaml.Visibility" |
| 134 | +
|
| 135 | +# List all types in a namespace |
| 136 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action types -Namespace "Microsoft.UI.Xaml.Controls" |
| 137 | +
|
| 138 | +# Browse namespaces |
| 139 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action namespaces -Filter "Microsoft.UI" |
| 140 | +``` |
| 141 | + |
| 142 | +If you need full detail beyond what `-Action members` shows, use `-Action search` to get the JSON file path, then read the JSON file directly. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +### Other Commands |
| 147 | + |
| 148 | +```powershell |
| 149 | +# List cached projects |
| 150 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action projects |
| 151 | +
|
| 152 | +# List packages for a project |
| 153 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action packages |
| 154 | +
|
| 155 | +# Show stats |
| 156 | +.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action stats |
| 157 | +``` |
| 158 | + |
| 159 | +> If only one project is cached, `-Project` is auto-selected. |
| 160 | +> If multiple projects exist, add `-Project <name>` (use `-Action projects` to see available names). |
| 161 | +> In scan mode, manifest names include a short hash suffix to avoid collisions; you can pass the base project name without the suffix if it's unambiguous. |
| 162 | +
|
| 163 | +## Search Scoring |
| 164 | + |
| 165 | +The search ranks type names and member names against your query: |
| 166 | + |
| 167 | +| Score | Match type | Example | |
| 168 | +|-------|-----------|---------| |
| 169 | +| 100 | Exact name | `Button` → `Button` | |
| 170 | +| 80 | Starts with | `Navigation` → `NavigationView` | |
| 171 | +| 60 | Contains | `Dialog` → `ContentDialog` | |
| 172 | +| 50 | PascalCase initials | `ASB` → `AutoSuggestBox` | |
| 173 | +| 40 | Multi-keyword AND | `navigation item` → `NavigationViewItem` | |
| 174 | +| 20 | Fuzzy character match | `NavVw` → `NavigationView` | |
| 175 | + |
| 176 | +Results are grouped by namespace. Higher-scored namespaces appear first. |
| 177 | + |
| 178 | +## Troubleshooting |
| 179 | + |
| 180 | +| Issue | Fix | |
| 181 | +|-------|-----| |
| 182 | +| "Cache not found" | Run `Update-WinMdCache.ps1` | |
| 183 | +| "Multiple projects cached" | Add `-Project <name>` | |
| 184 | +| "Namespace not found" | Use `-Action namespaces` to list available ones | |
| 185 | +| "Type not found" | Use fully qualified name (e.g., `Microsoft.UI.Xaml.Controls.Button`) | |
| 186 | +| Stale after NuGet update | Re-run `Update-WinMdCache.ps1` | |
| 187 | +| Cache in git history | Add `Generated Files/` to `.gitignore` | |
| 188 | + |
| 189 | +## References |
| 190 | + |
| 191 | +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — documentation for `Windows.*` namespaces |
| 192 | +- [Windows App SDK API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) — documentation for `Microsoft.*` WinAppSDK namespaces |
0 commit comments