NuLink 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?

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

The project is currently in beta. It already works for both .NET Core/NETStandard and .NET Framework packages and projects. Some combinations (OS, consumer style, package style) weren't yet tested. See Limitations & roadmap for details.

Please report bugs and suggestions in the repo Issues. If something goes wrong, see recovery steps in Troubleshooting.

Contributions are welcome :-) Read CONTRIBUTING.md.

• .NET Core and NETStandard projects and packages ("SDK/PackageReference-style")
• New in Beta 2: .NET Framework projects and packages ("packages.config-style")

• Linux, macOS, or Windows
• .NET Core SDK 2.1 (not tested on 3.0 yet)

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

Prior to linking, make sure these conditions are met:

• package must be first restored from a NuGet feed (this limitation will be removed in upcoming versions)
• package source project must be located on the local machine
• either dotnet restore or dotnet build must be run at least once on the package project

In terminal, go to directory of 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

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

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.

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

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

Supporting the full variety of NuGet setups and workflows is hardly feasible. NuLink will initially support the more straightforward workflows, as listed in the table below. Eventually, support for more scenarios can be added.

Back to top

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

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

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

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, do these steps:

• Go to package version folder, usually ~/.nuget/packages/My.Package/1.0.5 on macOS and Linux, or %UserProfile%\.nuget\packages\My.Package\1.0.5 on Windows
  • To verify the exact location of packages root folder, go to one of the consuming projects. In the obj directory, find a file with extension .nuget.g.props. In that file, find <NuGetPackageRoot> element, specifying packages root folder. From that folder, descend into -> My.Package -> 1.0.5.
• List files in directory (ls or dir). Make sure you find:
  • lib directory symlink pointing to bin/Debug of package source folder
  • nulink-backup.lib directory. This is the original lib directory before creation of symlink.
• Remove the lib directory with rm (Linux/macOS) or del (Windows). Note that this only removes the symlink, not the actual bin/Debug folder.
• Rename the nulink-backup.lib directory back to lib.

Back to top

• Felix Berman - initial work

Back to top

This tool was inspired by npm link.

These awesome libraries were used:

• System.CommandLine by .NET Foundation (license and copyright)
• Buildalyzer by Dave Glick (license and copyright)
• Murphy.SymbolicLink by Thomas Chust (license and copyright)

Back to top