Merge pull request #1145 from MicrosoftDocs/main

Auto Publish – main to live - 2026-03-19 05:00 UTC

Author: learn-build-service-prod[bot]

docs/TOC.yml

@@ -3,6 +3,8 @@ items:
       items:
       - name: Overview
         href: overview.md
+      - name: Choose your AI solution
+        href: ./windows-ai-comparison.md
       - name: Ready-to-use AI
         items:
         - name: Large Language Models
@@ -1138,7 +1140,5 @@ items:
           - name: Release notes
             href: windows-ml/release-notes.md
             items:
-            - name: Compare AI solutions
-              href: ./windows-ai-comparison.md
             - name: FAQ
               href: windows-ml/faq.yml

docs/new-windows-ml/distributing-your-app.md

@@ -1,25 +1,21 @@
 ---
 title: Deploy your app that uses Windows ML
 description: Learn how to deploy your app that uses Windows Machine Learning (ML).
-ms.date: 07/07/2025
+ms.date: 03/10/2026
 ms.topic: concept-article
 ---
 
 # Deploy your app that uses Windows ML
 
-When you're ready to distribute your C# or C++ app that uses Windows ML, you need to ensure that the Windows App SDK framework is properly deployed to your users' devices. The Windows ML runtime is distributed as part of the Windows App SDK.
+Windows ML is deployed like any other Windows App SDK component, supporting both framework-dependent and self-contained deployment. See the [Windows App SDK deployment overview](/windows/apps/package-and-deploy/deploy-overview) for more details about the deployment options in Windows App SDK.
 
-## Supported deployment options for Windows ML
-
-Windows ML supports both the framework-dependent and the self-contained deployment options in Windows App SDK. See the [Windows App SDK deployment overview](/windows/apps/package-and-deploy/deploy-overview) for more details about the deployment options in Windows App SDK.
-
-### Framework-dependent: ✅ Supported
+## Framework-dependent
 
 Your app depends on the Windows App SDK runtime and/or framework package being present on the target machine. Framework-dependent deployment is the default deployment mode of the Windows App SDK for its efficient use of machine resources and serviceability. See [Deployment architecture and overview for framework-dependent apps](/windows/apps/windows-app-sdk/deployment-architecture) for more details.
 
-### Self-contained: ✅ Supported
+## Self-contained
 
-With the GA release of Windows ML, use of the self-contained deployment option in Windows App SDK is now supported when using Windows ML. See [Deployment guide for self-contained apps](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps) for more details.
+Your app carries the Windows App SDK dependencies with it. See [Deployment guide for self-contained apps](/windows/apps/package-and-deploy/self-contained-deploy/deploy-self-contained-apps) for more details.
 
 In self-contained mode, ONNX Runtime binaries are deployed alongside your application:
 

docs/new-windows-ml/get-started.md

@@ -21,28 +21,90 @@ If you're not already familiar with the ONNX Runtime, we suggest reading the [ON
 * .NET 6 or greater
 * Targeting a Windows 10-specific TFM like `net6.0-windows10.0.19041.0` or greater
 
-### [C++](#tab/cppwinrt)
+### [C++/WinRT](#tab/cppwinrt)
 
 C++20 or later.
 
+### [C/C++](#tab/c)
+
+* Visual Studio 2022 with C++ workload (includes the C compiler)
+* CMake 3.21 or later
+
 ### [Python](#tab/python)
 
 Python versions 3.10 to 3.13, on x64 and ARM64 devices.
 
 ---
 
-## Step 1: Install or update the Windows App SDK
-
-Windows ML is included in [Windows App SDK 1.8.1 or greater](/windows/apps/windows-app-sdk/stable-channel).
+## Step 1: Install or update Windows ML
 
 ### [C#](#tab/csharp)
 
+Windows ML is included in [Windows App SDK 1.8.1 or greater](/windows/apps/windows-app-sdk/stable-channel).
+
 See [use the Windows App SDK in an existing project](/windows/apps/windows-app-sdk/use-windows-app-sdk-in-existing-project) for how to add the Windows App SDK to your project, or if you're already using Windows App SDK, update your packages.
 
-### [C++](#tab/cppwinrt)
+### [C++/WinRT](#tab/cppwinrt)
+
+Windows ML is included in [Windows App SDK 1.8.1 or greater](/windows/apps/windows-app-sdk/stable-channel).
 
 See [use the Windows App SDK in an existing project](/windows/apps/windows-app-sdk/use-windows-app-sdk-in-existing-project) for how to add the Windows App SDK to your project, or if you're already using Windows App SDK, update your packages.
 
