Get started building an app with Windows AI APIs

1. Confirm that your device meets the hardware requirements for the Windows AI APIs you plan to use. Most APIs require a Copilot+ PC with an NPU (we recommend the devices listed in the Copilot+ PCs developer guide). Some APIs also support GPU or CPU execution on non-Copilot+ devices — see the supported hardware table for details.

2. Run the following command in Windows Terminal.

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

   This runs a WinGet Configuration file that performs the following tasks:

   • Checks for minimum OS version.
   • Enables Developer Mode.
   • Installs Visual Studio Community Edition with WinUI and other required workloads.
   • Installs the Windows App SDK.

• Confirm that your device meets the hardware requirements for the Windows AI APIs you plan to use. Most APIs require a Copilot+ PC with an NPU (we recommend the devices listed in the Copilot+ PCs developer guide). Some APIs also support GPU or CPU execution — see the supported hardware table for details.
• Install Windows 11 Insider Preview build 26120.3073 (Dev and Beta Channels), or later (to check your OS version, run winver from Windows Search).
  • For Phi Silica on GPU: Use Windows Insider Experimental Channel build 26300.8553 or later.
• Enable Developer Mode in Settings > System > For developers > Developer Mode. This is required for Phi Silica on GPU.
• Install Visual Studio with the specific workloads and components for developing with WinUI and the Windows App SDK. For more details, see Required workloads and components.
• Use Windows App SDK version 2.2.2-experimental9 (June 2026 Experimental) or later for Phi Silica on GPU.

1. In Visual Studio, create a new WinUI project by selecting the Blank App, Packaged (WinUI 3 in Desktop) template.

   

2. In Solution Explorer, right-click the project node, select Properties > Application > General, and ensure that the target framework is set to .NET 8.0, and the target OS is set to 10.0.22621 or later.

   

3. Edit the Package.appxmanifest file (right click and select View code) and add the following snippets.

   • The systemAIModels capability to the <Capabilities> node:

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

   • The systemai namespace specifier to "IgnorableNamespaces" in the <Package> node:

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

   • The max version tested in the TargetDeviceFamily element of the <Dependencies> node needs to be at least 10.0.26226.0:

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

4. Add the following to your .waproj, .csproj, or .vcxproj file. This step is necessary to ensure visual studio doesn't override the max version tested.

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

5. Right-click the project node and select Manage NuGet Packages....

6. In NuGet Package Manager, check the Include prerelease checkbox, and select Windows App SDK version 1.8.250410001-experimental1. Click Install or Update.

   

7. Ensure that your build configuration is set to the appropriate architecture for your device (for example, ARM64 or x64).

   

8. Build and run your app.

9. If the app launches succesfully, then continue to Add your first AI API. Otherwise, see Troubleshooting.

1. In Visual Studio, create a new WPF project by selecting the WPF Application template.

2. In Solution Explorer, right-click the project node and select Edit Project File to open as XML. Replace everything inside <PropertyGroup> with the following:

   <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. Edit the Package.appxmanifest file (right click and select View code) and add the following snippets.

   • The systemAIModels capability to the <Capabilities> node:

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

   • The systemai namespace specifier to "IgnorableNamespaces" in the <Package> node:

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

   • The max version tested in the TargetDeviceFamily element of the <Dependencies> node needs to be at least 10.0.26226.0:

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

4. Add the following to your .waproj, .csproj, or .vcxproj file. This step is necessary to ensure visual studio doesn't override the max version tested.

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

5. In Solution Explorer, right-click the Dependencies node and select Manage Nuget Packages....

6. In NuGet Package Manager, check the Include prerelease checkbox, and select Windows App SDK version 1.8.250410001-experimental1. Click Install or Update.

7. Build and run your app.

8. If the app launches succesfully, then continue to Add your first AI API. Otherwise, see Troubleshooting.

For more info, see Configure your WPF project for Windows App SDK support.

1. In Visual Studio, create a new WinForms project by selecting the Windows Forms App template.

2. In Solution Explorer, right-click the project node > Edit Project File to open as XML. Replace everything inside <PropertyGroup> with the following:

   <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. Edit the Package.appxmanifest file (right click and select View code) and add the following snippets.

   • The systemAIModels capability to the <Capabilities> node:

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

   • The systemai namespace specifier to "IgnorableNamespaces" in the <Package> node:

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

   • The max version tested in the TargetDeviceFamily element of the <Dependencies> node needs to be at least 10.0.26226.0:

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

