ReferenceTrimmer 3.2.4
See the version list below for details.
dotnet add package ReferenceTrimmer --version 3.2.4
NuGet\Install-Package ReferenceTrimmer -Version 3.2.4
<PackageReference Include="ReferenceTrimmer" Version="3.2.4"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add ReferenceTrimmer --version 3.2.4
#r "nuget: ReferenceTrimmer, 3.2.4"
// Install ReferenceTrimmer as a Cake Addin #addin nuget:?package=ReferenceTrimmer&version=3.2.4 // Install ReferenceTrimmer as a Cake Tool #tool nuget:?package=ReferenceTrimmer&version=3.2.4
ReferenceTrimmer
Easily identify which C# dependencies can be removed from an MSBuild project, and expose MSVC output to show unused libraries and delay-load DLLs at link time. Removing project dependencies flattens your build dependency graph which can improve build parallelism and reduce end-to-end build time.
Rules
The following warnings are generated by this package:
Id | Description |
---|---|
RT0000 | Enable documentation generation for accuracy of used references detection |
RT0001 | Unnecessary reference |
RT0002 | Unnecessary project reference |
RT0003 | Unnecessary package reference |
How to use
Add a package reference to the ReferenceTrimmer package in your projects, or as a common package reference in the repo's Directory.Packages.props
.
If you're using Central Package Management, you can use it as a GlobalPackageReference
in your Directory.Packages.props
to apply it to the entire repo.
<ItemGroup>
<GlobalPackageReference Include="ReferenceTrimmer" Version="{LatestVersion}" />
</ItemGroup>
C#
You'll need to enable C# documentation XML generation to ensure good analysis results. If your repo is not already using docxml globally, this can introduce a large number of errors and warnings specific to docxml. Additionally, turning on docxml adds additional output I/O that can slow down large repos.
You can turn off specific docxml related warnings and errors while defaulting ReferenceTrimmer to off using a block of code like this in your Directory.Build.props
. Turn on the ReferenceTrimmer build by setting /p:EnableReferenceTrimmer=true
on the MSBuild command line or setting the same property value as an environment variable. You could create a separate build pipeline for your repo to run ReferenceTrimmer builds.
<PropertyGroup Label="ReferenceTrimmer">
<EnableReferenceTrimmer Condition=" '$(EnableReferenceTrimmer)' == '' ">false</EnableReferenceTrimmer>
</PropertyGroup>
<PropertyGroup Condition=" '$(EnableReferenceTrimmer)' == 'true' and '$(GenerateDocumentationFile)' != 'true' " Label="ReferenceTrimmer">
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);419;1570;1573;1574;1584;1591;SA1602</NoWarn>
</PropertyGroup>
Note: To get better results, enable the IDE0005
unnecessary using
rule. This avoids the C# compiler seeing a false positive assembly usage from unneeded using
directives causing it to miss a removable dependency. See also the note for why IDE0005 code analysis rule requires <GenerateDocumentationFile>
property to be enabled. Documentation generation is also required for accuracy of used references detection (based on https://github.com/dotnet/roslyn/issues/66188).
C++ (.vcxproj projects)
ReferenceTrimmer for C++ is an MSBuild distributed logger. It writes guidance to the MSBuild stdout stream (not to the MSBuild internal logger at this time) and writes ReferenceTrimmerUnusedMSVCLibraries.json.log
to the build working directory.
The distributed logger requires configuration at the MSBuild command line using the -distributedlogger
parameter. See the BuildWithReferenceTrimmer example script for how to orchestrate pulling and using the package's loggers.
Use msbuild -restore
or msbuild /t:Restore
instead of dotnet restore
to ensure .vcxproj restore will work to add the ReferenceTrimmer props and targets to your build. NOTE: If you are seeing a Sequence contains no elements
exception from MSBuild, see https://github.com/dotnet/NuGet.BuildTasks/issues/154 for a workaround or status on a fix.
The current implementation turns on MSVC link.exe
flags /VERBOSE:UNUSEDLIBS
and /VERBOSE:UNUSEDDELAYLOAD
. These flags tell the linker to print out unused .lib files and delay-load DLLs to stdout. This will include .lib files containing code bundles as well as import libraries for DLLs. Removing these libraries reduces I/O and memory usage by the linker. Here's an example of the linker output:
Unused libraries:
C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x64\gdi32.lib
C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x64\winspool.lib
C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x64\comdlg32.lib
ReferenceTrimmer reads this output and splits the resulting libraries into two sets:
Windows SDK import libraries
The Microsoft C++ SDK for MSBuild includes in the AdditionalDependencies
property a default list of Win32 import libraries like kernel32.lib and user32.lib. You can find the default list in your local VS installation by searching:
findstr /s CoreLibraryDependencies "\Program Files"\*props
To disable these, modify the vcxproj <AdditionalDependencies>
property to just the list of SDK .lib files needed for the project, and do not add %(AdditionalDependencies)
to the property to avoid the default list. Example:
<ItemDefinitionGroup>
<Link>
<AdditionalDependencies>kernel32.lib;shlwapi.lib;ws2_32.lib</AdditionalDependencies>
</Link>
</ItemDefinitionGroup>
Not all SDK .lib files can be removed this way. You might need to use <IgnoreSpecificDefaultLibraries>
as well:
<ItemDefinitionGroup>
<Link>
<IgnoreSpecificDefaultLibraries>OLDNAMES.lib;%(IgnoreSpecificDefaultLibraries)</IgnoreSpecificDefaultLibraries>
</Link>
</ItemDefinitionGroup>
Package or Project libraries
If you find an unused .lib that is created by a .vcxproj in your repo, you should be able to remove the ProjectReference
to that vcxproj to improve your build dependency graph and allow greater parallelism during build.
If you find an unused .lib that is from a package, remove the reference to that .lib from your project to speed up linking.
Disabling a rule on a reference
To turn off a rule on a specific project or package reference, add the relevant RTxxxx code to a NoWarn metadata attribute. For example:
<ProjectReference Include="../Other/Project.csproj" NoWarn="RT0002" />
Configuration
$(EnableReferenceTrimmer)
- Controls whether the build logic should run for a given project. Defaults to true
.
$(ReferenceTrimmerEnableVcxproj)
- Controls whether MSVC link flags are set up to print out unused libraries and delay-load DLLs. Defaults to true
.
How does it work?
C#
There are two main pieces to C# support. First there is an MSBuild task which collects all references passed to the compiler. There is also a Roslyn Analyzer which uses the GetUsedAssemblyReferences
analyzer API which is available starting with Roslyn compiler that shipped with Visual Studio 2019 version 16.10, .NET 5. (see https://github.com/dotnet/roslyn/blob/main/docs/wiki/NuGet-packages.md#versioning). This is the compiler telling us exactly what references were needed as part of compilation. The analyzer then compares the set of references the Task gathered with the references the compiler says were used.
C++ (.vcxproj projects)
ReferenceTrimmer enables the MSVC link.exe
flags noted above, then parses output coming from the Link
MSBuild task. It categorizes the outputs and emits them into the MSBuild console output and the JSON output file noted above. It does not issue MSBuild warnings at this time.
Future development
The outcome of https://github.com/dotnet/sdk/issues/10414 may be of use for ReferenceTrimmer
future updates.
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories (2)
Showing the top 2 popular GitHub repositories that depend on ReferenceTrimmer:
Repository | Stars |
---|---|
dotnet/extensions
This repository contains a suite of libraries that provide facilities commonly needed when creating production-ready applications.
|
|
dfederm/ReferenceTrimmer
Easily identify which dependencies can be removed from a .NET project
|
Version | Downloads | Last updated |
---|---|---|
3.3.10 | 932 | 10/1/2024 |
3.3.6 | 113,461 | 4/1/2024 |
3.3.3 | 3,025 | 3/27/2024 |
3.3.2 | 471 | 3/23/2024 |
3.3.1 | 1,750 | 3/8/2024 |
3.3.0 | 210 | 3/6/2024 |
3.2.4 | 15,154 | 2/2/2024 |
3.2.3 | 703 | 11/1/2023 |
3.2.0 | 855 | 10/2/2023 |
3.1.26 | 461 | 9/19/2023 |
3.1.23 | 269 | 9/15/2023 |
3.1.22 | 416 | 9/9/2023 |
3.1.17 | 1,448 | 6/7/2023 |
3.1.16 | 420 | 3/8/2023 |
3.1.15 | 347 | 2/24/2023 |
3.1.12 | 569 | 2/3/2023 |
3.1.11 | 930 | 1/28/2023 |
3.1.10 | 398 | 1/25/2023 |
3.1.8 | 406 | 1/21/2023 |
3.1.7 | 320 | 1/19/2023 |
3.1.5 | 371 | 1/18/2023 |
3.1.4 | 375 | 1/17/2023 |
3.1.2 | 363 | 1/12/2023 |
3.1.0 | 381 | 1/5/2023 |
3.0.8 | 506 | 10/11/2022 |
3.0.7 | 452 | 10/11/2022 |
3.0.5 | 448 | 9/9/2022 |
3.0.4-g961fd51237 | 223 | 9/9/2022 |
2.0.0 | 3,243 | 10/5/2018 |