Language
Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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
- A Windows version supported by the
Microsoft.Windows.AI.MachineLearningpackage. See Windows ML deployment requirements. - The experimental version
2.9.42-experimentalof Microsoft.Windows.AI.MachineLearning NuGet package. Windows ML 2.9 adds the CGC backend and Tasks that take a model.
- The .NET 8 SDK or later.
- A C# console project that targets
net8.0-windows10.0.19041.0or later. - CsWin32 0.3.369 or later. Earlier versions generate
IUnknown*parameters, such as the adapter thatCreateExecutionTargetFromAdaptertakes, asIUnknownvalues 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.
Add the package references. Set the runtime identifier to
win-x64orwin-arm64to 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>Copy the wrapper files from the Windows ML samples repository into your project:
- The
Runtimefolder, which holds the wrapper source (namespacesWinMLSamples.RuntimeandWinMLSamples.Runtime.Tasks). NativeMethods.txt, which lists the APIs that CsWin32 generates bindings for.NativeMethods.json, which sets the CsWin32 generation options.
- The
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.