Introdução à criação de um aplicativo com a IA do Windows APIs

1. Confirme se o dispositivo atende aos requisitos de hardware do Windows IA APIs que você planeja usar. A maioria dos APIs exige um PC Copilot+ com uma NPU (recomendamos os dispositivos listados no guia do desenvolvedor de PCs Copilot+). Alguns APIs também oferecem suporte à execução em GPU ou CPU em dispositivos sem Copilot+ — consulte a tabela de hardware compatível para obter detalhes.

2. Execute o comando a seguir no Terminal do Windows.

   winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/learn_wcr.winget
   

   Isso executa um arquivo de Configuração do WinGet que executa as seguintes tarefas:

   • Verifica a versão mínima do sistema operacional.
   • Habilita o modo de desenvolvedor.
   • Instala o Visual Studio Community Edition com WinUI e outras cargas de trabalho necessárias.
   • Instala o SDK do Aplicativo do Windows.

• Confirme se o dispositivo atende aos requisitos de hardware do Windows IA APIs que você planeja usar. A maioria dos APIs exige um PC Copilot+ com uma NPU (recomendamos os dispositivos listados no guia do desenvolvedor de PCs Copilot+). Alguns APIs também dão suporte à execução de GPU ou CPU – consulte a tabela de hardware com suporte para obter detalhes.
• Instale o Windows 11 Insider Preview build 26120.3073 (Canais de Desenvolvimento e Beta) ou posterior (para verificar a versão do sistema operacional, execute winver na Pesquisa do Windows).
  • Para o Phi Silica na GPU: Use a compilação 26300.8553 ou posterior do Windows Insider Experimental Channel.
• Habilitar o Modo de Desenvolvedor em Configurações>Sistema>para desenvolvedores>Modo de Desenvolvedor. Isso é necessário para Phi Silica na GPU.
• Instale o Visual Studio com as cargas de trabalho e os componentes específicos para o desenvolvimento com o WinUI e o SDK do Aplicativo do Windows. Para obter mais detalhes, consulte cargas de trabalho e componentes necessários.
• Use o SDK do Aplicativo Windows versão 2.2.2-experimental9 (Experimental de junho de 2026) ou posterior para Phi Silica em GPU.

1. No Visual Studio, crie um novo projeto WinUI selecionando o modelo Aplicativo em branco, empacotado (WinUI 3 na Área de trabalho).

   

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto, selecione Propriedades>Aplicativo>Geral e verifique se o framework de destino está definido como .NET 8.0 e o sistema operacional de destino está definido como 10.0.22621 ou posterior.

   

3. Edite o arquivo Package.appxmanifest (clique com o botão direito do mouse e selecione Exibir código) e adicione os snippets a seguir.

   • A systemAIModels capacidade do nó <Capabilities>:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • O especificador de namespace systemai para "IgnorableNamespaces" no nó <Package>:

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • A versão máxima testada no elemento TargetDeviceFamily do nó <Dependencies> precisa ser, no mínimo, 10.0.26226.0:

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. Adicione o seguinte ao arquivo .waproj, .csproj ou .vcxproj. Esta etapa é necessária para garantir que o Visual Studio não substitua a versão máxima testada.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. Clique com o botão direito do mouse no nó do projeto e selecione Gerenciar Pacotes NuGet....

6. No Gerenciador de Pacotes NuGet, marque a caixa de seleção Incluir pré-lançamento e selecione o SDK do Aplicativo do Windows versão 1.8.250410001-experimental1. Clique em Instalar ou Atualizar.

   

7. Verifique se a configuração de build está definida como a arquitetura apropriada para seu dispositivo (por exemplo, ARM64 ou x64).

   

8. Crie e execute seu aplicativo.

9. Se o aplicativo for iniciado com sucesso, continue para Adicionar sua primeira IA API. Caso contrário, consulte solução de problemas.

1. No Visual Studio, crie um novo projeto do WPF selecionando o modelo de aplicativo WPF .

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Editar Arquivo de Projeto para abrir como XML. Substitua tudo dentro <PropertyGroup> pelo seguinte:

   <OutputType>WinExe</OutputType>
   <TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   <Nullable>enable</Nullable>
   <UseWPF>true</UseWPF>
   <ImplicitUsings>enable</ImplicitUsings>
   <WindowsPackageType>None</WindowsPackageType>
   

3. Edite o arquivo Package.appxmanifest (clique com o botão direito do mouse e selecione Exibir código) e adicione os snippets a seguir.

   • A systemAIModels capacidade do nó <Capabilities>:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • O especificador de namespace systemai para "IgnorableNamespaces" no nó <Package>:

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • A versão máxima testada no elemento TargetDeviceFamily do nó <Dependencies> precisa ser, no mínimo, 10.0.26226.0:

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. Adicione o seguinte ao arquivo .waproj, .csproj ou .vcxproj. Esta etapa é necessária para garantir que o Visual Studio não substitua a versão máxima testada.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências e selecione Gerenciar Pacotes Nuget....

