dotnet-add-reference

Add a reference to the project in the current directory

$ dotnet add reference [path/to/reference.csproj]

$ dotnet add reference [path/to/reference1.csproj path/to/reference2.csproj ...]

$ dotnet add [path/to/project.csproj] reference [path/to/reference.csproj]

$ dotnet add [path/to/project.csproj] reference [path/to/reference1.csproj path/to/reference2.csproj ...]

dotnet add [] reference [...] [options]

Where:

`PROJECT` (optional): The path to the project file to add the reference to. If not specified, the command searches the current directory for a project file.
`REFERENCE_PROJECT_PATH` (required): The path(s) to the project file(s) to be referenced. Multiple paths can be specified, separated by spaces.

PROJECT
    Optional. The path to the project file to add the reference to. If omitted, the command searches for a project file in the current working directory. This can be a project file (e.g., MyProject.csproj) or the directory containing it.

REFERENCE_PROJECT_PATH
    Required. The path(s) to the project file(s) that should be added as a reference to the target project. Multiple paths can be provided, separated by spaces.

-f|--framework
    Adds the project reference conditionally, meaning it's only active when the target project is compiled against a specific target framework moniker (TFM), such as net6.0 or net7.0.

-h|--help
    Prints out a short help message for the command.

The dotnet add reference command is a core utility within the .NET command-line interface (CLI) that enables developers to establish project-to-project (P2P) dependencies. When working with multi-project solutions, it's common for one project (e.g., an application) to depend on another (e.g., a shared library). This command facilitates the addition of such a reference by modifying the target project's file (e.g., .csproj, .fsproj, or .vbproj).

Upon execution, dotnet add reference inserts a <ProjectReference> item into the project file, linking it to the specified referenced project. This ensures that during compilation, the dependent project can correctly resolve types and members from the referenced project. It also ensures that the referenced project is built before the dependent project, maintaining the correct build order. This command is particularly useful for managing dependencies within a solution, streamlining the development workflow by abstracting away manual XML editing of project files. It works seamlessly across various operating systems, including Linux, macOS, and Windows, as it's part of the cross-platform .NET SDK.

Existing Projects Only: The paths provided for `REFERENCE_PROJECT_PATH` must point to existing .NET project files (.csproj, .fsproj, .vbproj). The command will fail if the files do not exist.
Circular References: Creating circular references between projects (e.g., Project A references Project B, and Project B references Project A) is not permitted and will result in build errors.
File Modification: The command directly modifies the target project's XML file. It's advisable to commit your changes or be aware of the modifications if using version control.
Build Dependency: Adding a project reference does not automatically build the referenced project. However, during a subsequent dotnet build of the dependent project, the referenced project will be implicitly built if it's outdated or part of the same solution.

It's important to distinguish between project references and package references. dotnet add reference is used for project-to-project dependencies within the same solution or codebase, where you are referencing another local source project. In contrast, dotnet add package is used for referencing external NuGet packages, which are pre-compiled libraries distributed via a package manager. Both serve to resolve dependencies, but their contexts and underlying mechanisms differ significantly.

1. Add a single project reference from the current directory:
dotnet add reference ../MySharedLibrary/MySharedLibrary.csproj

2. Add multiple project references to a specific project file:
dotnet add src/MyWebApp/MyWebApp.csproj reference ../MyDataLayer/MyDataLayer.csproj ../MyBusinessLogic/MyBusinessLogic.csproj

3. Add a project reference conditionally for a specific framework:
dotnet add reference ../MyLibrary/MyLibrary.csproj --framework net7.0

The `dotnet` CLI, including the `dotnet add reference` command, emerged with the introduction of .NET Core (now simply .NET) as a cross-platform and modular framework. Before the `dotnet` CLI, managing project references often involved direct manual editing of MSBuild .csproj files or reliance on IDE-specific functionalities (like Visual Studio). The `dotnet add reference` command was introduced to streamline and standardize the process of adding project-to-project dependencies for command-line driven development, providing a consistent experience across all supported operating systems, including Linux. It replaced the less structured `project.json` approach used in early .NET Core iterations, aligning with the return to MSBuild as the primary build system.

dotnet new(1), dotnet remove reference(1), dotnet add package(1), dotnet sln(1), dotnet build(1)