Avoid package dependencies on libraries in the shared framework (#106172)

* Avoid package dependencies on libraries in the shared framework We can avoid these dependencies since we can count on the library being part of the shared framework. Fewer dependencies means less packages downloaded, less for customers to service, less copied into the output directory when serviced. * Add warning code. * Address feedback
2025-06-08 03:27:04 +09:00 · 2024-08-12 11:15:19 -07:00 · 2024-08-12 11:15:19 -07:00 · 6e440de5b4
commit 6e440de5b4
parent 78f5e8710b
16 changed files with 61 additions and 22 deletions
--- a/docs/coding-guidelines/libraries-packaging.md
+++ b/docs/coding-guidelines/libraries-packaging.md
@ -18,6 +18,14 @@ Source generators and analyzers can be included in the shared framework by addin

 Removing a library from the shared framework is a breaking change and should be avoided.

+### References to libraries in the shared framework that produce packages
+
+It's beneficial to avoid project references to libraries that are in the shared framework because it makes the package graph smaller which reduces the number of packages that require servicing and the number of libraries that end up being copied into the application directory.
+
+If a dependency is part of the shared framework a project/package reference is never required on the latest version (`NetCoreAppCurrent`).  A reference is required for previous .NET versions even if the dependency is part of the shared framework if the project you are building targets .NETStandard and references the project there.  You may completely avoid a package dependency on .NETStandard and .NET if it's not needed for .NETStandard (for example - if it is an implementation only dependency and you're building a PNSE assembly for .NETStandard).
+
+Warning NETPKG0001 is emitted when you have an unnecessary reference to a library that is part of the shared framework.  To avoid this warning, make sure your ProjectReference is conditioned so that it doesn't apply on `NetCoreAppCurrent`.
+
 ## Transport package

 Transport packages are non-shipping packages that dotnet/runtime produces in order to share binaries with other repositories.
--- a/eng/packaging.targets
+++ b/eng/packaging.targets
@ -202,6 +202,21 @@
    </ItemGroup>
  </Target>

+  <Target Name="WarnOnProjectReferenceToFrameworkAssemblies"
+          BeforeTargets="IncludeTransitiveProjectReferences"
+          Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)' and
+                     '@(ProjectReference)' != ''">
+    <!-- Find project references that overlap with NetCoreApp, are direct (NuGetPackageId is not set), actually referenced (ReferenceOutputAssembly), and not hidden with PrivateAssets
+         ProjectReferences can opt out of this checking by setting AllowFrameworkPackageReference, though they should not. -->
+    <Warning Text="Project reference '%(_overlappingProjectFrameworkReference.Identity)' is a reference to a framework assembly and is not required in $(NetCoreAppCurrent) (NetCoreAppCurrent)."
+             Code="NETPKG0001"
+             Condition="$(NetCoreAppLibrary.Contains('%(ProjectReference.Filename);')) and
+                        '%(ProjectReference.ReferenceOutputAssembly)' != 'false' and
+                        '%(ProjectReference.NuGetPackageId)' == '' and
+                        '%(ProjectReference.PrivateAssets)' != 'all' and
+                        '%(ProjectReference.AllowFrameworkPackageReference)' != 'true'" />
+  </Target>
+
  <Target Name="GenerateMultiTargetRoslynComponentTargetsFile"
          Inputs="$(MSBuildProjectFullPath);$(_MultiTargetRoslynComponentTargetsTemplate)"
          Outputs="$(MultiTargetRoslynComponentTargetsFileIntermediatePath)">
--- a/src/libraries/Microsoft.Extensions.Configuration.Json/src/Microsoft.Extensions.Configuration.Json.csproj
+++ b/src/libraries/Microsoft.Extensions.Configuration.Json/src/Microsoft.Extensions.Configuration.Json.csproj
@ -13,9 +13,12 @@
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Configuration.Abstractions\src\Microsoft.Extensions.Configuration.Abstractions.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Configuration.FileExtensions\src\Microsoft.Extensions.Configuration.FileExtensions.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.FileProviders.Abstractions\src\Microsoft.Extensions.FileProviders.Abstractions.csproj" />
-    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
    <Compile Include="$(CommonPath)System\ThrowHelper.cs"
             Link="Common\System\ThrowHelper.cs" />
  </ItemGroup>

