NuGet Errors and Warnings

Issue

NuGet #4895: NET Core 2.0: Register all warnings/errors to assets file (including PackageTargetFallback)

Problem

The following user scenarios are driving this feature:

1. A NuGet warning can be overridden as errors, by the developer from Project properties and/or csproj file.
2. A NuGet warning can be suppressed by the developer from Project properties and/or csproj file.
3. Per Package NuGet warning can be suppressed by the developer from Project properties and/or csproj file.
4. NuGet warnings should follow warning-levels defined in Project just like any other warnings in the project.

Who is the customer?

All developers who use NuGet using PackageReference. .NET Core, .NET Standard and other projects (opted-in to use PackageReference).

Evidence

As stated in the problem.

Solution

• All the NuGet warnings will be coded. List of all the numbered warnings can be found here - Restore errors and warnings
• These errors and warnings will be written into the assets file so that msbuild can output these errors appropriately.

Warning Properties

NuGet supports 3 warning properties in PackageReference based projects at project wide level -

• TreatWarningsAsErrors - Treat all NuGet warnings as errors <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
• WarningsAsErrors - Treat specific warnings as errors <WarningsAsErrors>NU1605</WarningsAsErrors>
• NoWarn - Hide Specific warnings <NoWarn>NU1701</NoWarn>

NuGet also supports 1 warning property at package reference level -

• NoWarn - Hide Specific warnings - <PackageReference Include="NuGet.Versioning" Version=4.6.9 NoWarn="NU1603">

Lastly, NuGet also supports Transitive NoWarn.

The Warning properties are represented in memory using the WarningProperties. ProjectRestoreMetadata contains an instance of warning properties for the project here. The package specific NoWarn properties are represented using PackageSpecificWarningProperties.

The cumulative warning properties are stored in WarningPropertiesCollection. During restore the warning properties collection is instantiated in RestoreCollectorLogger here.

Restore Collector Logger

RestoreCollectorLogger was created to allow consumption of warning properties. It is instantiated by RestoreCommand here. RestoreCollectorLogger is responsible for enforcing the warning properties to any restore log message.
When an ILogMessage is passed to RestoreCollectorLogger it first checks if it is warning and it needs to be suppressed. If the message is not yet suppressed then it checks of the message is a warning and it needs to be upgraded to an error. Hence it implies and order of preference such that NoWarn is preferred over the other 2 properties. For all Package reference based projects, the RestoreCollectorLogger writes all the errors and un-suppressed warnings into the assets file as IAssetsLogMessage.

Transitive Warning Properties

NuGet also supports NoWarn property through P2P references such that is a lower level project has NoWarn'ed a code, then no higher level project will see that warning in its closure during restore. The detailed spec for the feature is here.

The implementation is in TransitiveNoWarnUtils. The method CreateTransitiveWarningPropertiesCollection is called by RestoreCollectorLogger to collect the NoWarn properties from all the preferenced projects in the closure. This is then used to suppressed warnings here.

Displaying Errors and Warnings

NuGet is logging is split between the three project types -

• .NET SDK based projects - For these projects NuGet does not log errors and warnings in Visual Studio. We write them into the assets file and the .NET sdk then displays them in Visual Studio. You can see the sdk code here. To prevent logging of error and warnings, we use ProjectRestoreSettings.HideWarningsAndErrors. This property is set to true only for sdk based projects here and used here.
• Legacy csproj based projects - For these projects, NuGet is responsible for logging all the errors and warnings in Visual Studio.
• Packages.Config based projects - For these projects, NuGet is responsible for logging all the errors and warnings in Visual Studio. However, there is no support for warning properties in packages.config based projects.

Appendix

User Scenarios

Scenario-1: A NuGet warning can be overridden as errors, by the developer from Project properties and/or csproj file

1. User creates a new project that references NuGet.Packaging 3.5.0 that references NuGet.Versioning 3.5.0
2. User now another package dependency NuGet.Commands 4.0.0 that has dependency to NuGet.Versioning 4.0.0 as shown in the dependency tree: NuGet.Commands 4.0.0 -> NuGet.Configuration 4.0.0 -> NuGet.Versioning 4.0.0
3. User gets a downgrade warning (NU1605):