+### [C/C++](#tab/c)
+
+Windows ML C APIs are included in the [`Microsoft.WindowsAppSDK.ML` NuGet package](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.ML) version 1.8.6 or greater. The NuGet package ships CMake config files under `build/cmake/` that are directly consumable. The `@WINML_VERSION@` token is resolved at NuGet build time, so no additional processing is required.
+
+To use the NuGet package...
+
+1. Download or restore the NuGet package (e.g., via `nuget restore` or manual download)
+2. Extract or reference the package root directory
+3. Set `CMAKE_PREFIX_PATH` to the `build/cmake` subdirectory of the package
+
+**Example CMakeLists.txt**
+
+```cmake
+cmake_minimum_required(VERSION 3.21)
+project(MyApp LANGUAGES CXX)
+
+# C++20 standard for modern features (std::format, etc.)
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(microsoft.windows.ai.machinelearning CONFIG REQUIRED)
+
+add_executable(MyApp main.cpp)
+target_link_libraries(MyApp PRIVATE WindowsML::Api WindowsML::OnnxRuntime)
+
+add_custom_command(TARGET MyApp POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+        $<TARGET_RUNTIME_DLLS:MyApp> $<TARGET_FILE_DIR:MyApp>
+    COMMAND_EXPAND_LISTS
+    VERBATIM
+)
+```
+
+**Example Build Commands**
+
+```powershell
+# Point CMAKE_PREFIX_PATH to the NuGet package's cmake directory
+cmake -B build -S . -DCMAKE_PREFIX_PATH="C:/packages/Microsoft.WindowsAppSDK.ML/build/cmake"
+cmake --build build --config Release
+```
+
+The NuGet package ships its own cmake config under `build/cmake/` that understands
+the NuGet directory structure (architecture-specific directories under `lib/native/`
+and `runtimes/`). Architecture is determined from `CMAKE_GENERATOR_PLATFORM`,
+`CMAKE_VS_PLATFORM_NAME`, or `CMAKE_SYSTEM_PROCESSOR`.
+
+The vcpkg portfile generates a separate, thin config file that maps to the standard
+vcpkg layout (`lib/` and `bin/`). Both configs share the same targets file
+(`microsoft.windows.ai.machinelearning-targets.cmake`) which defines the IMPORTED
+targets.
+
+The same targets (`WindowsML::WindowsML`, `WindowsML::Api`, `WindowsML::OnnxRuntime`, `WindowsML::DirectML`) are available
+in both consumption modes. Use the standard CMake 3.21 `$<TARGET_RUNTIME_DLLS>` generator expression
+to copy runtime DLLs to the build output directory.
+
 ### [Python](#tab/python)
 
 The Python binding leverages the [pywinrt](https://github.com/pywinrt/pywinrt) project for the Windows App SDK projection. Ensure that your Python installation is not from the Microsoft Store (you can install an unpackaged version from python.org or via winget). The sample depends on using the Windows App SDK dynamic dependency API, which is only valid for unpackaged apps.
@@ -58,10 +120,10 @@ Please make sure the `wasdk-` packages' version matches the WindowsAppRuntime's
 
 ## Step 2: Download and register EPs
 
-The simplest way to get started is to let Windows ML automatically discover, download, and register the latest version of all compatible execution providers. Execution providers need to be registered with the ONNX Runtime inside of Windows ML before you can use them. And if they haven't been downloaded yet, they need to be downloaded first. Calling `EnsureAndRegisterCertifiedAsync()` will do both of these in one step.
-
 ### [C#](#tab/csharp)
 
+The simplest way to get started is to let Windows ML automatically discover, download, and register the latest version of all compatible execution providers. Execution providers need to be registered with the ONNX Runtime inside of Windows ML before you can use them. And if they haven't been downloaded yet, they need to be downloaded first. Calling `EnsureAndRegisterCertifiedAsync()` will do both of these in one step.
+
 ```csharp
 using Microsoft.ML.OnnxRuntime;
 using Microsoft.Windows.AI.MachineLearning;
@@ -84,7 +146,9 @@ var catalog = ExecutionProviderCatalog.GetDefault();
 await catalog.EnsureAndRegisterCertifiedAsync();
 ```
 
-### [C++](#tab/cppwinrt)
+### [C++/WinRT](#tab/cppwinrt)
+
+The simplest way to get started is to let Windows ML automatically discover, download, and register the latest version of all compatible execution providers. Execution providers need to be registered with the ONNX Runtime inside of Windows ML before you can use them. And if they haven't been downloaded yet, they need to be downloaded first. Calling `EnsureAndRegisterCertifiedAsync()` will do both of these in one step.
 
 ```cppwinrt
 #include <winrt/Microsoft.Windows.AI.MachineLearning.h>
@@ -101,8 +165,55 @@ winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog catalog
 catalog.EnsureAndRegisterCertifiedAsync().get();
 ```
 
+### [C/C++](#tab/c)
+
+With the C APIs, you must download a specific execution provider, and then manually register its path with ONNX Runtime.
+
+```cpp
+#include <WinMLEpCatalog.h>
+#include <onnxruntime_cxx_api.h> // Or <onnxruntime_c_api.h> if just using C
+#include <filesystem>
+#include <string>
+
+// Initialize ONNX Runtime
+Ort::Env env(ORT_LOGGING_LEVEL_ERROR, "WinMLDemo"); // Use an ID of your own choice
+
+// --- Windows ML: Get EP catalog handle ---
+WinMLEpCatalogHandle catalog = nullptr;
+HRESULT hr = WinMLEpCatalogCreate(&catalog);
+if (FAILED(hr))
+{
+    // Handle error
+    return;
+}
+
+// --- Windows ML: Find, download, and register a specific EP (in this case, QNN) ---
+WinMLEpHandle ep = nullptr;
+hr = WinMLEpCatalogFindProvider(catalog, "QNN", NULL, &ep);
+if (SUCCEEDED(hr))
+{
+    // Windows ML: Download the EP if it isn't already downloaded
+    WinMLEpEnsureReady(ep);
+
+    // Windows ML: Get the EP library path
+    size_t pathSize = 0;
+    WinMLEpGetLibraryPathSize(ep, &pathSize);
+    std::string libraryPathUtf8(pathSize, '\0');
+    WinMLEpGetLibraryPath(ep, pathSize, libraryPathUtf8.data(), nullptr);
+
+    // Register the EP with ONNX Runtime using the C++ API
+    std::filesystem::path libraryPath(libraryPathUtf8);
+    env.RegisterExecutionProviderLibrary("QNN", libraryPath.wstring());
+}
+
+// --- Windows ML: Release the EP catalog handle ---
+WinMLEpCatalogRelease(catalog);
+```
+
 ### [Python](#tab/python)
 
+With the Python APIs, you can enumerate all compatible execution providers, and then manually register their paths with ONNX Runtime.
+
 ```python
 import sys
 from pathlib import Path