Produce reference assemblies for Microsoft.AspNetCore.App

[natemcmaster]

In order to satisfy the requirements of making Microsoft.AspNetCore.App a ref-only package (#3608), we need to change our build system to produce reference assemblies for API in Microsoft.AspNetCore.App.

Requirements

• Reference assemblies do not contain implementation.
• API breaking changes to any assembly in Microsoft.AspNetCore.App are not allowed after 3.0.0
• Reference assemblies must not change assembly version in patch updates. They remain constant at "Version=3.0.0.0" for the lifetime of netcoreapp3.0.
• Assembly version bumps when the TFM changes. So when/if netcoreapp3.1 comes along, assemblies change to "Version=3.1.0.0"
• Implementation binaries must satisfy the API surface of the reference assembly
• When Microsoft.Extensions.* APIs are used in projects targeting .NET Framework, automatic binding redirect generation must continue to work correctly

Proposed solution

1. Generate source for ref assemblies

We use build tools from https://github.com/dotnet/arcade to generate reference assemblies from implementation projects. This generated source lives in the repo next to the implementation. Most assemblies in the shared framework will have a folder layout like this:

.../Microsoft.AspNetCore.Mvc/
	ref/
		Microsoft.AspNetCore.Mvc.csproj
		Microsoft.AspNetCore.Mvc.cs       (generated by tools, should not be hand edited)
	src/
		Microsoft.AspNetCore.Mvc.csproj
		**/*.cs       (code for the implementation of Microsoft.AspNetCore.Mvc.dll)
	test/ (optional - unit tests)
		Microsoft.AspNetCore.Mvc.Tests.csproj
		**/*.cs       (test code)

2. Implement tests to ensure implementation matches the ref API

Wire up the build to use tools from https://github.com/dotnet/arcade which assert that the implementation binaries are binary compatible with their reference assemblies. This is essential to making sure patches don't break API.

Open questions

• How to structure NuGet packages and set assembly versions without introducing downgrade errors or producing incorrect binding redirects?

[Eilon]

This proposal looks reasonable to me.

[dsplaisted]

When Microsoft.Extensions.* APIs are used in projects targeting .NET Framework, automatic binding redirect generation must continue to work correctly

This may be problematic. The binding redirects are generated based on the compile graph. So if any binding redirects are generated, it will be to the version of the ref assembly. Probably this means that the Microsoft.Extensions packages should not include the reference assemblies, they should only be used in the targeting pack for ASP.NET Core.

[natemcmaster]

My main concern is about servicing updates. I think we can make 3.0.0 work fine. It's 3.0.1 that we need to think through. I'll add to this issue that we need to design how ref assemblies and assembly versions should work so that we can keep .NET Framework and .NET Core happy.

[Eilon]

This appears to be done. I have a build and inside of C:\Program Files\dotnet\packs\Microsoft.AspNetCore.App.Ref\3.0.0-preview4-19162-05\ref\netcoreapp3.0 I have ref-only DLLs, plus the matching XML files.

We're not sure what this means:

Open questions

• How to structure NuGet packages and set assembly versions without introducing downgrade errors or producing incorrect binding redirects?

[Eilon]

@natemcmaster - can you provide some info on the "Open question" above? Is this done, or is there more work remaining?

[natemcmaster]

Work remaining: ensure these requirements are met (they are not currently). This will require a combination of writing tests and changing some MSbuild goop.

• Reference assemblies must not change assembly version in patch updates. They remain constant at "Version=3.0.0.0" for the lifetime of netcoreapp3.0.
• Implementation binaries must satisfy the API surface of the reference assembly
• API breaking changes to any assembly in Microsoft.AspNetCore.App are not allowed after 3.0.0

[Eilon]

Got it. I'm closing this issue as Done for preview 4, because the bulk of the work was completed. I logged #9479 to track the remaining work for a later milestone.