winmd-api-search

WinMD API 搜索

此技能可帮助你为任何功能找到合适的 Windows API，并获取其完整详细信息。它会搜索来自以下来源的所有 WinMD 元数据的本地缓存：

• Windows Platform SDK — 所有 Windows.* WinRT API（始终可用，无需还原）
• WinAppSDK / WinUI — 作为基线捆绑在缓存生成器中（始终可用，无需还原）
• NuGet 包 — 已还原项目中任何包含 .winmd 文件的额外包
• 项目输出的 WinMD — 生成 .winmd 作为构建输出的类库（C++/WinRT、C#）

即使是在全新克隆、没有还原或构建的情况下，你仍可获得完整的 Platform SDK + WinAppSDK 覆盖范围。

何时使用此技能

• 用户想要构建某项功能，而你需要找到提供该能力的 API
• 用户询问“我该怎么做 X？”，其中 X 涉及某项平台功能（摄像头、文件、通知、传感器、AI 等）
• 在编写代码之前，你需要某个类型的确切方法、属性、事件或枚举值
• 你不确定某项 UI 或系统任务该使用哪个控件、类或接口

先决条件

• .NET SDK 8.0 或更高版本 — 构建缓存生成器所必需。如不可用，请从 dotnet.microsoft.com 安装。

缓存设置（首次使用前必需）

所有查询和搜索命令都从本地 JSON 缓存读取。你必须在运行任何查询之前生成缓存。

# All projects in the repo (recommended for first run)
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1

# Single project
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1 -ProjectDir <project-folder>

基线覆盖范围（Platform SDK + WinAppSDK）无需项目还原或构建。对于额外的 NuGet 包，项目需要 dotnet restore（这会生成 project.assets.json）或一个 packages.config 文件。

缓存存储在 Generated Files\winmd-cache\，按包+版本去重。

索引内容

来源	可用时机
Windows Platform SDK	始终（从本地 SDK 安装读取）
WinAppSDK（最新）	始终（作为基线捆绑在缓存生成器中）
WinAppSDK Runtime	当系统上安装时（通过 Get-AppxPackage 检测）
项目 NuGet 包	在 dotnet restore 之后或存在 packages.config 时
项目输出的 .winmd	在项目构建之后（生成 WinMD 的类库）

注意： 此缓存目录应加入 .gitignore — 它是生成产物，而非源文件。

如何使用

选择与当前情况相符的路径：

---

发现 — “我不知道该用哪个 API”

用户用自己的话描述一项能力。你需要找到正确的 API。

0. 确保缓存已存在

如果缓存尚未生成，请先运行 Update-WinMdCache.ps1 — 参见上文的缓存设置。

1. 将用户语言转换为 → 搜索关键词

把用户的日常语言映射为编程术语。尝试多种变体：

用户说	尝试的搜索关键词（按顺序）
“拍张照片”	camera, capture, photo, MediaCapture
“从磁盘加载”	file open, picker, FileOpen, StorageFile
“描述里面有什么”	image description, Vision, Recognition
“显示一个弹窗”	dialog, flyout, popup, ContentDialog
“拖放”	drag, drop, DragDrop
“保存设置”	settings, ApplicationData, LocalSettings

从简单的日常用词开始。如果结果较弱或不相关，再尝试更技术性的变体。

2. 运行搜索

.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action search -Query "<keyword>"

这会返回按排名排列的命名空间，其中包含最匹配的类型以及 JSON 文件路径。

如果结果分数较低（低于 60）或不相关，则退回到搜索在线文档：

1. 使用网络搜索在 Microsoft Learn 上找到正确的 API，例如：
   • site:learn.microsoft.com/uwp/api <capability keywords> 用于 Windows.* API
   • site:learn.microsoft.com/windows/windows-app-sdk/api/winrt <capability keywords> 用于 Microsoft.* WinAppSDK API
2. 阅读文档页面，确定哪个类型符合用户的需求。
3. 一旦知道类型名称，回来使用 -Action members 或 -Action enums 获取确切的本地签名。

3. 读取 JSON 以选择正确的 API

读取顶部结果中路径对应的文件。该 JSON 包含该命名空间中的所有类型 — 完整成员、签名、参数、返回类型、枚举值。

阅读并判断哪些类型和成员符合用户的需求。

4. 查阅官方文档以获取上下文

缓存中仅包含签名 — 没有描述或用法指导。如需解释、示例和备注，请在 Microsoft Learn 上查找该类型：

命名空间前缀	文档基础 URL
Windows.*	https://learn.microsoft.com/uwp/api/{fully.qualified.typename}
Microsoft.* (WinAppSDK)	https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/{fully.qualified.typename}

例如，Microsoft.UI.Xaml.Controls.NavigationView 映射到： https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationview

5. 使用 API 知识来回答或编写代码

---

查询 — “我知道这个 API，给我看细节”

你已经知道（或怀疑）类型或命名空间名称。直接执行：

# Get all members of a known type
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action members -TypeName "Microsoft.UI.Xaml.Controls.NavigationView"

# Get enum values
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action enums -TypeName "Microsoft.UI.Xaml.Visibility"

# List all types in a namespace
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action types -Namespace "Microsoft.UI.Xaml.Controls"

# Browse namespaces
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action namespaces -Filter "Microsoft.UI"

如果你需要 -Action members 所显示内容之外的完整细节，使用 -Action search 获取 JSON 文件路径，然后直接读取该 JSON 文件。

---

其他命令

# List cached projects
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action projects

# List packages for a project
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action packages

# Show stats
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action stats

如果只缓存了一个项目，-Project 会自动选择。 如果存在多个项目，请添加 -Project <name>（使用 -Action projects 查看可用名称）。 在扫描模式下，清单名称会包含一个短哈希后缀以避免冲突；如果无歧义，你可以传入不带后缀的基础项目名称。

搜索评分

搜索会将类型名称和成员名称与你的查询进行排名匹配：

分数	匹配类型	示例
100	名称完全匹配	Button → Button
80	以……开头	Navigation → NavigationView
60	包含	Dialog → ContentDialog
50	PascalCase 首字母	ASB → AutoSuggestBox
40	多关键词 AND	navigation item → NavigationViewItem
20	模糊字符匹配	NavVw → NavigationView

结果按命名空间分组。分数较高的命名空间会排在前列。

故障排除

问题	修复
“未找到缓存”	运行 Update-WinMdCache.ps1
“多个项目已缓存”	添加 -Project <name>
“未找到命名空间”	使用 -Action namespaces 列出可用命名空间
“未找到类型”	使用完全限定名（例如 Microsoft.UI.Xaml.Controls.Button）
NuGet 更新后数据陈旧	重新运行 Update-WinMdCache.ps1
缓存出现在 git 历史中	将 Generated Files/ 添加到 .gitignore

参考资料

• Windows Platform SDK API 参考 — Windows.* 命名空间的文档
• Windows App SDK API 参考 — Microsoft.* WinAppSDK 命名空间的文档