Remove the PackageReference to Microsoft.AspNetCore.App/All from project files for netcoreapp2.x

[natemcmaster]

Update, Jan 2019: we are not fixing for .NET Core 2, but will address this in .NET Core 3. See #3612.

---

Most NuGet packages provide both compilation and runtime assets. Microsoft.NETCore.App, Microsoft.AspNetCore.App, and Microsoft.AspNetCore.All effectively only provide the first - compilation references. Users must install other runtime assets to make .NET Core apps work but this is not obvious or intuitive, and not always possible: for example, Azure Web Apps, AWS, Google Cloud, etc. This violates a reasonable expectation of using a NuGet package, and has been a continual source of grief for users. Microsoft.NETCore.App had the same issues, but these were largely resolved by (1) making the PackageReference implicit based on TargetFramework and (2) pinning the package version to the lowest stable release. We should follow this pattern in the Microsoft.AspNetCore.App and .All metapackages.

Proposal

These changes are currently open for discussion. I may update this issue as we tweak this proposal.

Change 1

Update Sept. 24: this change will not be implemented.

Remove the PackageReference to Microsoft.AspNetCore.App/All from the .csproj file. Make it implicit when the RuntimeFrameworkName property is set. An ASP.NET Core web project would look like this.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <RuntimeFrameworkName>Microsoft.AspNetCore.App</RuntimeFrameworkName>
  </PropertyGroup>

</Project>

When RuntimeFrameworkName is set, an implicit PackageReference is added to the project, but this will use the IsImplicitlyDefined property, which hides updates from NuGet UI.

The default implicit package reference will stay pinned to version AspNetCore.App 2.1.1 to maximize compatibility with the most deployment environments.

This implicit version will also use the self-contained rollforward mechanism used by Microsoft.NETCore.App today.

If users need to elevate the minimum version of the shared runtime, they can use RuntimeFrameworkVersion (which is already supported by Microsoft.NETCore.App).

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <RuntimeFrameworkName>Microsoft.AspNetCore.App</RuntimeFrameworkName>
    <!-- Less common, but available for users who want to ensure a minimum version. -->
    <RuntimeFrameworkVersion>2.1.789</RuntimeFrameworkVersion>
  </PropertyGroup>

Change 2

Update July 11: this piece will be implemented in 2.1.3, regardless of the other changes. We believe it helps address some issues, even if we don't land Changes 1, 3, and 4 until later. See #3316

All packages which share a dependency with Microsoft.AspNetCore.App should target 2.1.0 unless there is an important reason to force a patched version. This applies to most ASP.NET Core packages, and should also apply to third-party libraries.

We'll start by implementing this within ASP.NET Core on a repo by repo basis. Doing this from package to package within a repo is currently prohibitively expensive. We'll re-evaluate this in 2.2 or 3.0.

Change 3

Update Sept. 24: this change will not be implemented.

Issue warnings when Microsoft.AspNetCore.App/All are explicit references and encourage users to switch to the new implicit reference format. Wording might say something like:

warning: A PackageReference for 'Microsoft.AspNetCore.App' was included in your project.
We recommend removing this and adding the RuntimeFrameworkName property.

 <PropertyGroup>
    <RuntimeFrameworkName>Microsoft.AspNetCore.App</RuntimeFrameworkName>
 </PropertyGroup>

For more information, see https://aka.ms/sdkimplicitrefs

Change 4

Update Sept. 24: this change will not be implemented.

When both RuntimeFrameworkName and an explicit PackageReference are present, issue the same warning that currently exists for Microsoft.NETCore.App. It would look like this:

warning NETSDK1023: A PackageReference for 'Microsoft.AspNetCore.App' was included in your project. This package is implicitly referenced by the .NET SDK and you do not typically need to reference it from your project. For more information, see https://aka.ms/sdkimplicitrefs

Impact

Scenario: 2.1.x patch updates

Currently: users need to update the PackageReference to ensure their packages and the shared runtime stay aligned. Users must install the latest ASP.NET Core shared runtime on their servers.

Change: no modification to the .csproj file would be necessary. Users should install the latest ASP.NET Core shared runtime on their servers.

Scenario: patch updates for ASP.NET Core on .NET Framework

Currently: we cascade version udpates and re-release packages to ensure updating PackageReference hoists all transitives to latest.

Change: if there are changes in transitive dependencies which are important for users to consume, they may need to add new explicit references to get the latest patched versions.

Scenario: Minor releases

Currently: users would need to update the TargetFramework property to netcoreapp2.2 and the PackageReference to Microsoft.AspNetCore.App

Change: users only need to update the TargetFramework property to netcoreapp2.2.