6. No Gerenciador de Pacotes NuGet, marque a caixa de seleção Incluir pré-lançamento e selecione o SDK do Aplicativo do Windows versão 1.8.250410001-experimental1. Clique em Instalar ou Atualizar.

7. Crie e execute seu aplicativo.

8. Se o aplicativo for iniciado com sucesso, continue para Adicionar sua primeira IA API. Caso contrário, consulte solução de problemas.

Para obter mais informações, consulte Configurar seu projeto do WPF para suporte ao SDK do Aplicativo do Windows.

1. No Visual Studio, crie um novo projeto WinForms selecionando o modelo de aplicativo do Windows Forms .

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó >do projeto Editar Arquivo de Projeto para abrir como XML. Substitua tudo dentro <PropertyGroup> pelo seguinte:

   <OutputType>WinExe</OutputType>
   <TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   <Nullable>enable</Nullable>
   <UseWindowsForms>true</UseWindowsForms>
   <ImplicitUsings>enable</ImplicitUsings>
   <WindowsPackageType>None</WindowsPackageType>
   

3. Edite o arquivo Package.appxmanifest (clique com o botão direito do mouse e selecione Exibir código) e adicione os snippets a seguir.

   • A systemAIModels capacidade do nó <Capabilities>:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • O especificador de namespace systemai para "IgnorableNamespaces" no nó <Package>:

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • A versão máxima testada no elemento TargetDeviceFamily do nó <Dependencies> precisa ser, no mínimo, 10.0.26226.0:

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

4. Adicione o seguinte ao arquivo .waproj, .csproj ou .vcxproj. Esta etapa é necessária para garantir que o Visual Studio não substitua a versão máxima testada.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências>Gerenciar Pacotes Nuget....

6. No Gerenciador de Pacotes NuGet>, na seção Procurar, marque Incluir pré-lançamento, e selecione a versão 1.8.250410001-experimental1 do SDK do Aplicativo do Windows. Clique em Instalar ou Atualizar.

7. Crie e execute seu aplicativo.

8. Se o aplicativo for iniciado com sucesso, continue para Adicionar sua primeira IA API. Caso contrário, consulte solução de problemas.

Para obter mais informações, consulte Configurar seu projeto WinForms para suporte ao SDK do Aplicativo do Windows.

1. Crie um projeto MAUI seguindo as instruções em Criar seu primeiro aplicativo MAUI do .NET.

2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó >do projeto Editar Arquivo de Projeto para abrir como XML.

3. Na parte inferior do arquivo de projeto, adicione estas linhas para fazer referência à versão correta do pacote Microsoft.WindowsAppSDK (ao compilar para a plataforma Windows):

   <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
      <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.250410001-experimental1"/> 
   </ItemGroup>
   

   Observação

   Embora você possa clicar no nó do projeto e selecionar a opção Gerenciar Pacotes NuGet... para adicionar o pacote necessário, se seu aplicativo também estiver sendo criado para outras plataformas, como Android e iOS, você ainda precisará editar o arquivo de projeto para condicioná-lo à referência de pacote para builds somente do Windows.

4. Adicione o seguinte ao arquivo .waproj, .csproj ou .vcxproj. Esta etapa é necessária para garantir que o Visual Studio não substitua a versão máxima testada.

   <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
   <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
   

5. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto, selecione Propriedades e verifique se o Windows Framework de destino está definido como 10.0.22621 ou posterior.

6. Edite o arquivo Package.appxmanifest (clique com o botão direito do mouse e selecione Exibir código) e adicione os snippets a seguir.

   • A systemAIModels capacidade do nó <Capabilities>:

     <Capabilities>
        <systemai:Capability Name="systemAIModels"/>
     </Capabilities>
     

   • O especificador de namespace systemai para "IgnorableNamespaces" no nó <Package>:

     xmlns:systemai="http://schemas.microsoft.com/appx/manifest/systemai/windows10"
     IgnorableNamespaces="uap rescap systemai"
     

   • A versão máxima testada no elemento TargetDeviceFamily do nó <Dependencies> precisa ser, no mínimo, 10.0.26226.0:

     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.26226.0" />
     

7. Crie e execute seu aplicativo.

8. Se o aplicativo for iniciado com sucesso, continue para Adicionar sua primeira IA API. Caso contrário, consulte solução de problemas.

1. Em MainWindow.xaml, adicione um TextBlock para exibir a resposta LanguageModel .

   <TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
   

