winmd-api-search

WinMD API Search

這項 Skill 能協助你為任何功能找到合適的 Windows API 并取得其完整詳細資訊。它會搜尋包含下列來源所有 WinMD 元資料（metadata）的本機快取：

• Windows Platform SDK — 所有 Windows.* WinRT API（隨時可用，無需執行還原）
• WinAppSDK / WinUI — 已作為基準預先打包於快取產生器中（隨時可用，無需執行還原）
• NuGet 套件 — 已還原專案中任何包含 .winmd 檔案的附加套件
• 專案輸出的 WinMD — 建置後會產生 .winmd 的類別庫（C++/WinRT、C#）

即使是在剛複製（clone）下來、尚未執行還原或建置的全新專案中，你依然能享有完整的 Platform SDK + WinAppSDK API 涵蓋範圍。

何時使用此 Skill

• 使用者想要開發某項功能，而你需要找出哪一個 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 <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. 使用 Web 搜尋在 Microsoft Learn 上尋找合適的 API，例如：
   • 針對 Windows.* API：site:learn.microsoft.com/uwp/api <功能關鍵字>
   • 針對 Microsoft.* WinAppSDK API：site:learn.microsoft.com/windows/windows-app-sdk/api/winrt <功能關鍵字>
2. 閱讀文件頁面以確認哪一個型別符合使用者的需求。
3. 一旦得知型別名稱後，返回此處使用 -Action members 或 -Action enums 來取得精確的本機簽章。

3. 讀取 JSON 以選擇合適的 API

讀取最符合結果中的檔案路徑。該 JSON 包含了該命名空間下的所有型別——完整的成員、簽章、參數、回傳型別與列舉值。

研讀內容並判斷哪些型別與成員符合使用者的需求。

4. 查閱官方文件以取得上下文資訊

快取僅包含語法簽章，不包含說明文字或使用指南。若需詳細說明、範例和備註，請在 Microsoft Learn 上查詢該型別：

命名空間前綴	文件 Base 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 名稱，請顯示詳細資訊」

若你已知（或推測出）型別或命名空間名稱，可直接查詢：

# 取得已知型別的所有成員
.\.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 <name>（可使用 -Action projects 檢視可用名稱）。
在掃描模式下，清單名稱會包含短雜湊（hash）字尾以避免命名衝突；若無歧義，你可以傳入不帶字尾的基底專案名稱。

搜尋計分機制

搜尋演算法會針對你的查詢字串，對型別名稱與成員名稱進行比分比對與排序：

比分	比對類型	範例
100	完全相同	Button → Button
80	開頭符合	Navigation → NavigationView
60	包含字串	Dialog → ContentDialog
50	PascalCase 首字母	ASB → AutoSuggestBox
40	多關鍵字 AND 邏輯	navigation item → NavigationViewItem
20	模糊字元比對	NavVw → NavigationView

搜尋結果會依命名空間進行分組，得分較高的命名空間會排在前面。

疑難排解

問題	解法
「Cache not found」（找不到快取）	執行 Update-WinMdCache.ps1
「Multiple projects cached」（存在多個專案快取）	加上 -Project <name> 參數
「Namespace not found」（找不到命名空間）	使用 -Action namespaces 列出所有可用的命名空間
「Type not found」（找不到型別）	使用完整修飾名稱（例如 Microsoft.UI.Xaml.Controls.Button）
更新 NuGet 後快取未更新	重新執行 Update-WinMdCache.ps1
快取誤加入 git 歷史紀錄	將 Generated Files/ 加入 .gitignore

參考資料

• Windows Platform SDK API 參考 — Windows.* 命名空間的文件
• Windows App SDK API 參考 — Microsoft.* WinAppSDK 命名空間的文件