Pesquisa de API WinMD

Esta habilidade ajuda você a encontrar a API do Windows certa para qualquer funcionalidade e obter seus detalhes completos. Ela pesquisa um cache local de todos os metadados WinMD de:

• Windows Platform SDK — todas as APIs Windows.* WinRT (sempre disponíveis, sem necessidade de restauração)
• WinAppSDK / WinUI — incluído como base no gerador de cache (sempre disponível, sem necessidade de restauração)
• Pacotes NuGet — quaisquer pacotes adicionais em projetos restaurados que contenham arquivos .winmd
• WinMD de saída do projeto — bibliotecas de classes (C++/WinRT, C#) que produzem .winmd como saída de compilação

Mesmo em um clone novo, sem restauração ou compilação, você ainda obtém cobertura completa do Platform SDK + WinAppSDK.

Quando Usar Esta Habilidade

• O usuário quer criar um recurso e você precisa encontrar qual API fornece essa funcionalidade
• O usuário pergunta "como faço X?" onde X envolve um recurso da plataforma (câmera, arquivos, notificações, sensores, IA, etc.)
• Você precisa dos métodos, propriedades, eventos ou valores de enumeração exatos de um tipo antes de escrever o código
• Você não tem certeza de qual controle, classe ou interface usar para uma tarefa de UI ou de sistema

Pré-requisitos

• .NET SDK 8.0 ou posterior — necessário para compilar o gerador de cache. Instale em dotnet.microsoft.com se não estiver disponível.

Configuração do Cache (Obrigatório Antes do Primeiro Uso)

Todos os comandos de consulta e pesquisa leem de um cache JSON local. Você deve gerar o cache antes de executar quaisquer consultas.

# 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>

Nenhuma restauração ou compilação de projeto é necessária para cobertura básica (Platform SDK + WinAppSDK). Para pacotes NuGet adicionais, o projeto precisa de dotnet restore (que gera project.assets.json) ou de um arquivo packages.config.

O cache é armazenado em Generated Files\winmd-cache\, deduplicado por pacote+versão.

O que é indexado

Observação: Este diretório de cache deve estar em .gitignore — ele é gerado, não é código fonte.

Como Usar

Escolha o caminho que corresponde à situação:

Descobrir — "Não sei qual API usar"

O usuário descreve uma funcionalidade com suas próprias palavras. Você precisa encontrar a API certa.

0. Certifique-se de que o cache existe

Se o cache ainda não foi gerado, execute Update-WinMdCache.ps1 primeiro — veja Configuração do Cache acima.

1. Traduza a linguagem do usuário → palavras-chave de pesquisa

Mapeie a linguagem cotidiana do usuário para termos de programação. Tente várias variações:

Comece com palavras simples do dia a dia. Se os resultados forem fracos ou irrelevantes, tente a variação mais técnica.

2. Execute pesquisas

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

Isso retorna namespaces classificados com os principais tipos correspondentes e o caminho do arquivo JSON.

Se os resultados tiverem pontuações baixas (abaixo de 60) ou forem irrelevantes, recorra à pesquisa na documentação online:

1. Use a pesquisa na web para encontrar a API certa no Microsoft Learn, por exemplo:
   • site:learn.microsoft.com/uwp/api <capability keywords> para APIs de Windows.*
   • site:learn.microsoft.com/windows/windows-app-sdk/api/winrt <capability keywords> para APIs de Microsoft.* WinAppSDK
2. Leia as páginas de documentação para identificar qual tipo corresponde ao requisito do usuário.
3. Assim que souber o nome do tipo, volte e use -Action members ou -Action enums para obter as assinaturas locais exatas.

…