Discussion about how references are defined in libraries

[ViktorHofer]

In runtime's libraries there are different ways to reference a dependency:

• ProjectReference: If a compatible live configuration of a dependency exists, a ProjectReference should be used. Exception: $(NetCoreAppCurrent) targeting pack references from runtime pack assemblies are currently not represented as ProjectReference but Reference items to minimize incremental build costs (including netstandard.dll).
• Reference: If a compatible live configuration of a dependency doesn't exist and the assembly is part of the targeting pack (framework reference), a Reference should be used.
• PackageReference: If a compatible live configuration of a dependency doesn't exist and the assembly isn't part of the targeting pack (framework reference), a PackageReference should be used. Example: System.Memory for netstandard2.0.

For someone who doesn't work full time on runtime's infrastructure, it's hard to reason about when to use which of the ItemTypes above. AspNetCore doesn't use ProjectReference items in the project file and dynamically construct the ProjectReference items based on Reference items.

I would like to discuss if it there's value in simplifying how references in runtime's libraries are defined. This could be accomplished by consolidating on one of the above item types or by introducing a new one i.e. DynamicReference.

Requirements

Such a system needs to work with "msbuild static graph" which we depend on to restore projects. That said, it should be fine to depend on a target, as static graph restore invokes certain targets and static graph build (from my perspective) will likely need to support that as well.

Additional information

• The DisableImplicitFrameworkReferences msbuild property defines if a targeting pack is "consumed" by the project. In dotnet/runtime this property defaults to true for $(NetCoreAppCurrent) ref and src assemblies which are inbox.

@ericstj @joperezr @safern @Anipik @eerhardt and @dougbu @wtgodbe (for thoughts about what aspnetcore's infra does well and what not)

Tagging subscribers to this area: @safern, @ViktorHofer
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Currently there are different ways and reasons to reference an assembly, project or package:

• ProjectReference: If a compatible live configuration of a dependency exists, a ProjectReference should be used. Exception: $(NetCoreAppCurrent) targeting pack references from runtime pack assemblies are currently not represented as ProjectReference but Reference items to minimize incremental build costs (including netstandard.dll).
• Reference: If a compatible live configuration of a dependency doesn't exist and the assembly is part of the targeting pack (framework reference), a Reference should be used.
• PackageReference: If a compatible live configuration of a dependency doesn't exist and the assembly isn't part of the targeting pack (framework reference), a PackageReference should be used. Example: System.Memory for netstandard2.0.

For someone who doesn't work full time on runtime's infrastructure, it's hard to reason about when to use which of the ItemTypes above. AspNetCore doesn't use ProjectReference items in the project file and dynamically construct the ProjectReference items based on Reference items.

I would like to discuss if it there's value in simplifying how references in runtime's libraries are defined. This could be accomplished by i.e. consolidating on one of the above item types or by introducing a new one i.e. DynamicReference.

A requirement is that such a system needs to work with msbuild static graph. That said, it should be fine to depend on a target, as static graph restore invokes certain targets and static graph build (from my perspective) will likely need to support that as well.

@ericstj @joperezr @safern @Anipik @eerhardt and @dougbu @wtgodbe (for thoughts about what aspnetcore's infra does well and what not)

Author:	ViktorHofer
Assignees:	ViktorHofer
Labels:	Discussion, area-Infrastructure-libraries
Milestone:	Future

[joperezr]

I definitely see value on adding something that abstracts this concept from most devs as at least I get asked this question relatively often. That said, it is not super common to add new references to projects (meaning most PRs don't have to do this) so one thing we could consider is simply erroring when detecting that the wrong item was used without trying to attempt to fix it. This is only a suggestion based on thinking that perhaps the cost of adding logic to detect the wrong item vs the logic of consolidating to the right one (while still making sure that it happens at the right time for restore and RAR etc) might be considerably different.

[dougbu]

thoughts about what aspnetcore's infra does well and what not

dotnet/aspnetcore almost never uses <PackageReference /> or <ProjectReference /> in our C# projects. Instead we use <Reference /> elements and convert them to @(ProjectReference) items as part of MSBuild evaluation and to @(PackageReference) items later, in a ResolveCustomReferences target that runs e.g. before ResolvePackageAssets.

This works relatively well but is a bit confusing for new members of our dev community because <Reference /> doesn't have its usual meaning (includes assembly names instead of assembly locations) and because those adding new projects or moving sources around need to update our mappings to project locations and package versions. We've also had to service this part of the code a few times, a downside for the build v-team. Fortunately, we don't get much pushback from the community and the code involved is pretty well commented these days. See https://github.com/dotnet/aspnetcore/blob/main/eng/targets/ResolveReferences.targets and the few files providing mappings, mostly https://github.com/dotnet/aspnetcore/blob/main/eng/Dependencies.props (notice the item group at the bottom) and https://github.com/dotnet/aspnetcore/blob/main/eng/ProjectReferences.props

The main historical benefit was our ability to use "baseline" package references when rebuilding in servicing instead of rebuilding everything. Effectively our 2.1 branch builds primarily against the previous (say) 2.1.24 release except for the few projects we're patching in 2.1.25.

The benefits aren't as obvious in 3.1 and later. But, it still makes our *.csproj files smaller and avoids having package versions spread throughout the repo.

[ericstj]

Being at the bottom of the stack I think it's pretty important to have the distinction between PackageReference and Reference|ProjectReference. This is an indication of whether the project expects and live-built library or a previously shipped one. I think it's important to record and track changes like that at the consumption site.

I'm less interested in the difference between Reference and ProjectReference. These differences are side-effects of how we choose to architect the build infra. Forcing developers to understand this isn't particularly meaningful. Tracking changes to those in individual projects isn't helpful either.

I do think we need to maintain granular references for things inside the shared framework. This helps us hold the line on architectural layering.