Use Roslyn from SDK always for SDK-based project builds (#48028)

jjonescz · jaredpar · web-flow · commit e5f35a28bbfc · 2025-04-19T18:45:56.000Z
Co-authored-by: Jared Parsons &lt;jared@paranoidcoding.org&gt;
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -6,6 +6,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageVersion Include="Basic.CompilerLog.Util" Version="0.9.9" />
     <PackageVersion Include="AwesomeAssertions" Version="$(AwesomeAssertionsVersion)" />
     <PackageVersion Include="AwesomeAssertions.Json" Version="$(AwesomeAssertionsJsonVersion)" />
     <PackageVersion Include="MicroBuild.Plugins.SwixBuild.Dotnet" Version="1.1.87-gba258badda" />
@@ -77,6 +78,7 @@
     <PackageVersion Include="Microsoft.Web.Xdt" Version="$(MicrosoftWebXdtPackageVersion)" />
     <PackageVersion Include="Microsoft.Win32.SystemEvents" Version="$(MicrosoftWin32SystemEventsPackageVersion)" />
     <PackageVersion Include="Microsoft.Windows.CsWin32" Version="$(MicrosoftWindowsCsWin32PackageVersion)" />
+    <PackageVersion Include="MSBuild.StructuredLogger" Version="2.2.386" />
     <PackageVersion Include="Moq" Version="$(MoqPackageVersion)" />
     <PackageVersion Include="NETStandard.Library.NETFramework" Version="$(NETStandardLibraryNETFrameworkVersion)" />
     <PackageVersion Include="Newtonsoft.Json" Version="$(NewtonsoftJsonPackageVersion)" />
diff --git a/documentation/general/decouple-vs-and-net-sdk.md b/documentation/general/decouple-vs-and-net-sdk.md
@@ -117,13 +117,19 @@ There is nothing preventing NuGet based analyzers from following the same model
 
 Solutions that mix .NET SDK and Visual Studio projects will end up with multiple compiler servers running. This is a result of the .NET SDK projects using the compiler from the .NET SDK and non-SDK projects using the compiler from Visual Studio. There is nothing functionally wrong with this but it's possible customers will notice this and ask questions about it.
 
-The compiler will offer a property that allows SDK projects to use the MSBuild version of the compiler when being built with `msbuild`: `<RoslynUseMSBuildCompiler>true</RoslynUseMSBuildCompiler>`. This can be added to a `Directory.Build.props` file to impact the entire solution. This is not expected to be a common scenario but is available for customers who need it. This property will be ignored when using `dotnet build` as there is no way to fall back to the Visual Studio compiler in that scenario.
+The compiler will offer a property that allows SDK projects to use the MSBuild version of the compiler when being built with `msbuild`: `<RoslynCompilerType>Framework</RoslynCompilerType>`. This can be added to a `Directory.Build.props` file to impact the entire solution. This is not expected to be a common scenario but is available for customers who need it. This property will be ignored when using `dotnet build` as there is no way to fall back to the Visual Studio compiler in that scenario.
+
+> [!NOTE]
+> These values are recognized for property `RoslynCompilerType`:
+> - `Core`: use the compiler that comes with the .NET SDK
+> - `Framework`: use the compiler that comes with .NET Framework MSBuild
+> - `FrameworkPackage`: download package with .NET Framework compiler corresponding to the .NET SDK version
 
 ### .NET Framework based analyzers
 
 There are a few analyzers which are built against .NET Framework TFMs. That means when loaded in a .NET Core compiler it could lead to compatibility issues. This is not expected to be a significant issue as our processes have been pushing customers to target `netstandard` in analyzers for 5+ years. However it is possible that some customers will run into issues here.
 
-For those customers we will recommend that they set `<RoslynUseMSBuildCompiler>true</RoslynUseMSBuildCompiler>` in their build to ensure a .NET Framework based compiler is used.  However, it is not our intent to support loading .NET Framework based analyzers in perpetuity. Starting in .NET 12 the compiler will begin issueing warnings is this setup when it detects framework analyzers, and this will become an error in .NET 13. Non-SDK projects will support loading framework based analyzers for the foreseeable future.
+For those customers we will recommend that they set `<RoslynCompilerType>Framework</RoslynCompilerType>` in their build to ensure a .NET Framework based compiler is used.  However, it is not our intent to support loading .NET Framework based analyzers in perpetuity. Starting in .NET 12 the compiler will begin issueing warnings is this setup when it detects framework analyzers, and this will become an error in .NET 13. Non-SDK projects will support loading framework based analyzers for the foreseeable future.
 
 ### Build server shutdown
 
diff --git a/documentation/general/torn-sdk.md b/documentation/general/torn-sdk.md
@@ -1,5 +1,8 @@
 # Torn .NET SDK
 
+> [!CAUTION]
+> This document has been superseded by [Decoupling the .NET SDK and Visual Studio](decouple-vs-and-net-sdk.md).
+
 ## Terminology
 
 - **msbuild**: refers the .NET Framework based msbuild included with Visual Studio.
diff --git a/sdk.sln b/sdk.sln
@@ -19,7 +19,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		build.sh = build.sh
 		Directory.Build.props = Directory.Build.props
 		Directory.Build.targets = Directory.Build.targets
+		Directory.Packages.props = Directory.Packages.props
 		LICENSE.TXT = LICENSE.TXT
+		NuGet.config = NuGet.config
 		README.md = README.md
 		restore.cmd = restore.cmd
 		restore.sh = restore.sh
diff --git a/src/Layout/redist/targets/Crossgen.targets b/src/Layout/redist/targets/Crossgen.targets
@@ -57,7 +57,7 @@
 
       <RazorToolFiles Include="$(InstallerOutputDirectory)Sdks\Microsoft.NET.Sdk.Razor\tools\**\*" />
 
-      <RemainingFiles Include="$(InstallerOutputDirectory)**\*" Exclude="$(InstallerOutputDirectory)FSharp\FSharp.Build.dll;@(RoslynFiles);@(FSharpFiles)" />
+      <RemainingFiles Include="$(InstallerOutputDirectory)**\*" Exclude="$(InstallerOutputDirectory)FSharp\FSharp.Build.dll;@(RoslynFiles);@(FSharpFiles);$(InstallerOutputDirectory)Roslyn\binfx\**\*" />
 
       <!-- Don't crossgen VB since the usage doesn't justify the size cost for everyone -->
       <RoslynFiles Remove="$(InstallerOutputDirectory)Roslyn\bincore\Microsoft.CodeAnalysis.VisualBasic.dll" />
diff --git a/src/Layout/redist/targets/GenerateLayout.targets b/src/Layout/redist/targets/GenerateLayout.targets
@@ -50,6 +50,8 @@
       <RoslynFrameworkAssembly Include="$(RoslynPackagePath)System.*.dll;
                                         $(RoslynPackagePath)runtimes\**\System.*.dll"
                                Exclude="$(RoslynPackagePath)runtimes\**\System.IO.Pipes.AccessControl.dll"/>
+      <!-- binfx folder contains full framework dlls that are needed only on Windows -->
+      <RoslynFrameworkAssembly Include="$(RoslynPackagePath)binfx\**\*" Condition="'$(OS)' != 'Windows_NT'"/>
       <RoslynFile Include="$(RoslynPackagePath)**\*" Exclude="@(RoslynFrameworkAssembly)" />
     </ItemGroup>
 
diff --git a/src/RazorSdk/Targets/Microsoft.NET.Sdk.Razor.Compilation.targets b/src/RazorSdk/Targets/Microsoft.NET.Sdk.Razor.Compilation.targets
@@ -129,6 +129,7 @@ Copyright (c) .NET Foundation. All rights reserved.
          ChecksumAlgorithm="$(ChecksumAlgorithm)"
          CodeAnalysisRuleSet="$(ResolvedCodeAnalysisRuleSet)"
          CodePage="$(CodePage)"
+         CompilerType="$(RoslynCompilerType)"
          DebugType="$(DebugType)"
          DefineConstants="$(DefineConstants)"
          DelaySign="$(DelaySign)"
diff --git a/src/RazorSdk/Targets/Microsoft.NET.Sdk.Razor.Component.targets b/src/RazorSdk/Targets/Microsoft.NET.Sdk.Razor.Component.targets
@@ -195,6 +195,7 @@ Copyright (c) .NET Foundation. All rights reserved.
          ChecksumAlgorithm="$(ChecksumAlgorithm)"
          CodeAnalysisRuleSet="$(ResolvedCodeAnalysisRuleSet)"
          CodePage="$(CodePage)"
+         CompilerType="$(RoslynCompilerType)"
          DebugType="$(DebugType)"
          DefineConstants="$(DefineConstants)"
          DelaySign="$(DelaySign)"
diff --git a/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.BeforeCommon.targets b/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.BeforeCommon.targets
@@ -299,4 +299,45 @@ Copyright (c) .NET Foundation. All rights reserved.
     <IsNetCoreAppTargetingLatestTFM Condition="'$(IsNetCoreAppTargetingLatestTFM)' == '' and '$(TargetFrameworkIdentifier)' == '.NETCoreApp' and '$(_TargetFrameworkVersionWithoutV)' == '$(NETCoreAppMaximumVersion)'">true</IsNetCoreAppTargetingLatestTFM>
   </PropertyGroup>
 
+  <!--
+    Use Roslyn deployed with SDK for builds of SDK-style projects (regardless of whether the initiator is `dotnet` or `msbuild`).
+    See https://github.com/dotnet/sdk/blob/main/documentation/general/decouple-vs-and-net-sdk.md.
+  -->
+  <Choose>
+    <!-- RoslynCompilerType specified by user, do not overwrite it. -->
+    <When Condition="'$(RoslynCompilerType)' != ''"></When>
+
+    <!-- BuildWithNetFrameworkHostedCompiler specified by user to opt into downloading compiler framework toolset package. -->
+    <When Condition="'$(BuildWithNetFrameworkHostedCompiler)' == 'true'">
+      <PropertyGroup><RoslynCompilerType>FrameworkPackage</RoslynCompilerType></PropertyGroup>
+    </When>
+
+    <!-- On core MSBuild or if we have path to dotnet host, use Core compiler type. -->
+    <When Condition="'$(MSBuildRuntimeType)' == 'Core' or '$(DOTNET_HOST_PATH)' != '' or '$(DOTNET_EXPERIMENTAL_HOST_PATH)' != ''">
+      <PropertyGroup><RoslynCompilerType>Core</RoslynCompilerType></PropertyGroup>
+    </When>
+
+    <!-- Automatically opt users into using the toolset package if they are running an MSBuild other than what this SDK was built against.
+          This is to reduce 'tearing'/dependency mismatch, but as always users can override this behavior by disabling the hosted compiler flag. -->
+    <When Condition="'$(MSBuildRuntimeType)' == 'Full'
+      and '$(BuildWithNetFrameworkHostedCompiler)' == ''
+      and '$(_IsDisjointMSBuildVersion)' == 'true'
+      and ('$(MSBuildProjectExtension)' == '.csproj'
+      or '$(MSBuildProjectExtension)' == '.vbproj')">
+      <PropertyGroup><RoslynCompilerType>FrameworkPackage</RoslynCompilerType></PropertyGroup>
+    </When>
+
+    <!-- Otherwise we must be on full MSBuild, so choose Framework compiler type. -->
+    <Otherwise>
+      <PropertyGroup><RoslynCompilerType>Framework</RoslynCompilerType></PropertyGroup>
+    </Otherwise>
+  </Choose>
+
+  <PropertyGroup Condition="'$(RoslynCompilerType)' == 'Core'">
+    <RoslynTargetsPath Condition="'$(MSBuildRuntimeType)' == 'Core'">$(MSBuildThisFileDirectory)..\..\..\Roslyn</RoslynTargetsPath>
+    <RoslynTargetsPath Condition="'$(MSBuildRuntimeType)' != 'Core'">$(MSBuildThisFileDirectory)..\..\..\Roslyn\binfx</RoslynTargetsPath>
+    <CSharpCoreTargetsPath>$(MSBuildThisFileDirectory)..\..\..\Roslyn\Microsoft.CSharp.Core.targets</CSharpCoreTargetsPath>
+    <VisualBasicCoreTargetsPath>$(MSBuildThisFileDirectory)..\..\..\Roslyn\Microsoft.VisualBasic.Core.targets</VisualBasicCoreTargetsPath>
+  </PropertyGroup>
+
 </Project>
diff --git a/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.Common.targets b/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.Common.targets
@@ -75,17 +75,7 @@ Copyright (c) .NET Foundation. All rights reserved.
   <UsingTask TaskName="NETSdkInformation" AssemblyFile="$(MicrosoftNETBuildTasksAssembly)" />
   <UsingTask TaskName="ShowPreviewMessage" AssemblyFile="$(MicrosoftNETBuildTasksAssembly)" />
 
-  <PropertyGroup Condition="'$(MSBuildRuntimeType)' == 'Full'">
-    <!-- Automatically opt users into using the toolset package if they are running an MSBuild other than what this SDK was built against.
-          This is to reduce 'tearing'/dependency mismatch, but as always users can override this behavior by disabling the hosted compiler flag.
-          This is done in Common.targets so that it applies to ApiCompat which uses RoslynTargetsPath in the outer build. -->
-    <BuildWithNetFrameworkHostedCompiler Condition="'$(BuildWithNetFrameworkHostedCompiler)' == ''
-                                                    and '$(_IsDisjointMSBuildVersion)' == 'true'
-                                                    and ('$(Language)' == 'C#'
-                                                    or '$(Language)' == 'VB')">true</BuildWithNetFrameworkHostedCompiler>
-  </PropertyGroup>
-
-  <PropertyGroup Condition="'$(BuildWithNetFrameworkHostedCompiler)' == 'true' and '$(OS)' == 'Windows_NT' and '$(MSBuildRuntimeType)' == 'Full'">
+  <PropertyGroup Condition="'$(RoslynCompilerType)' == 'FrameworkPackage' and '$(OS)' == 'Windows_NT' and '$(MSBuildRuntimeType)' == 'Full'">
     <RoslynTargetsPath>$(NuGetPackageRoot)\microsoft.net.sdk.compilers.toolset\$(NETCoreSdkVersion)</RoslynTargetsPath>
     <_NeedToDownloadMicrosoftNetSdkCompilersToolsetPackage>true</_NeedToDownloadMicrosoftNetSdkCompilersToolsetPackage>
     <_MicrosoftNetSdkCompilersToolsetPackageRootEmpty Condition="'$(NuGetPackageRoot)' == ''">true</_MicrosoftNetSdkCompilersToolsetPackageRootEmpty>
diff --git a/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.targets b/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.targets
@@ -1235,6 +1235,7 @@ Copyright (c) .NET Foundation. All rights reserved.
          PublicSign="$(PublicSign)"
          PathMap="$(PathMap)"
          Features="$(Features)"
+         CompilerType="$(RoslynCompilerType)"
          DelaySign="$(DelaySign)"
          Deterministic="$(Deterministic)"
          DisabledWarnings="$(DisabledWarnings)"
diff --git a/test/Microsoft.NET.Build.Tests/Microsoft.NET.Build.Tests.csproj b/test/Microsoft.NET.Build.Tests/Microsoft.NET.Build.Tests.csproj
@@ -21,13 +21,16 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Basic.CompilerLog.Util" />
     <PackageReference Include="Microsoft.Build" />
+    <PackageReference Include="MSBuild.StructuredLogger" />
     <PackageReference Include="NuGet.ProjectModel" />
     <PackageReference Include="NuGet.LibraryModel" />
     <PackageReference Include="NuGet.Versioning" />
     <PackageReference Include="NuGet.Configuration" />
     <PackageReference Include="NuGet.Frameworks" />
     <PackageReference Include="NuGet.Common" />
+    <PackageReference Include="Xunit.Combinatorial" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/test/Microsoft.NET.Build.Tests/RoslynBuildTaskTests.cs b/test/Microsoft.NET.Build.Tests/RoslynBuildTaskTests.cs
@@ -0,0 +1,128 @@
+﻿// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Runtime.CompilerServices;
+using Basic.CompilerLog.Util;
+using Microsoft.Build.Logging.StructuredLogger;
+
+namespace Microsoft.NET.Build.Tests;
+
+public sealed class RoslynBuildTaskTests(ITestOutputHelper log) : SdkTest(log)
+{
+    private const string CoreCompilerFileName = "csc.dll";
+    private const string FxCompilerFileName = "csc.exe";
+
+    [FullMSBuildOnlyTheory, CombinatorialData]
+    public void FullMSBuild_SdkStyle(bool useSharedCompilation)
+    {
+        var testAsset = CreateProject(useSharedCompilation);
+        var buildCommand = BuildAndRunUsingMSBuild(testAsset);
+        VerifyCompiler(buildCommand, CoreCompilerFileName, useSharedCompilation);
+    }
+
+    [FullMSBuildOnlyTheory, CombinatorialData]
+    public void FullMSBuild_SdkStyle_OptOut(bool useSharedCompilation)
+    {
+        var testAsset = CreateProject(useSharedCompilation).WithProjectChanges(static doc =>
+        {
+            doc.Root!.Element("PropertyGroup")!.Add(new XElement("RoslynCompilerType", "Framework"));
+        });
+        var buildCommand = BuildAndRunUsingMSBuild(testAsset);
+        VerifyCompiler(buildCommand, FxCompilerFileName, useSharedCompilation);
+    }
+
+    [FullMSBuildOnlyTheory, CombinatorialData]
+    public void FullMSBuild_NonSdkStyle(bool useSharedCompilation)
+    {
+        var testAsset = CreateProject(useSharedCompilation, static project =>
+        {
+            project.IsSdkProject = false;
+            project.TargetFrameworkVersion = "v4.7.2";
+        });
+        var buildCommand = BuildAndRunUsingMSBuild(testAsset);
+        VerifyCompiler(buildCommand, FxCompilerFileName, useSharedCompilation);
+    }
+
+    [Theory, CombinatorialData]
+    public void DotNet(bool useSharedCompilation)
+    {
+        var testAsset = CreateProject(useSharedCompilation);
+        var buildCommand = BuildAndRunUsingDotNet(testAsset);
+        VerifyCompiler(buildCommand, CoreCompilerFileName, useSharedCompilation);
+    }
+
+    private TestAsset CreateProject(bool useSharedCompilation, Action<TestProject>? configure = null, [CallerMemberName] string callingMethod = "")
+    {
+        var project = new TestProject
+        {
+            Name = "App1",
+            IsExe = true,
+            SourceFiles =
+            {
+                ["Program.cs"] = """
+                    class Program
+                    {
+                        static void Main()
+                        {
+                            System.Console.WriteLine(40 + 2);
+                        }
+                    }
+                    """,
+            },
+        };
+
+        // UseSharedCompilation should be the default, so set it only if false.
+        if (!useSharedCompilation)
+        {
+            project.AdditionalProperties["UseSharedCompilation"] = "false";
+        }
+
+        configure?.Invoke(project);
+        return _testAssetsManager.CreateTestProject(project, callingMethod: callingMethod);
+    }
+
+    private TestCommand BuildAndRunUsingMSBuild(TestAsset testAsset)
+    {
+        var buildCommand = new MSBuildCommand(testAsset, "Build");
+        buildCommand.WithWorkingDirectory(testAsset.Path)
+            .Execute("-bl").Should().Pass();
+
+        Run(buildCommand.GetOutputDirectory().File(testAsset.TestProject!.GetOutputFileName()));
+
+        return buildCommand;
+    }
+
+    private TestCommand BuildAndRunUsingDotNet(TestAsset testAsset)
+    {
+        var buildCommand = new DotnetBuildCommand(testAsset);
+        buildCommand.Execute("-bl").Should().Pass();
+
+        Run(buildCommand.GetOutputDirectory().File(testAsset.TestProject!.GetOutputFileName()));
+
+        return buildCommand;
+    }
+
+    private void Run(FileInfo outputFile)
+    {
+        var runCommand = new RunExeCommand(Log, outputFile.FullName);
+        runCommand.Execute().Should().Pass()
+            .And.HaveStdOut("42");
+    }
+
+    private static void VerifyCompiler(TestCommand buildCommand, string compilerFileName, bool usedCompilerServer)
+    {
+        var binaryLogPath = Path.Join(buildCommand.WorkingDirectory, "msbuild.binlog");
+        using (var reader = BinaryLogReader.Create(binaryLogPath))
+        {
+            var call = reader.ReadAllCompilerCalls().Should().ContainSingle().Subject;
+            Path.GetFileName(call.CompilerFilePath).Should().Be(compilerFileName);
+        }
+
+        // Verify compiler server message.
+        var compilerServerMesssages = BinaryLog.ReadBuild(binaryLogPath).FindChildrenRecursive<Message>(
+            static message => message.Text.StartsWith("CompilerServer:", StringComparison.Ordinal));
+        compilerServerMesssages.Should().ContainSingle().Which.Text.Should().StartWith(usedCompilerServer
+            ? "CompilerServer: server - server processed compilation - "
+            : "CompilerServer: tool - using command line tool by design");
+    }
+}
diff --git a/test/Microsoft.NET.Restore.Tests/GivenThatWeWantToUseFrameworkRoslyn.cs b/test/Microsoft.NET.Restore.Tests/GivenThatWeWantToUseFrameworkRoslyn.cs
diff --git a/test/Microsoft.NET.TestFramework/Commands/DotnetBuildCommand.cs b/test/Microsoft.NET.TestFramework/Commands/DotnetBuildCommand.cs
diff --git a/test/Microsoft.NET.TestFramework/ProjectConstruction/TestProject.cs b/test/Microsoft.NET.TestFramework/ProjectConstruction/TestProject.cs
