dotnet references

A dotnet global tool that aids with bulk solution and project file references changes and related directory organisation.

(Formerly dotnet-fix-references, see prior documentation for it here.)

Installation

dotnet tool install --global dotnet-references

Note: If using this in a scripted process you want to be consistent (like a build), you should pin to a specific version with --version x.y.z.

Usage

Usage: dotnet-references <Mode> [options]

Arguments:
  Mode                                       The mode to run (fix or internalise)

Options:
  -ep|--entry-point                          The entry point to use (a .sln file or a directory)
  -wd|--working-directory                    The working directory to use (under which all .sln and .csproj files are contained). 
                                             If not provided, defaults to directory of entry point.
  -rupf|--remove-unreferenced-project-files  Should unreferenced project files be removed?
                                             (Caution! Deletes files! Only supported in fix mode).
  -reig|--remove-empty-item-groups           Should ItemGroup elements in project files that are empty be removed?
                                             (Only supported in internalise mode).
  -?|-h|--help                               Show help information

Supports the following modes which have varying use cases.

Mode 1: Fix

This mode can fix references between solution files and projects in one of two ways.

⚠️ If the dotnet cli complains with "Specify which project file to use because this '...' contains more than one project file.", you've run into a limitation of the dotnet cli. A workaround is to execute from any random directory and utilise the -ep and -wd args. (eg. mkdir temp && cd temp && dotnet references fix -ep ../ -wd .. -rupf (or -ep ../Company.Project.sln -wd ..)).

Directory-first

By passing a directory as the entry, the tool will assume that the current directory structure is the source of truth and will fix all project references inside all .sln and .csproj files to the correct relative path.

dotnet references fix -ep ./src

Use cases: You have moved your source code into a new folder structure (via a script or otherwise) and don't want to manually updates all your project references in .sln and .csproj files. (Project file names must be the same).

File-first

By passing a .sln file, the tool will assume that it, and the path it references .csproj files, is the source of truth; thus moving the .csproj files into the correct directory structure.

dotnet references fix -ep Company.Project.sln

Use cases:

1. Overcoming Dockerfile COPY globbing limitations... See here.

Mode 2: Internalise (PackageReference --> ProjectReference)

This mode "internalises" references, by turning package references to project references. (The project name must be the same as the package name).

dotnet references internalise -wd ./src

Use cases:

1. You've consolidated separate projects (and packages) into a mono repo and want to swap all package references to local project references where possible.

Note: It currently doesn't handle transitive dependencies (dependencies of dependencies), which you'll need to add manually.

Word of warning

This tool updates/deletes files in-place. Backup anything you care about before running this tool.

Feature backlog

1. Support fix mode w/ .csproj entry