Synopsis

Allows consuming NuGet packages directly from source code on local machine. This creates seamless environment where packages can be developed and tested as if their code was in the main project. Why?

Build status Nuget

See also: Usage instructions, Limitations & roadmap, Troubleshooting, Contributing, Acknowledgements

Getting started

Supported types of projects

Prerequisites

Installing

$ dotnet tool install -g NuLink --version 0.1.0-beta2

Linking a package to local sources

Prior to linking, make sure these conditions are met:

In terminal, go to directory of a project/solution that consumes the package, and run:

$ nulink link -p My.Package -l /path/to/my/package/source/My.Package.csproj

In this example, all consumers of My.Package will start using binaries from /path/to/my/package/source/bin/Debug.

See Usage instructions for more info.

Back to top

How it works

NuLink creates symbolic links to consume binaries of selected packages directly from their compilation directories in the local file system.

For SDK/PackageReference-style projects (.NET Core or NETStandard)

Original                      Linked
--------------------          ----------------------
~ or %UserProfile%            working directory
|                             |
+- .nuget/                    +- My.Package/
   |                             | 
   +- packages/                  +- Source/
      |                             |
      +- my.package/                +- My.Package.csproj     
         |                          |  
         +- 1.0.5/                  +- bin/
            |                          |
            +- lib >---> SYMLINK >---> +- Debug/
               |                          |
               +-X- netstandard2.0/       +-V- netstandard2.0/

In this example, every time My.Package.csproj is compiled, the latest binaries from its bin/Debug are automatically used by all consumers. Since .pdb in bin/Debug maps the binaries to local sources, code navigation and debugging on consumer side work seamlessly with the latest changes in package code.

For packages.config-style projects (.NET Framework)

Original                        Linked
--------------------            ----------------------
consumer working directory    
| 
+- Source\                      package working directory    
   |                            | 
   +- consumer-solution.sln     +- My.Package
   |                               |
   +- packages\                    +- Source\
      |                               |
      +- My.Package.1.0.5\            +- My.Package.csproj     
         |                            |  
         +- lib\                      +- bin\
            |                            |
            +- net45 >---> SYMLINK >---> +- Debug\

This example works mostly like the previous one, except that the link only affects a specific consumer solution. This is because in .NET Framework projects, packages are copied under a solution-level packages folder, whereas in the new SDK-style projects, .NET looks for packages in the user-level cache.

Back to top

Why would you use it

Say you’ve found a piece of code that’s a perfect candidate to become a reusable package. So you create a class library project, configure it to be packed for NuGet, and move the code there.

That’s all great, but now when making changes in the package, how do you try them out in your main project? Publishing a new version to NuGet every time you want to test your new lines of code just doesn’t cut it.

There has to be a seamless environment, which lets you develop packages as if their code was in your main project.

In Node community this problem is long solved with symlinks using npm link command. On top of that tools like lerna support whole development workflows.

Back to top

Usage instructions

Install, update, uninstall

Install:

$ dotnet tool install -g NuLink --version 0.1.0-beta2

After the installation, the tool can be run from terminal with nulink command.

To update to a newer version of the tool, run:

$ dotnet tool update -g NuLink

To uninstall the tool:

$ dotnet tool uninstall -g NuLink

Check status of packages

To check status of packages referenced by project or solution, run from project/solution directory:

$ nulink status

First, make sure you have the sources of the package, and you did dotnet restore and dotnet build on the package project. Then in terminal, go to consumer project or solution directory and run:

$ nulink link -p My.Package -l /path/to/my/package/source/My.Package.csproj

In the above example, all consumers of My.Package will start using binaries from /path/to/my/package/source/bin/Debug.

To revert symbolic link on a package, go to consumer project or solution directory, and run:

$ nulink unlink -p My.Package

Get help

To list existing commands:

$ nulink --help

To get help on a specific command, e.g. link:

$ nulink link --help

To check version of the tool:

$ nulink --version

Back to top

Troubleshooting

Checking current situation

To check the current situation of symbolic links in your NuGet packages, run one of the following commands, depending on your OS:

macOS and Linux:

$ cd ~/.nuget/packages
$ find . -type l -ls

Windows:

> cd %UserProfile%\.nuget\packages
> dir /al /s | findstr "<SYMLINKD>"

Example. To manually remove a link for My.Package version 1.0.5 in a .NET Core or NETStandard project, do these steps:

Back to top