+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
+    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
+  </ItemGroup>
+
 </Project>
--- a/src/libraries/Microsoft.Extensions.DependencyModel/src/Microsoft.Extensions.DependencyModel.csproj
+++ b/src/libraries/Microsoft.Extensions.DependencyModel/src/Microsoft.Extensions.DependencyModel.csproj
@ -19,7 +19,7 @@ By default, the dependency manifest contains information about the application's
  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">
    <Compile Remove="**\*.netstandard.cs" />
  </ItemGroup>
-  
+
  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
    <Compile Remove="**\*.netcoreapp.cs" />
    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\RequiresAssemblyFilesAttribute.cs" />
@ -27,10 +27,10 @@ By default, the dependency manifest contains information about the application's
  </ItemGroup>

  <ItemGroup>
-    <InternalsVisibleTo Include="Microsoft.Extensions.DependencyModel.Tests" /> 
+    <InternalsVisibleTo Include="Microsoft.Extensions.DependencyModel.Tests" />
  </ItemGroup>

-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Encodings.Web\src\System.Text.Encodings.Web.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
  </ItemGroup>
@ -43,5 +43,5 @@ By default, the dependency manifest contains information about the application's
  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">
    <Reference Include="System.Runtime" />
  </ItemGroup>
-  
+
 </Project>
--- a/src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Microsoft.Extensions.Diagnostics.Abstractions.csproj
+++ b/src/libraries/Microsoft.Extensions.Diagnostics.Abstractions/src/Microsoft.Extensions.Diagnostics.Abstractions.csproj
@ -33,8 +33,11 @@ Microsoft.Extensions.Diagnostics.Metrics.MetricsOptions</PackageDescription>
    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\DynamicallyAccessedMemberTypes.cs" />
  </ItemGroup>

-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Diagnostics.DiagnosticSource\src\System.Diagnostics.DiagnosticSource.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.DependencyInjection.Abstractions\src\Microsoft.Extensions.DependencyInjection.Abstractions.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Options\src\Microsoft.Extensions.Options.csproj" />
  </ItemGroup>
--- a/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj
+++ b/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/Microsoft.Extensions.Logging.Abstractions.csproj
@ -38,6 +38,10 @@ Microsoft.Extensions.Logging.Abstractions.NullLogger</PackageDescription>
    <PackageReference Include="System.Memory" Version="$(SystemMemoryVersion)" />
  </ItemGroup>

+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
+    <ProjectReference Include="$(LibrariesProjectRoot)System.Diagnostics.DiagnosticSource\src\System.Diagnostics.DiagnosticSource.csproj" />
+  </ItemGroup>
+
  <ItemGroup>
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.DependencyInjection.Abstractions\src\Microsoft.Extensions.DependencyInjection.Abstractions.csproj" />

@ -53,7 +57,6 @@ Microsoft.Extensions.Logging.Abstractions.NullLogger</PackageDescription>
    <ProjectReference Include="..\gen\Microsoft.Extensions.Logging.Generators.Roslyn4.4.csproj"
                      ReferenceOutputAssembly="false"
                      PackAsAnalyzer="true" />
-    <ProjectReference Include="$(LibrariesProjectRoot)System.Diagnostics.DiagnosticSource\src\System.Diagnostics.DiagnosticSource.csproj" /> 
  </ItemGroup>

 </Project>
--- a/src/libraries/Microsoft.Extensions.Logging.Console/src/Microsoft.Extensions.Logging.Console.csproj
+++ b/src/libraries/Microsoft.Extensions.Logging.Console/src/Microsoft.Extensions.Logging.Console.csproj
@ -48,6 +48,9 @@
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Logging.Configuration\src\Microsoft.Extensions.Logging.Configuration.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Logging\src\Microsoft.Extensions.Logging.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Options\src\Microsoft.Extensions.Options.csproj" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
  </ItemGroup>

--- a/src/libraries/Microsoft.Extensions.Logging.EventSource/src/Microsoft.Extensions.Logging.EventSource.csproj
+++ b/src/libraries/Microsoft.Extensions.Logging.EventSource/src/Microsoft.Extensions.Logging.EventSource.csproj
@ -31,7 +31,10 @@
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Logging.Abstractions\src\Microsoft.Extensions.Logging.Abstractions.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Options\src\Microsoft.Extensions.Options.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)Microsoft.Extensions.Primitives\src\Microsoft.Extensions.Primitives.csproj" />
-    <!-- Application tfms (.NETCoreApp, .NETFramework) need to use the same or higher version of .NETStandard's dependencies. -->
+  </ItemGroup>
+
+  <!-- Application tfms (.NETCoreApp, .NETFramework) need to use the same or higher version of .NETStandard's dependencies. -->
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
  </ItemGroup>

--- a/src/libraries/System.Data.Odbc/src/System.Data.Odbc.csproj
+++ b/src/libraries/System.Data.Odbc/src/System.Data.Odbc.csproj
@ -157,8 +157,4 @@ System.Data.Odbc.OdbcTransaction</PackageDescription>
    <None Include="DatabaseSetupInstructions.md" />
  </ItemGroup>

-  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">
-    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Encoding.CodePages\src\System.Text.Encoding.CodePages.csproj" />
-  </ItemGroup>
-
 </Project>
--- a/src/libraries/System.Formats.Nrbf/src/System.Formats.Nrbf.csproj
+++ b/src/libraries/System.Formats.Nrbf/src/System.Formats.Nrbf.csproj
@ -8,7 +8,7 @@
    <PackageDescription>Provides a safe reader for .NET Remoting Binary Format (NRBF) payloads.

 Commonly Used Types:
-System.Formats.Nrbf.NrbfDecoder</PackageDescription>    
+System.Formats.Nrbf.NrbfDecoder</PackageDescription>

    <!-- Disabling baseline validation since this is a brand new package.
         Once this package has shipped a stable version, the following line
@ -17,7 +17,7 @@ System.Formats.Nrbf.NrbfDecoder</PackageDescription>
    <!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
    <EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
  </PropertyGroup>
-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)\System.Reflection.Metadata\src\System.Reflection.Metadata.csproj" />
  </ItemGroup>
  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">
--- a/src/libraries/System.Memory.Data/src/System.Memory.Data.csproj
+++ b/src/libraries/System.Memory.Data/src/System.Memory.Data.csproj
@ -23,7 +23,7 @@ System.BinaryData</PackageDescription>
    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\RequiresDynamicCodeAttribute.cs" />
  </ItemGroup>

-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
  </ItemGroup>

--- a/src/libraries/System.Net.Http.Json/src/System.Net.Http.Json.csproj
+++ b/src/libraries/System.Net.Http.Json/src/System.Net.Http.Json.csproj
@ -48,15 +48,17 @@ System.Net.Http.Json.JsonContent</PackageDescription>
    <Compile Include="System\Net\Http\Json\TranscodingWriteStream.cs" />
  </ItemGroup>

-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Json\src\System.Text.Json.csproj" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)'">
+    <Reference Include="System.IO.Pipelines" />
    <Reference Include="System.Memory" />
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Net.Primitives" />
    <Reference Include="System.Runtime" />
+    <Reference Include="System.Text.Json" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
--- a/src/libraries/System.Reflection.Metadata/src/System.Reflection.Metadata.csproj
+++ b/src/libraries/System.Reflection.Metadata/src/System.Reflection.Metadata.csproj
@ -264,7 +264,7 @@ The System.Reflection.Metadata library is built-in as part of the shared framewo
    <Compile Include="$(CommonPath)System\Text\ValueStringBuilder.AppendSpanFormattable.cs" Link="System\Text\ValueStringBuilder.AppendSpanFormattable.cs" Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'" />
  </ItemGroup>