4. Add the following to your .waproj, .csproj, or .vcxproj file. This step is necessary to ensure visual studio doesn't override the max version tested.

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

5. In Solution Explorer, right-click the Dependencies node > Manage Nuget Packages....

6. In NuGet Package Manager > Browse, check Include prerelease, and and select Windows App SDK version 1.8.250410001-experimental1. Click Install or Update.

7. Build and run your app.

8. If the app launches succesfully, then continue to Add your first AI API. Otherwise, see Troubleshooting.

For more info, see Configure your WinForms project for Windows App SDK support.

1. Create a MAUI project by following the instructions at Build your first .NET MAUI app.

2. In Solution Explorer, right-click the project node > Edit Project File to open as XML.

3. At the bottom of the project file, add these lines to reference the correct Microsoft.WindowsAppSDK package version (when compiling for the Windows platform):

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

   Note

   While you can click the project node and select the Manage NuGet Packages... option to add the required package, if your app is also building for other platforms, such as Android and iOS, you still need to edit the project file to condition the package reference for Windows-only builds.

4. Add the following to your .waproj, .csproj, or .vcxproj file. This step is necessary to ensure visual studio doesn't override the max version tested.

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

5. In Solution Explorer, right-click the project node, select Properties, and ensure that the Target Windows Framework is set to 10.0.22621 or later.

6. Edit the Package.appxmanifest file (right click and select View code) and add the following snippets.

   • The systemAIModels capability to the <Capabilities> node:

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

   • The systemai namespace specifier to "IgnorableNamespaces" in the <Package> node:

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

   • The max version tested in the TargetDeviceFamily element of the <Dependencies> node needs to be at least 10.0.26226.0:

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

7. Build and run your app.

8. If the app launches succesfully, then continue to Add your first AI API. Otherwise, see Troubleshooting.

1. In MainWindow.xaml, add a TextBlock to display the LanguageModel response.

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

2. At the top of MainWindow.xaml.cs, add the following using Microsoft.Windows.AI directive.

   using Microsoft.Windows.AI; 
   

3. In MainWindow.xaml.cs, replace the MainWindow class with the following code, which confirms the LanguageModel is available and then submits a prompt asking for the model to respond with the molecular formula of glucose.

   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. Build and run the app.

5. The formula for glucose should appear in the text block.

1. In MainWindow.xaml, add a TextBlock to display the LanguageModel response.

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

2. At the top of MainWindow.xaml.cs, add the following using Microsoft.Windows.AI directive.

   using Microsoft.Windows.AI; 
   

3. In MainWindow.xaml.cs, replace the MainWindow class with the following code, which confirms the LanguageModel is available and then submits a prompt asking for the model to respond with the molecular formula of glucose.

   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. Build and run the app.

5. The formula for glucose should appear in the text block.

1. In the Windows Forms Designer, drag a Label onto the page, and name it OutputLabel.

2. At the top of Form1.cs, add the following using Microsoft.Windows.AI directive.

   using Microsoft.Windows.AI; 
   

3. In Form.cs, replace the Form class with the following code, which confirms the LanguageModel is available and then submits a prompt asking for the model to respond with the molecular formula of glucose.

   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. Build and run the app.

5. The formula for glucose should appear in the text block.

See Invoke platform code for details on adding platform-specific code to a MAUI app.

For this example, we use the partial classes and partial methods approach to put the Windows code in the Platform\Windows folder.

1. In MainPage.xaml.cs, add a partial method definition as partial void ChangeLanguageModelAvailability(); and call that partial method from the OnCounterClicked handler for the CounterBtn button created by the .NET MAUI App template.

2. In Solution Explorer, expand Platforms, right-click on Windows, select Add > Class…, type the name MainPage.cs, and click Add.

3. The new MainPage.cs should be shown in the editor window. Switch back to MainPage.xaml.cs to copy its namespace line.

4. Switch back to the new MainPage.cs and replace its namespace line with the line from MainPage.xaml.cs. This is to make the Platform\Windows class a partial extension of the base MainPage class.

5. To complete making MainPage.cs an extension, replace internal on the class declaration with partial.

6. Add the following code to the ChangeLanguageModelAvailability partial method defined in step 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. Run the app again, click the Click me button, and observe the output in the Visual Studio debug output pane.