Detected package downgrade: NuGet.Versioning from 4.0.0 to 3.5.0
  NuGet.Packaging 3.5.0 -> NuGet.Versioning 3.5.0
  NuGet.Commands 4.0.0 -> NuGet.Configuration 4.0.0 -> NuGet.Versioning 4.0.0

4. User now adds the warning (NU1605) as error in the Project.Properties.Build UI:
5. Alternatively, user can write the following in the csproj file to treat this warning as error:

Was <TreatSpecificWarningsAsErrors>NU1605</TreatSpecificWarningsAsErrors>

New <WarningsAsErrors>NU1605</WarningsAsErrors> based on https://github.com/dotnet/project-system/pull/2368#issuecomment-305868038

6. User now sees this downgrade as an error.

Scenario-2: A NuGet warning can be suppressed by the developer from Project properties and/or csproj file.

1. User creates a new NET Standard 2.0 project
2. User add NuGet reference to Microsoft.Composition package – this gets added due to PackageTargetFallBack
3. User sees the following warning(NU1701) as part of each build: Package 'Microsoft.Composition' was restored using 'net461' instead the project target framework 'netstandard2.0'. This may cause compatibility problems.
4. User can suppress this warning(NU1701) totally for the project so that any warning w.r.t PackageTargetFallback is never shown for the project in Project.Properties.Build UI as follows:
   
5. Alternatively, user can suppress this warning(NU1701) by using the following line in the csproj file: <NoWarn>NU1701</NoWarn>

Scenario-3: Per Package NuGet warning can be suppressed by the developer from Project properties and/or csproj file.

1. User creates a new NET Standard 2.0 project
2. User add NuGet reference to Microsoft.Composition package – this gets added due to PackageTargetFallBack
3. User sees the following warning(NU1701) as part of each build: Package 'Microsoft.Composition' was restored using 'net461' instead the project target framework 'netstandard2.0'. This may cause compatibility problems.
4. User can suppress this warning(NU1701) specific to the package 'Microsoft.Composition' in the package dependency property:

5. User can do the same by specifying the suppression in the csproj file (comma or semi-colon separated list of warnings):

    <PackageReference Include="Contoso.Base.API" Version="1.0.3">
      <NoWarn>NU1701</NoWarn>
    </PackageReference>

Scenario-4: NuGet warnings should follow warning-levels defined in Project just like any other warnings in the project.

1. User creates a new NET Standard 2.0 project
2. User goes to Project.Properties.Build and sets the Warning level as 1:
3. Alternatively, in the csproj file, the users sets the following to set the Warning level as 1: <WarningLevel>1</WarningLevel>
4. User now only sees severe warnings and not the other warnings. TBD Classification of warnings into levels 1 through 4.

NET Core 2.0 scenarios

1. Package downgrades should be errors for .Net Core 2.0 projects. (As per requirements by the team)
2. PackageTargetFallback warnings should be ignored for certain package dependencies if developer knows that a package is being brought into the project due to PackageTargetFallback and does not want be reminded again and again for each restore.

Scenario-1: Package downgrades should be errors for .Net Core 2.0 projects.

1. User creates a new project that directly references “Microsoft.AspNetCore.Hosting” 1.0.0
2. User now adds a new reference “Microsoft.AspNetCore” 1.1.0 that references “Microsoft.AspNetCore.Hosting” 1.0.0
3. “Microsoft.AspNetCore.Hosting” package currently gets pinned to the lower version, rather than getting lifted to the version depended upon by the Core package.
4. User gets the downgrade error - This was originally a warning that this project type treats as an error.
5. User should be able to go to package reference properties, see this warning is an error and be able to clear it to make the current error back to warning.

Scenario-2: 3. PackageTargetFallback warnings should be ignored for certain package dependencies...

1. User creates a new NET Standard 2.0 project
2. User add NuGet reference to Microsoft.Composition package – this gets added due to PackageTargetFallBack
3. User sees the following warning(NU1701) as part of each build: Package 'Microsoft.Composition' was restored using 'net461' instead the project target framework 'netstandard2.0'. This may cause compatibility problems.
4. User can suppress this warning(NU1701) totally for the project so that any warning w.r.t PackageTargetFallback is never shown for the project.
5. User can suppress this warning(NU1701) for only Microsoft.Composition package so that the warning does not show for Microsoft.Composition package but it will show for newer such packages added due to PackageTargetFallback.
6. Suppression mechanisms (TBD)