Skip to content

[Documentation] Update ONNX Runtime Documentation to Position WinML as Preferred Windows Path and DirectML in Sustained Engineering#25901

Merged
MaanavD merged 4 commits intogh-pagesfrom
copilot/fix-f05ef26d-9c38-4d97-b893-688f54493272
Sep 16, 2025
Merged

[Documentation] Update ONNX Runtime Documentation to Position WinML as Preferred Windows Path and DirectML in Sustained Engineering#25901
MaanavD merged 4 commits intogh-pagesfrom
copilot/fix-f05ef26d-9c38-4d97-b893-688f54493272

Conversation

Copy link
Contributor

Copilot AI commented Aug 29, 2025

This PR addresses issue #25899 by updating the ONNX Runtime documentation to clearly reflect that WinML is the preferred and future-safe execution path for Windows developers, with DirectML now in sustained engineering rather than deprecated.

Changes Made

DirectML Execution Provider Page

  • Updated messaging to use "sustained engineering" terminology, clarifying that DirectML continues to be supported but new feature development has moved to WinML
  • Maintained clear migration guidance directing users to WinML with links to installation instructions
  • Preserved existing technical documentation for users who still need DirectML information

Windows Getting Started Page

  • Updated the introduction to explicitly state "WinML is the recommended Windows development path for ONNX Runtime"
  • Enhanced developer guidance explaining WinML's key benefits:
    • Uses the same ONNX Runtime APIs developers are familiar with
    • WinML automatically selects the best execution provider based on customer's hardware, with override mechanisms for manual fine-grained control
    • Simplified deployment by deploying all needed dependencies for AI inference on the client
  • Added comprehensive Windows version support clarification:
    • Windows 10 (1809+) & Windows 11 (before 24H2): ONNX Runtime works but requires manual execution provider management
    • Windows 11 (24H2+): WinML provides additional automation for execution provider selection and hardware optimization
  • Corrected namespace reference to Microsoft.Windows.AI.MachineLearning.dll

Install Page

  • Updated installation instructions to consistently use sustained engineering terminology for DirectML
  • Enhanced WinML visibility by maintaining "recommended for Windows" designation
  • Updated both inline installation sections and comprehensive install table with consistent messaging
  • Added guidance note to Python DirectML section directing new projects to consider WinML

Impact

These changes provide clearer, more accurate guidance for Windows developers on the preferred ONNX Runtime deployment path while maintaining backward compatibility documentation. The updates help developers understand:

  • DirectML's current sustained engineering status (supported but innovation moved to WinML)
  • WinML's relationship to ONNX Runtime with clear version requirements and capabilities
  • The benefits of using WinML over DirectML, including automatic hardware optimization with manual override options
  • Precise Windows version support breakdown for different deployment scenarios
  • Where to find additional resources and migration paths

The documentation changes preserve all existing content while providing the necessary updated guidance based on Microsoft's current Windows AI strategy.

Fixes #25899


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

- Add deprecation notice to DirectML Execution Provider page with clear migration guidance to WinML
- Update Windows Getting Started page to prioritize WinML as recommended path
- Add developer guidance about WinML benefits (same APIs, dynamic EP selection, simplified deployment)
- Update install instructions to clearly mark DirectML as deprecated
- Add Windows ML Overview reference link
- Update install table to highlight WinML as recommended for Windows and mark DirectML as deprecated

Co-authored-by: MaanavD <24942306+MaanavD@users.noreply.github.com>
Copilot AI changed the title [WIP] https://github.com@microsoft/onnxruntime/issues/25899/microsoft/onnxruntime/issues/25899 [Documentation] Update ONNX Runtime Documentation to Highlight WinML as the Preferred Windows Path Aug 29, 2025
Copilot AI requested a review from MaanavD August 29, 2025 20:16
@MaanavD MaanavD marked this pull request as ready for review August 29, 2025 20:19
@MaanavD
Copy link
Contributor

MaanavD commented Sep 2, 2025

@copilot make changes based on this discussion:

My feedback:
**Note: DirectML is deprecated.** Please use [WinML](../get-started/with-windows.md) for Windows-based ONNX Runtime deployments. WinML provides the same ONNX Runtime APIs while dynamically selecting the best execution provider based on your hardware. See the [WinML install section](../install/#cccwinml-installs) for installation instructions.

Agreed with Anastasiya -- might be just a touch too strong. The terminology we've used in the past for stuff like this is "sustained engineering", which signals that it's still supported, but innovation is halted. You might try a message around that. (and as Anastasiya mentioned, this should also be reflected on lines 172 and 178 later in the doc)

**Dynamic execution provider selection**: Automatically selects the best execution provider (EP) based on your hardware
This looks good, but has me wondering if some developers might be left wondering if they have control over this. You could try something more balanced that says "Dynamic execution Provider selection: WinML automatically selects the best execution provider (EP) based on your customer's hardware, with mechanisms that you can override for manual fine-grained control".

**Simplified deployment**: Reduces complexity for Windows developers by handling hardware optimization automatically
This sentence is a bit strange to me. Deployment is different than hardware optimization. I think I would say: "Simplified Deployment: Reduces complexity for Windows developers by deploying all needed dependencies for AI inference on the client" (or "local AI inference" or however that is best said)

This will almost definitely confused someone:```
- While it's true that ORT runs on Win10 >= 1809, WinML is only Win11 24H2+.  This needs some expansion to make it clearer that there is a difference in support between these two things.
- The namespace for WinML is Microsoft.Windows.AI.MachineLearning.  I'm assuming that means the DLL also has the Microsoft prefix?

As a clarification to that last point: 

ORT running on Windows 10 1809+, but the WinML part only running on Windows 11 24H2+
 
WinML handles the catalog of execution providers for the ORT. You could manually handle that with the ORT, but it's a growing problem as more silicon comes up.
 
ORT on Windows before Windows 11 24H2: Works, but you have to pick and manage the models and EPs yourself
24H2+ : WinML helps with a lot of the other ceremony.
 
The reason is Windows is a very broad and open ecosystem compared to some others, so to have full support for all silicon, you really want some help in the form of WinML. Beyond that, it's all ORT

…d improve WinML descriptions

Co-authored-by: MaanavD <24942306+MaanavD@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Sep 2, 2025

@copilot make changes based on this discussion:

My feedback:
...

I've addressed all the feedback in commit ec95d65:

  1. DirectML messaging: Changed from "deprecated" to "sustained engineering mode" throughout all documentation
  2. Dynamic EP selection: Updated to clarify that WinML provides automatic selection with override mechanisms for manual fine-grained control
  3. Simplified deployment: Clarified this refers to deploying AI inference dependencies on the client
  4. Windows version support: Expanded to clearly distinguish:
    • Win10 1809+ & Win11 (before 24H2): Manual EP management required
    • Win11 24H2+: WinML provides automation for EP selection
  5. Namespace correction: Updated to Microsoft.Windows.AI.MachineLearning.dll
  6. Consistent terminology: Updated all DirectML references (lines 172, 178, and install table) to use sustained engineering mode

The changes maintain backward compatibility while providing clearer guidance on WinML's benefits and Windows version requirements.

Copilot AI changed the title [Documentation] Update ONNX Runtime Documentation to Highlight WinML as the Preferred Windows Path [Documentation] Update ONNX Runtime Documentation to Position WinML as Preferred Windows Path and DirectML in Sustained Engineering Mode Sep 2, 2025
Copilot AI requested a review from MaanavD September 2, 2025 19:39
@MaanavD
Copy link
Contributor

MaanavD commented Sep 2, 2025

@copilot Just "sustained engineering". It's a relatively common term, no need to add the "mode"

Co-authored-by: MaanavD <24942306+MaanavD@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Sep 2, 2025

@copilot Just "sustained engineering". It's a relatively common term, no need to add the "mode"

Updated all instances to use "sustained engineering" instead of "sustained engineering mode" throughout the documentation in commit 9ea00a1.

Copilot AI changed the title [Documentation] Update ONNX Runtime Documentation to Position WinML as Preferred Windows Path and DirectML in Sustained Engineering Mode [Documentation] Update ONNX Runtime Documentation to Position WinML as Preferred Windows Path and DirectML in Sustained Engineering Sep 2, 2025
@natke natke self-requested a review September 3, 2025 21:12
@MaanavD MaanavD merged commit d6123fb into gh-pages Sep 16, 2025
1 of 3 checks passed
@MaanavD MaanavD deleted the copilot/fix-f05ef26d-9c38-4d97-b893-688f54493272 branch September 16, 2025 20:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants