[Feature Request] Support building with preview versions of the .NET SDK

[martincostello]

Is your feature request related to a problem? Please describe.

Testing applications out with the .NET 9 Preview 1 SDK, it's not possible to build sites using docfx that have a net9.0 target framework.

This appears to be due to the code below, which requires that the SDK used is the same version as the runtime version docfx uses.

docfx/src/Docfx.Dotnet/CompilationHelper.cs

Lines 135 to 159 in bebcd35

	private static IEnumerable<MetadataReference> GetDefaultMetadataReferences(string language)
	{
	try
	{
	// Get current .NET runtime version with `{major}.{minor}` format.
	var dotnetMajorMinorVersion = Environment.Version.ToString(2);
	// Resolve .NET SDK packs directory path. (e.g. `C:\Program Files\dotnet\packs\Microsoft.NETCore.App.Ref\8.0.2\ref\net8.0`)
	var dotnetExeDirectory = DotNetCorePathFinder.FindDotNetExeDirectory();
	var refDirectory = Path.Combine(dotnetExeDirectory, "packs/Microsoft.NETCore.App.Ref");
	var version = new DirectoryInfo(refDirectory).GetDirectories().Select(d => d.Name).Where(x => x.StartsWith(dotnetMajorMinorVersion)).Max()!;
	var moniker = new DirectoryInfo(Path.Combine(refDirectory, version, "ref")).GetDirectories().Select(d => d.Name).Where(x => x.EndsWith(dotnetMajorMinorVersion)).Max()!;
	var path = Path.Combine(refDirectory, version, "ref", moniker);
	Logger.LogInfo($"Compiling {language} files using .NET SDK {version} for {moniker}");
	Logger.LogVerbose($"Using SDK reference assemblies in {path}");
	return Directory.EnumerateFiles(path, "*.dll", SearchOption.TopDirectoryOnly)
	.Select(CreateMetadataReference);
	}
	catch (Exception ex)
	{
	Logger.LogVerbose(ex.ToString());
	throw new DocfxException("Cannot find .NET Core SDK to compile the project.");
	}
	}

Even if the .NET 8 SDK is installed, in addition to .NET 9's, and DOTNET_ROLLFORWARD=Major is set, docfx will still and try to use the .NET 8 SDK to build for .NET 9, which fails.

Using .NET Core SDK 8.0.200
Loading project 
/runner/_work/MyProject/MyProject/src/MyProject/MyProject.csproj
  Determining projects to restore...
Error: /usr/share/dotnet/sdk/8.0.200/Sdks/Microsoft.NET.Sdk/targets/Microsoft.NET.TargetFrameworkInference.targets(166,5): error NETSDK1045: The current .NET SDK does not support targeting .NET 9.0.  Either target .NET 8.0 or lower, or use a version of the .NET SDK that supports .NET 9.0. Download the .NET SDK from https://aka.ms/dotnet/download [/runner/_work/MyProject/MyProject/src/MyProject/MyProject.csproj::TargetFramework=net9.0]

Describe the solution you'd like

docfx allows the use of newer .NET SDKs if installed in the execution environment.

Describe alternatives you've considered

Wait until November until .NET 9 is released and ignore my failing documentation builds.

Additional context

None.

[filzrev]

The above CompilationHelper.cs logic is used for C#/VB source-based build only.
When generating API metadata with .csproj it's not used.

Using .NET Core SDK 8.0.200 log message is recorded by following lines.

docfx/src/Docfx.Dotnet/DotnetApiCatalog.cs

Lines 129 to 145 in bebcd35

	private static void EnsureMSBuildLocator()
	{
	try
	{
	if (!MSBuildLocator.IsRegistered)
	{
	var vs = MSBuildLocator.RegisterDefaults() ?? throw new ExtractMetadataException(
	$"Cannot find a supported .NET Core SDK. Install .NET Core SDK {Environment.Version.Major}.{Environment.Version.Minor}.x to build .NET API docs.");
	Logger.LogInfo($"Using {vs.Name} {vs.Version}");
	}
	}
	catch (Exception e)
	{
	throw new ExtractMetadataException(e.Message, e);
	}
	}

MSBuildLocator resolve SDKs whose version is lower than the current .NET runtime.
So .NET 9 features will not be supported until targetFrameworks net9.0 are added to docfx. (Related issue #9609)
https://github.com/dotnet/docfx/blob/main/Directory.Build.props#L4

[martincostello]

It's a shame that roll-forward isn't causing that behaviour to change - that's often a good-enough workaround when I test pre-release versions of .NET where I use global tools that don't yet support them.

[filzrev]

If DOTNET_ROLLFORWARD=Major is specified.
Runtime will not be roll forwarded if the target runtime is already installed.
https://learn.microsoft.com/en-us/dotnet/core/versions/selection#values

To force to use .NET9 runtime.
You must set the following environment variables.

• DOTNET_ROLL_FORWARD=LatestMajor
• DOTNET_ROLL_FORWARD_TO_PRERELEASE=1

Note

It can't use .NET 9 specific features by above settings.
Because It needs to update Roslyn packages (Microsoft.CodeAnalysis) to latest prerelease versions

[martincostello]

Setting those two environment variables was enough to get things building in my branch:

[yufeih]

We can introduce official support for .NET 9 when we retire .NET 7 in May. Supporting a new .NET framework version increases distribution package size.

[filzrev]

This issue can be closed.
Because .NET 9 support is added from docfx 2.78,0.

[martincostello]

This issue is about previews in general, not support for .NET 9 specifically - if .NET 10 preview 1 has the same problems, then it's still relevant.