cc @DamianEdwards @davidfowl @dsplaisted @nguerrera @JunTaoLuo @mlorbetske @normj

[nguerrera]

I'm trying to think about the ways in which having a single RuntimeFrameworkName/RuntimeFrameworkVersion pair might be a problem. We need to add an implicit ref to both Microsoft.NETCore.App and Microsoft.AspNetCore.App, right? For example, if I have this example from the description:

    <RuntimeFrameworkName>Microsoft.AspNetCore.App</RuntimeFrameworkName>
    <!-- Less common, but available for users who want to ensure a minimum version. -->
    <RuntimeFrameworkVersion>2.1.789</RuntimeFrameworkVersion>

Am I now forced to use Microsoft.NETCore.App 2.1.0?

[natemcmaster]

We need to add an implicit ref to both Microsoft.NETCore.App and Microsoft.AspNetCore.App, right?

That's one solution, or, we could introduce a package dependency from Microsoft.AspNetCore.App -> Microsoft.NETCore.App. I'm prototyping both approaches today to see which works better.

Am I now forced to use Microsoft.NETCore.App 2.1.0?

In which way do you mean this? ...forced to use the Microsoft.NETCore.App 2.1.0 { package or shared runtime }?

[poke]

What exactly is the plan for non-Web SDK projects? We have to keep in mind that we have library or test projects that may require dependencies from ASP.NET Core. For the latter, we ended up declaring them as Web SDK projects (#3156) although that’s pretty much a work around to get the shared framework working.

While this works for test projects, this is not an option for library projects which should target netstandard. So what exactly is the plan? I would like to see a solution that works equally on all project types because otherwise we will have to end up educating users all the time about when they have to do what – something that didn’t exactly get easier with the decision to add back explicit version numbers.

All packages which share a dependency with Microsoft.AspNetCore.App should target 2.1.0 unless there is an important reason to force a patched version. This applies to most ASP.NET Core packages, and should also apply to third-party libraries.

What is the behavior if they end up targetting a different version though when they require a patched version? Right now we get version conflict errors because of the implicit references of the shared framework. So we cannot actually overwrite anything that’s already part of the framework.

[natemcmaster]

What exactly is the plan for non-Web SDK projects?

I left that piece out because I'm still investigating. My thinking: we should implement the RuntimeFrameworkName property in the non-Web SDK so it works well for console and test projects, but I can't commit to that without more review from @nguerrera and @dsplaisted.

While this works for test projects, this is not an option for library projects which should target netstandard. So what exactly is the plan?

Not planning to address right now. This change is only about netcoreapp2.1 projects. But in general, I would recommend keeping your class libraries using the lowest compatible package version, and then let end-of-line projects upgrade to higher versions.

Right now we get version conflict errors because of the implicit references of the shared framework. So we cannot actually overwrite anything that’s already part of the framework.

Are you using 2.1.0? This sounds like aspnet/Universe#1180, which was address in the 2.1.1 update.

[davkean]

The issue is missing context on how the above proposal fixes:

Users must install other runtime assets to make .NET Core apps work but this is not obvious or intuitive, and not always possible: for example, Azure Web Apps, AWS, Google Cloud, etc.

[natemcmaster]

Updated to add this:

"The default implicit package reference (to Microsoft.AspNetCore.App) will stay pinned to version 2.1.1 to maximize compatibility on deployment."

We hope to never update this package version with new SDK updates. Apps get the latest runtime by updating their deployment environment, not their PackageReference. We let the host do the rollforward to newer versions.

[dasMulli]

A single RuntimeFrameworkVersion may be problem for ASP.NET Core only releases where you only increase the version number of ASP.NET Core but not .NET Core - like the recent 2.0.8 release.
The implicit reference to M.NETCore.App would then fail. Or are you planning to remove that as well and make it a dependency of the shared fx packages?

[natemcmaster]

@nguerrera had the same concern. My thinking is that there only needs to be one implicit package reference, and RuntimeFrameworkName/Version controls what that is. The layered shared frameworks, like AspNetCore.App and .All can use package dependencies to represent the shared runtime layers. e.g. Microsoft.AspNetCore.All (package) depends on AspNetCore.App depends on NETCore.App.

Also, we learned in 2.0.8 that we should keep NETCore.App and AspNetCore.App aligned exactly in version number, so regardless of this proposal, we plan to keep them in sync.

[dasMulli]

In this case, it would be great if the RuntimeFrameworkName logic was implemented in the core (non-web) SDK, this would open up the possibility to use the shared framework in test projects without the side effects of referencing the web sdk (icon, launchSettings.json generation, different globbing patterns, web.config generation on publish etc.).