2. Na parte superior do MainWindow.xaml.cs, adicione a diretiva a seguir using Microsoft.Windows.AI .

   using Microsoft.Windows.AI; 
   

3. Em MainWindow.xaml.cs, substitua a classe MainWindow pelo código a seguir, que confirma que o LanguageModel está disponível e, em seguida, envia um prompt solicitando que o modelo responda com a fórmula molecular de glicose.

   public sealed partial class MainWindow : Window
   {
       public MainWindow()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputText.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = 
              await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula of glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputText.Text = result.Response;
       }
   }
   

4. Compile e execute o aplicativo.

5. A fórmula para glicose deve aparecer no bloco de texto.

1. Em MainWindow.xaml, adicione um TextBlock para exibir a resposta LanguageModel .

   <TextBlock x:Name="OutputText" HorizontalAlignment="Center" VerticalAlignment="Center" />
   

2. Na parte superior do MainWindow.xaml.cs, adicione a diretiva a seguir using Microsoft.Windows.AI .

   using Microsoft.Windows.AI; 
   

3. Em MainWindow.xaml.cs, substitua a classe MainWindow pelo código a seguir, que confirma que o LanguageModel está disponível e envia um prompt solicitando que o modelo responda com a fórmula molecular de glicose.

   public sealed partial class MainWindow : Window
   {
       public MainWindow()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputText.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula for glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputText.Text = result.Response;
       }
   }
   

4. Compile e execute o aplicativo.

5. A fórmula para glicose deve aparecer no bloco de texto.

1. No Designer de Formulários do Windows, arraste um rótulo para a página e nomeie-o OutputLabel.

2. Na parte superior do Form1.cs, adicione a diretiva a seguir using Microsoft.Windows.AI .

   using Microsoft.Windows.AI; 
   

3. Em Form.cs, substitua a classe Form pelo código a seguir, que confirma que o LanguageModel está disponível e envia um prompt solicitando que o modelo responda com a fórmula molecular de glicose.

   public partial class Form1 : Window
   {
       public Form1()
       {
           this.InitializeComponent();
           InitAI();
       }
   
       private async void InitAI()
       {
           OutputLabel.Text = "Loading..";
   
           if (LanguageModel.GetReadyState() == AIFeatureReadyState.EnsureNeeded)
           {
               var result = await LanguageModel.EnsureReadyAsync();
               if (result.Status != PackageDeploymentStatus.CompletedSuccess)
               {
                   throw new Exception(result.ExtendedError().Message);
               }
           }            
   
           using LanguageModel languageModel = await LanguageModel.CreateAsync();
   
           string prompt = "Provide the molecular formula for glucose.";
           var result = await languageModel.GenerateResponseAsync(prompt);
           OutputLabel.Text = result.Response;
       }
   }
   

4. Compile e execute o aplicativo.

5. A fórmula para glicose deve aparecer no bloco de texto.

Consulte o código da plataforma Invoke para obter detalhes sobre como adicionar código específico da plataforma a um aplicativo MAUI.

Para este exemplo, usamos as classes parciais e a abordagem de métodos parciais para colocar o código do Windows na pasta Platform\Windows.

1. Em MainPage.xaml.cs, adicione uma definição de método parcial como partial void ChangeLanguageModelAvailability(); e chame esse método parcial a partir do manipulador OnCounterClicked para o botão CounterBtn criado pelo modelo de aplicativo .NET MAUI.

2. No Gerenciador de Soluções, expanda Plataformas, clique com o botão direito do mouse no Windows, selecione Adicionar>Classe..., digite o nome MainPage.cs e clique em Adicionar.

3. O novo MainPage.cs deve ser mostrado na janela do editor. Retorne para MainPage.xaml.cs para copiar a linha do namespace.

4. Volte para o novo MainPage.cs e substitua sua linha de namespace pela linha de MainPage.xaml.cs. Isso é para tornar a classe Platform\Windows uma extensão parcial da classe Base MainPage .

5. Para concluir a criação MainPage.cs uma extensão, substitua internal na declaração de classe por partial.

6. Adicione o código a seguir ao método parcial ChangeLanguageModelAvailability definido na etapa 1.

   partial void ChangeLanguageModelAvailability() 
   { 
      try 
      { 
         AIFeatureReadyState readyState = Microsoft.Windows.AI.LanguageModel.GetReadyState(); 
         System.Diagnostics.Debug.WriteLine($"LanguageModel.GetReadyState: {readyState}"); 
      } 
      catch (Exception e) 
      { 
         System.Diagnostics.Debug.WriteLine($"LanguageModel is not available: {e}"); 
      } 
   }
   

7. Execute o aplicativo novamente, clique no botão Clique aqui e observe a saída no painel de saída de depuração do Visual Studio.