-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Collections.Immutable\src\System.Collections.Immutable.csproj" />
  </ItemGroup>

@ -274,6 +274,7 @@ The System.Reflection.Metadata library is built-in as part of the shared framewo

  <ItemGroup Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)'">
    <Reference Include="System.Collections" />
+    <Reference Include="System.Collections.Immutable" />
    <Reference Include="System.IO.Compression" />
    <Reference Include="System.IO.MemoryMappedFiles" />
    <Reference Include="System.Memory" />
--- a/src/libraries/System.Reflection.MetadataLoadContext/src/System.Reflection.MetadataLoadContext.csproj
+++ b/src/libraries/System.Reflection.MetadataLoadContext/src/System.Reflection.MetadataLoadContext.csproj
@ -158,8 +158,8 @@
    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\RequiresUnreferencedCodeAttribute.cs" />
  </ItemGroup>

-  <ItemGroup>
-    <!-- Application tfms (.NETCoreApp, .NETFramework) need to use the same or higher version of .NETStandard's dependencies. -->
+  <!-- Application tfms (.NETCoreApp, .NETFramework) need to use the same or higher version of .NETStandard's dependencies. -->
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Collections.Immutable\src\System.Collections.Immutable.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)System.Reflection.Metadata\src\System.Reflection.Metadata.csproj" />
  </ItemGroup>
--- a/src/libraries/System.Security.Cryptography.Pkcs/src/System.Security.Cryptography.Pkcs.csproj
+++ b/src/libraries/System.Security.Cryptography.Pkcs/src/System.Security.Cryptography.Pkcs.csproj
@ -651,7 +651,7 @@ System.Security.Cryptography.Pkcs.EnvelopedCms</PackageDescription>
    <None Include="@(AsnXml)" />
  </ItemGroup>

-  <ItemGroup Condition="'$(IsPartialFacadeAssembly)' != 'true'">
+  <ItemGroup Condition="'$(IsPartialFacadeAssembly)' != 'true' and '$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Formats.Asn1\src\System.Formats.Asn1.csproj" />
  </ItemGroup>

--- a/src/libraries/System.Text.Json/src/System.Text.Json.csproj
+++ b/src/libraries/System.Text.Json/src/System.Text.Json.csproj
@ -395,7 +395,7 @@ The System.Text.Json library is built-in as part of the shared framework in .NET
  </ItemGroup>

  <!-- Application tfms (.NETCoreApp, .NETFramework) need to use the same or higher version of .NETStandard's dependencies. -->
-  <ItemGroup>
+  <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
    <ProjectReference Include="$(LibrariesProjectRoot)System.Text.Encodings.Web\src\System.Text.Encodings.Web.csproj" />
    <ProjectReference Include="$(LibrariesProjectRoot)System.IO.Pipelines\src\System.IO.Pipelines.csproj" />
  </ItemGroup>
@ -403,6 +403,7 @@ The System.Text.Json library is built-in as part of the shared framework in .NET
  <ItemGroup Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)'">
    <Reference Include="System.Collections" />
    <Reference Include="System.Collections.Concurrent" />
+    <Reference Include="System.IO.Pipelines" />
    <Reference Include="System.Memory" />
    <Reference Include="System.Numerics.Vectors" />
    <Reference Include="System.Reflection.Emit.ILGeneration" />
@ -413,8 +414,9 @@ The System.Text.Json library is built-in as part of the shared framework in .NET
    <Reference Include="System.Runtime.Intrinsics" />
    <Reference Include="System.Runtime.Loader" />
    <Reference Include="System.Text.Encoding.Extensions" />
-    <Reference Include="System.Threading" />
+    <Reference Include="System.Text.Encodings.Web" />
    <Reference Include="System.Text.RegularExpressions" />
+    <Reference Include="System.Threading" />
  </ItemGroup>
  
  <ItemGroup>