Discourage using explicit package references to ILCompiler to publish (#74591)

* Show a warning when an explicit package reference to ILCompiler is added

* Apply suggestions from code review
Co-authored-by: NJan Kotas <jkotas@microsoft.com>

* Fix issue 27239

* Apply suggestions from code review
Co-authored-by: NSven Boemer <sbomer@gmail.com>

* exclude the warning for direct targets file invoke cases
Co-authored-by: NJan Kotas <jkotas@microsoft.com>
Co-authored-by: NSven Boemer <sbomer@gmail.com>

src/coreclr/nativeaot/BuildIntegration/Microsoft.DotNet.ILCompiler.SingleEntry.targets

@@ -36,15 +36,18 @@
     <IlcDynamicBuildPropertyDependencies>SetupProperties</IlcDynamicBuildPropertyDependencies>
   </PropertyGroup>
 
-  <ItemGroup>
-    <!-- If called via package instead of the SDK, update the runtime package version to match the build package -->
-    <_PackageReferenceExceptILCompiler Include="@(PackageReference)" Exclude="Microsoft.DotNet.ILCompiler" />
-    <_ILCompilerPackageReference Include="@(PackageReference)" Exclude="@(_PackageReferenceExceptILCompiler)" />
-    <KnownILCompilerPack Update="Microsoft.DotNet.ILCompiler" Condition="@(_ILCompilerPackageReference->'%(Identity)')=='Microsoft.DotNet.ILCompiler'">
-        <ILCompilerPackVersion>@(_ILCompilerPackageReference->'%(Version)')</ILCompilerPackVersion>
+  <!-- If called via package instead of the SDK, update the runtime package version to match the build package -->
+  <ItemGroup Condition="'$(AotRuntimePackageLoadedViaSDK)' != 'true'">
+    <KnownILCompilerPack Update="Microsoft.DotNet.ILCompiler">
+      <ILCompilerPackVersion>$([System.IO.Path]::GetFileName($([System.IO.Path]::GetDirectoryName($([System.IO.Path]::GetDirectoryName($(ILCompilerTargetsPath)))))))</ILCompilerPackVersion>
     </KnownILCompilerPack>
   </ItemGroup>
 
+  <!-- Generate a warning if the non-SDK path is used  -->
+  <Target Name="GenerateILCompilerExplicitPackageReferenceWarning" Condition="'$(SuppressGenerateILCompilerExplicitPackageReferenceWarning)' == '' and '$(AotRuntimePackageLoadedViaSDK)' != 'true' and '$(ILCompilerTargetsPath)' != ''" BeforeTargets="ImportRuntimeIlcPackageTarget">
+    <Warning Text="Set PublishAot property to true and delete explicit 'Microsoft.DotNet.ILCompiler' package reference in your project file. Explicit 'Microsoft.DotNet.ILCompiler' package reference can run into version errors." />
+  </Target>
+
   <!-- Locate the runtime package according to the current target runtime -->
   <Target Name="ImportRuntimeIlcPackageTarget" Condition="'$(BuildingFrameworkLibrary)' != 'true' and '$(PublishAot)' == 'true' and $(IlcCalledViaPackage) == 'true'" DependsOnTargets="$(ImportRuntimeIlcPackageTargetDependsOn)" BeforeTargets="Publish">
     <Error Condition="'@(ResolvedILCompilerPack)' == ''" Text="The ResolvedILCompilerPack ItemGroup is required for target ImportRuntimeIlcPackageTarget" />

src/coreclr/nativeaot/BuildIntegration/Microsoft.DotNet.ILCompiler.props

@@ -11,8 +11,6 @@ Copyright (c) .NET Foundation. All rights reserved.
 -->
 <Project>
   <PropertyGroup>
-    <!-- Set the publishAot property to true when imported from a package reference. -->
-    <PublishAot Condition="'$(PublishAot)' == '' And '$(AotRuntimePackageLoadedViaSDK)' != 'true'">true</PublishAot>
     <!-- N.B. The ILCompilerTargetsPath is used as a sentinel to indicate a version of this file has already been imported. It will also be the path
          used to import the targets later in the SDK. -->
     <ILCompilerTargetsPath>$(MSBuildThisFileDirectory)Microsoft.DotNet.ILCompiler.SingleEntry.targets</ILCompilerTargetsPath>

src/coreclr/nativeaot/docs/compiling.md

@@ -2,8 +2,7 @@
 
 Please consult [documentation](https://docs.microsoft.com/dotnet/core/deploying/native-aot) for instructions how to compile and publish application.
 
-The rest of this document covers advanced topics only.
-
+The rest of this document covers advanced topics only. Adding an explicit package reference to `Microsoft.DotNet.ILCompiler` will generate warning when publishing and it can run into version errors. When possible, use the PublishAot property to publish a native AOT application.
 
 ## Using daily builds
 
@@ -34,7 +33,21 @@ or by adding the following element to the project file:
 
 ## Cross-architecture compilation
 
-Native AOT toolchain allows targeting ARM64 on an x64 host and vice versa for both Windows and Linux. Cross-OS compilation, such as targeting Linux on a Windows host, is not supported. To target win-arm64 on a Windows x64 host, in addition to the `Microsoft.DotNet.ILCompiler` package reference, also add the `runtime.win-x64.Microsoft.DotNet.ILCompiler` package reference to get the x64-hosted compiler:
+Native AOT toolchain allows targeting ARM64 on an x64 host and vice versa for both Windows and Linux and is now supported in the SDK. Cross-OS compilation, such as targeting Linux on a Windows host, is not supported. For SDK support, add the following to your project file,
+
+```xml
+    <PropertyGroup>
+        <PublishAot>true</PublishAot>
+    </PropertyGroup>
+```
+
+Targeting win-arm64 on a Windows x64 host machine,
+
+```bash
+> dotnet publish -r win-arm64 -c Release
+```
+
+To target win-arm64 on a Windows x64 host on an advanced scenario where the SDK support is not sufficient (note that these scenarios will generate warnings for using explicit package references), in addition to the `Microsoft.DotNet.ILCompiler` package reference, also add the `runtime.win-x64.Microsoft.DotNet.ILCompiler` package reference to get the x64-hosted compiler:
 ```xml
 <PackageReference Include="Microsoft.DotNet.ILCompiler; runtime.win-x64.Microsoft.DotNet.ILCompiler" Version="7.0.0-preview.2.22103.2" />
 ```