Language
Edit

Set up a project for the Windows ML Runtime API

Important

The Windows ML Runtime API is currently experimental and not supported for use in production environments. Apps trying out this API should not be published to the Microsoft Store.

This topic shows you how to configure a native C++, C#, or Python project to use the Runtime API and create an IWinMLRuntime instance. Continue to Run a model with the Windows ML Runtime API for model loading, tensor binding, and inference.

Prerequisites

  • The .NET 8 SDK or later.
  • A C# console project that targets net8.0-windows10.0.19041.0 or later.
  • CsWin32 0.3.369 or later. Earlier versions generate IUnknown* parameters, such as the adapter that CreateExecutionTargetFromAdapter takes, as IUnknown values instead of pointers.

The CPU execution target is the baseline path. GPU and NPU availability depends on the device, platform capabilities, and execution backend installed for your app.

Configure your project

Important

The Windows ML package doesn't include C# APIs yet. For now, you generate the bindings with CsWin32 and copy a C# wrapper into your project by hand. A future update will include the C# APIs natively, and you can then remove the copied files.

The package includes Win32 metadata for the Runtime and Task APIs, metadata\win32\Microsoft.Windows.AI.MachineLearning.Runtime.winmd. CsWin32 generates unmanaged bindings from it. The package adds the metadata to CsWin32 and lets the generated imports load the Runtime DLLs from the application directory. Set WinMLEnableRuntimeCsWin32Metadata to false to opt out. The Server API isn't included in the metadata.

  1. Add the package references. Set the runtime identifier to win-x64 or win-arm64 to match the process architecture, so that the package's native DLLs are placed next to your app.

    <PropertyGroup>
      <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
      <RuntimeIdentifier>win-x64</RuntimeIdentifier>
      <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    </PropertyGroup>
    <ItemGroup>
      <PackageReference Include="Microsoft.Windows.AI.MachineLearning" Version="2.9.42-experimental" />
      <PackageReference Include="Microsoft.Windows.CsWin32" Version="0.3.369" PrivateAssets="all" />
    </ItemGroup>
    
  2. Copy the wrapper files from the Windows ML samples repository into your project:

    • The Runtime folder, which holds the wrapper source (namespaces WinMLSamples.Runtime and WinMLSamples.Runtime.Tasks).
    • NativeMethods.txt, which lists the APIs that CsWin32 generates bindings for.
    • NativeMethods.json, which sets the CsWin32 generation options.

The wrapper gives the COM-style APIs an idiomatic C# surface: objects implement IDisposable, failures throw .NET exceptions that keep the HRESULT, and token streams are IAsyncEnumerable<T>. Your code then has no pointers or HRESULT checks.

Note

The wrapper is sample code, not a supported API. It isn't shipped in a package, and it can change with the samples. If you copy it, you maintain it until the C# APIs are included in the package.

Initialize the Runtime

Replace Program.cs with the following code:

// Temporary: WinMLRuntime and the other wrapper types in the WinMLSamples.Runtime
// namespaces aren't in the Windows ML package yet. Copy the wrapper files from
// https://github.com/microsoft/WindowsML/tree/main/Samples/Runtime/shared/csharp
// into your project. A future update will include the C# APIs natively.
using WinMLSamples.Runtime;

using WinMLRuntime runtime = WinMLRuntime.Create();

Console.WriteLine("Created the Windows ML Runtime.");

Build for the architecture that matches the runtime identifier, such as win-x64. A successful build confirms that CsWin32 generated the bindings and that the package copied the Runtime DLLs beside the executable.

Next steps