Get started building an app with Windows Copilot Runtime APIs

1. Download the Windows Copilot Runtime configuration .winget file from the winget-dsc GitHub repo (click ... > Download from the top of the page).

2. Next, double-click the file to open it with the Windows Package Manager client (or launch Terminal, navigate to the folder where you downloaded configuration.winget, and run the file using winget configure configuration.winget).

   This 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 is a Copilot+ PC (we recommend the devices listed in the Copilot+ PCs developer duide).
• Install Windows 11 Insider Preview build 26120.3073 (Dev and Beta Channels), or later (to check your OS version, run winver in Windows Search).
• Enable Developer Mode in Settings > System > For developers > Developer Mode.
• 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.

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 the <Package> node:

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

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

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

   

6. Ensure that your build configuration is set to ARM64.

   

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 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 the <Package> node:

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

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

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

6. Build and run your app.

7. 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 the <Package> node:

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

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

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

6. Build and run your app.

7. 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 clicking the project node and selecting the Manage NuGet Packages.. option can be used to add the required package, the project file still needs to be edited to condition the package reference for just Windows builds if your app is also building for other platforms such as Android and iOS.

4. 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.

5. 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 the <Package> node:

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

6. Build and run your app.

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

Add your first AI API

When implementing an AI feature using Windows Copilot Runtime APIs, your app should first check for the availability of the AI model that supports that feature.

The following snippet shows how to check for model availability and generate a response.

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.Generative directive.

   using Microsoft.Windows.AI.Generative; 
   

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.Generative directive.

   using Microsoft.Windows.AI.Generative; 
   

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 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.Generative directive.

   using Microsoft.Windows.AI.Generative; 
   

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.

• In MainPage.xaml.cs, add a partial method definition as partial void ChangeLanguageModelAvailability(); and call that partial method at the beginning of the OnCounterClicked method.

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

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

• 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.

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

• Add a definition of the partial ChangeLanguageModelAvailability method defined earlier.

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

1. Run the app again, click the "Click me" button, and observe the output in the Visual Studio debug output pane.