From c0d7c8bc44185e02485ec787b7ba73e1435508fc Mon Sep 17 00:00:00 2001
From: Sheil Kumar <smk2007@gmail.com>
Date: Mon, 14 Sep 2020 21:15:51 -0700
Subject: [PATCH] Add docs indicating that the onnxruntime engine from other
 distributions can be compatible with the WinRT NuGet (#5009)

* add docs for mix and matching

* typos

Co-authored-by: Sheil Kumar <sheilk@microsoft.com>
---
 ...osoft.AI.MachineLearning.Rules.Project.xml | 18 +++++++++---------
 .../Microsoft.AI.MachineLearning.targets      | 15 ++++++++-------
 docs/InferenceHighLevelDesign.md              | 19 ++++++++++++++++++-
 3 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.Rules.Project.xml b/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.Rules.Project.xml
index 9b2fe8c8c8..2394ee728a 100644
--- a/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.Rules.Project.xml
+++ b/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.Rules.Project.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<Rule Name="OnnxRuntime" DisplayName="ONNX Runtime (Beta)" Order="75" PageTemplate="generic" xmlns="http://schemas.microsoft.com/build/2009/properties">
+<Rule Name="WindowsAI" DisplayName="Microsoft.AI.MachineLearning NuGet Settings" Order="75" PageTemplate="generic" xmlns="http://schemas.microsoft.com/build/2009/properties">
   <Rule.Categories>
     <Category Name="General" DisplayName="General"/>
   </Rule.Categories>
@@ -8,13 +8,13 @@
     <DataSource Persistence="ProjectFile" HasConfigurationCondition="false" Label="Globals" />
   </Rule.DataSource>
 
-  <StringProperty Name="OnnxRuntimePathOverride"
-                  DisplayName="Custom ONNXRuntime DLL"
-                  Description="Specifies a path to a custom OnnxRuntime dll."
-                  Category="General" />
+  <BoolProperty Name="DisableOnnxRuntimeDllCopy"
+                DisplayName="Disable onnxruntime.dll copy on build"
+                Description="Suppresses binplacing the onnxruntime.dll from the Mirosoft.AI.MachineLearning NuGet distribution."
+                Category="General" />
 
-  <StringProperty Name="DirectMLPathOverride"
-                  DisplayName="Custom DirectML DLL"
-                  Description="Specifies a path to a custom Direct ML dll."
-                  Category="General" />
+  <BoolProperty Name="DisableDirectMLDllCopy"
+                DisplayName="Disable directml.dll copy on build"
+                Description="Suppresses binplacing the directml.dll from the Mirosoft.AI.MachineLearning NuGet distribution."
+                Category="General" />
 </Rule>
\ No newline at end of file
diff --git a/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.targets b/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.targets
index c578bd7a23..5f082a5795 100644
--- a/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.targets
+++ b/csharp/src/Microsoft.AI.MachineLearning/Microsoft.AI.MachineLearning.targets
@@ -8,16 +8,17 @@
   <PropertyGroup>
     <RuntimesDirectory Condition="'$(OutputType)' == 'AppContainerExe'">$(MSBuildThisFileDirectory)..\..\runtimes\win-$(WindowsAI-Platform)\uap</RuntimesDirectory>
     <RuntimesDirectory Condition="'$(RuntimesDirectory)' == ''">$(MSBuildThisFileDirectory)..\..\runtimes\win-$(WindowsAI-Platform)\native</RuntimesDirectory>
-
     <WindowsAIBinary>$(RuntimesDirectory)\Microsoft.AI.MachineLearning.dll</WindowsAIBinary>
-
-    <OnnxRuntimeBinary Condition="'$(OnnxRuntimePathOverride)' != ''">$(OnnxRuntimePathOverride)</OnnxRuntimeBinary>
-    <OnnxRuntimeBinary Condition="'$(OnnxRuntimeBinary)' == ''">$(RuntimesDirectory)\onnxruntime.dll</OnnxRuntimeBinary>
-
-    <DirectMLBinary Condition="'$(DirectMLPathOverride)' != ''">$(DirectMLPathOverride)</DirectMLBinary>
-    <DirectMLBinary Condition="'$(DirectMLBinary)' == ''">$(RuntimesDirectory)\directml.dll</DirectMLBinary>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(DisableOnnxRuntimeDllCopy)' != 'true'">
+    <OnnxRuntimeBinary Condition="'$(OnnxRuntimeBinary)' == ''">$(RuntimesDirectory)\onnxruntime.dll</OnnxRuntimeBinary>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(DisableDirectMLDllCopy)' != 'true'">
+    <DirectMLBinary Condition="'$(DirectMLBinary)' == ''">$(RuntimesDirectory)\directml.dll</DirectMLBinary>
+  </PropertyGroup>
+  
   <ItemGroup>
     <Reference Include="$(MSBuildThisFileDirectory)\..\..\lib\uap\Microsoft.AI.MachineLearning.winmd">
       <Implementation>$(WindowsAIBinary)</Implementation>
diff --git a/docs/InferenceHighLevelDesign.md b/docs/InferenceHighLevelDesign.md
index 0b71ce88a4..d5f0e73c1c 100644
--- a/docs/InferenceHighLevelDesign.md
+++ b/docs/InferenceHighLevelDesign.md
@@ -109,10 +109,27 @@ Developers can now choose which API works best for their scenario.
 
 You can also choose to use runtimes included in the Windows OS, or use the redist nuget to ship the runtime with the app.
 
-|Distribution|Inbox|App nuget|
+|Distribution|Inbox|App NuGet|
 |--|--|--|
 |Disk footprint| Included in the OS| Included in the App|
 |Servicing fixes| Serviced by OS updates| Serviced by the App|
 |Execution Providers| CPU & DirectML EP | App chosen EP|
 |Compatability testing| Tested with OS flights against supported GPU's and CPU's | App performs compatibility testing|
 |Opset| Refreshed in OS updates| App chooses|
+
+ 
+### Using the NuGet WinRT API with other C-API distributions
+The WinRT API NuGet is distributed with a curated build of the OnnxRuntime engine. App developers may wish to use the WinRT API, but find themselves limited to the functionality provided by the curated OnnxRuntime engine distributed as part of the WinRT API NuGet package. This can happen because the OnnxRuntime engine shipped with the WinRT API NuGet package only contains the CPU and DML execution providers.
+
+App developers may additionally wish to use a custom build-from-source version of the OnnxRuntime engine as well, or use a prebuilt version of the OnnxRuntime engine from another distribution source like the Micorosoft.ML.OnnxRuntime.MKLML distribution.
+
+To enable this, the WinRT API NuGet has been made to be compatible with a set of OnnxRuntime engines that ship in different NuGet packages.
+
+Please refer to the following table listing the distributions with compatible OnnxRuntime engines.
+- [Microsoft.ML.OnnxRuntime](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime)
+- [Microsoft.ML.OnnxRuntime.DirectML](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime.DirectML/)
+- [Microsoft.ML.OnnxRuntime.MKLML](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime.MKLML)
+
+Note that compatible distributions must match in release version.
+
+In order to use compatible engines, replace the onnxruntime.dll with the desired engine binary and its associated binaries.
\ No newline at end of file