WinMD API 搜索

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

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

即使在未还原或构建的全新克隆上，您仍然可以获得完整的平台 SDK + WinAppSDK 覆盖。

何时使用此技能

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

先决条件

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

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

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

# 仓库中的所有项目（首次运行推荐）
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1

# 单个项目
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1 -ProjectDir <项目文件夹>

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

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

索引内容

注意： 此缓存目录应位于 .gitignore 中 — 它是生成的，而不是源代码。

如何使用

根据情况选择以下路径：

探索 — “我不知道该用哪个 API”

用户用自己的话描述了某项能力。您需要找到正确的 API。

0. 确保缓存存在

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

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

将用户的日常用语映射到编程术语。尝试多种变体：

从简单的日常用语开始。如果结果不佳或不相关，请尝试更技术性的变体。

2. 运行搜索

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

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

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

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

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

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

阅读并决定哪些类型和成员符合用户的要求。

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

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

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

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

查找 — “我知道 API，显示详细信息”

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

# 获取已知类型的所有成员
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action members -TypeName "Microsoft.UI.Xaml.Controls.NavigationView"

# 获取枚举值
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action enums -TypeName "Microsoft.UI.Xaml.Visibility"

# 列出命名空间中的所有类型
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action types -Namespace "Microsoft.UI.Xaml.Controls"

# 浏览命名空间
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action namespaces -Filter "Microsoft.UI"

如果您需要超出 -Action members 显示的完整细节，请使用 -Action search 获取 JSON 文件路径，然后直接读取该 JSON 文件。

其他命令

# 列出已缓存的项目
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action projects

# 列出项目的包
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action packages

# 显示统计信息
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action stats

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

搜索评分

搜索会根据您的查询对类型名称和成员名称进行排名：

结果按命名空间分组。得分较高的命名空间显示在前面。

故障排除

参考

• Windows 平台 SDK API 参考 — Windows.* 命名空间的文档
• Windows 应用 SDK API 参考 — Microsoft.* WinAppSDK 命名空间的文档