Windows ML

Windows ML is ONNX Runtime plus an execution-provider (EP) catalog. Inference uses ordinary ONNX Runtime APIs. The catalog acquires optional vendor EPs and registers them with ONNX Runtime. CPU and DirectML are included; the vendor EPs are acquired separately. (Overview, acceleration)

Evidence tiers: read this first

This skill keeps three kinds of knowledge apart. Upstream docs can be wrong or silent, and a local observation can come from a misconfiguration rather than the platform. So never let a lower tier pass as a higher one.

Tier	Folder	What may go in	How to use it
1. Canon	`canon/`	Only what a `learn.microsoft.com` page states, each claim linked and dated.	Platform truth. If Learn is silent, say "unresolved"; never fill the gap from another tier.
2. Upstream source	`upstream/`	What ONNX Runtime / ONNX Runtime GenAI source code, tests or NuGet package contents show. Each claim names its repository, file and commit, or its package and version.	Implementation detail Learn does not document. True for the cited version only. Re-check after any version change.
3. Trackdub observations	`trackdub/`	Things seen on Trackdub machines, each with its date, setup, observer, reproduction status and suspected-cause confidence.	Leads to re-test, not facts. Never quote one as platform behaviour. Before code relies on an observation, reproduce it under the current versions. Record whether it held.

Rules when using and when editing this skill:

State the tier whenever you rely on a claim, for example "Learn says…", "ORT source at shows…" or "observed once on 2026-10-07…".
Promote only with evidence. An observation moves to Tier 2 or 1 only when source or Microsoft documentation confirms it. A config mistake that was later fixed gets marked as a misconfiguration, not deleted silently.
Contradictions go to the higher tier. If source or docs contradict an observation, record the contradiction on the observation entry and treat the observation as suspect.
Do not copy volatile numbers (package pins, driver minimums) into tiers 2–3. Point to the file or page that owns them.

Read by task

Task	Start with
Which providers exist, their requirements and limits	canon/execution-providers.md
Per-provider hardware, options, precision gaps, deployment constraints and diagnostic checks	canon/provider-configuration-coverage.md
Build and run a complete C# ResNet example with explicit selection and validated compilation	samples/ResNetWalkthrough/README.md
Get a model running: sourcing, CPU path, acceleration, GenAI, compile and cache	canon/model-setup-and-configuration.md
Packages, deployment mode, install → register → select lifecycle, with C# recipes	canon/deployment-and-lifecycle.md
Updates, offline devices, version traps, language differences	canon/structure-and-edge-cases.md
Download failures, ETW logs, "provider missing" triage	canon/diagnostics.md
How ORT / GenAI behave where Learn is silent (managed binding, registration names, GenAI provider names, package contents)	upstream/ort-and-genai-source.md, upstream/packages.md
What Trackdub has seen, and where its Windows ML code lives	trackdub/observations.md, trackdub/where-things-live.md

Canonical workflow (Tier 1)

Obtain or convert an ONNX model compatible with the ORT version shipped in the chosen Windows ML release.
Choose runtime deployment (self-contained or framework-dependent) separately from EP sourcing (catalog, bundled, or hybrid).
Establish the CPU inference path first.
Find compatible EPs, then install or prepare and register the one you need.
Enumerate EP devices, select explicitly, configure session options and create the session. Try device policies only after explicit selection works.
Compile and cache hardware-specific artifacts, and validate them before reuse.
Use Windows ML diagnostic logs to see what was actually selected and why it failed.

Sources: get started, deployment, install, select, compilation, logs.

Cover all providers equally; do not default to NVIDIA-specific configuration. samples/ConfigureExplicitProvider.cs adapts Microsoft's explicit-selection pattern. It only configures options: it does not install an EP, create a session or run a model.

Restrictions to check first (Tier 1)

Catalog-acquired hardware EPs require Windows 11 24H2 (build 26100) or later and suitable hardware and drivers. CPU and DirectML have broader OS coverage. (Providers)
Model compatibility depends on the ORT version shipped with Windows ML, not just the ONNX file format. (Models)
The MIGraphX Windows ML EP does not currently support GenAI scenarios. (Providers)
WebGPU is experimental and needs experimental packages and explicit installation. It is not recommended for performance-critical work. (WebGPU)
The separate Windows ML Runtime API is experimental, unsupported for production or Store publication, and has no C# support. (Runtime API)
EP licences are separate from the Windows ML licence and say nothing about a model's rights. (Third-party notices)

Looking things up

Use the Microsoft Learn MCP: microsoft_docs_search, then microsoft_docs_fetch, and microsoft_code_sample_search with language: "csharp" for API examples. Keep each query to one concept. If MCP is unavailable, use the reviewed CLI version, npx @microsoft/learn-cli@1.0.0 search|fetch|code-search (bump that version only after reviewing the release), and accept only learn.microsoft.com results for Tier 1.

Topic	Query
Model compatibility	`Windows ML models ONNX Runtime versions`
Provider lifecycle	`Windows ML EnsureReadyAsync RegisterCertifiedAsync TryRegister`
Hardware placement	`Windows ML GetEpDevices AppendExecutionProvider device policies`
Cache correctness	`Windows ML model compilation EP_NOT_APPLICABLE source hash`
Restricted or offline devices	`Windows ML execution provider download issues bring your own`
Deployment and updates	`Windows ML self-contained framework-dependent updates`
Model preparation	`Windows ML CLI model conversion optimization quantization`
Diagnostics	`Windows ML logs ETW rundown execution provider selection`

For Tier 2, read the source itself, for example with GitHits on github:microsoft/onnxruntime or github:microsoft/onnxruntime-genai at a pinned commit, or NuGet package contents. Record the commit or package version next to the claim.

Report what the documentation establishes, what source shows, what was observed, and what was actually tested. Documentation or a compiled sample alone does not prove model execution.

windows-ml