I'm converting a Habitat solution using DLLs checked into source control over to NuGet packages using the Sitecore package source feed.
When should I use the packages marked NoReferences (so that I end up with the exact same project references)? Or those without this suffix that include references to the same plus other DLLs?
The package without NoReferences suffix brings dependent Nugets containing additional DLLs. These DLLs are defined as dependencies in Nuget definition. If you check the dependencies list you will find Sitecore DLLs and third party DLLs like Newtonsoft.Json or HtmlAgilityPack in it.
The package with NoReferences suffix does not bring any dependencies. Developer expected to identify and add all required DLLs manually.
Now let's talk about what exactly is included in list of dependencies. The answer why some DLLs are included and others are not becomes clear if you check DLL references in the tool like ILSpy.
These are references in Sitecore.ContentSearch.dll:
And these are dependencies of Sitecore.ContentSearch Nuget package:
There is a clear pattern here. The Nuget package includes referenced assemblies as dependencies.
Now we can talk about what an assembly reference is and how it works. When our assembly executes its code it often uses types from external assemblies. References are the guidance for .NET to load the assembly that contains the required type. Interestingly, references are not used when an assembly is loaded, but when the code is executed. When the referenced assembly is missing, the application may work fine if any types from that assembly are not used at runtime.
From mentioned above you can see that the regular Nuget package is developer's safe harbour and the default choice. It includes all the references required at run-time, so you can execute any code without fear to get Could not load file or assembly error.
*NoReferences Nuget package can be used if you want to have full control over what is referenced. You can reduce amount of DLLs in your bin folder or use some specific dependency version.
In 2019 the answer is little bit different.
Sitecore will not release new NoReference Nuget packages. But you can get similar behavior by usage of -IgnoreDependencies setting:
Or by command line:
Install-Package -Id <package name> -IgnoreDependencies -ProjectName <project name>
If you want more details, there is good article that describes this approach for Sitecore.
The no-references packages allow you to add only the packages you need to your project.
Consider a package that preferences Sitecore.Kernel. The package may need Sitecore.Kernel, but not any of the packages that Sitecore.Kernel references (such as Newtonsoft). The no-references package allows you to reference only Sitecore.Kernel.
When using some smaller, more specialized packages, it makes sense to want to use the packages with references (especially for the packages that don't refer to foundational packages like Sitecore.Kernel).
To ensure you have complete control of the references you use in your solution I would argue you should always use the .NoReferences packages.
There is a good overview of the package source feed and some thoughts on when to use the .NoReferences suffix in this blog post https://jermdavis.wordpress.com/2016/09/05/the-official-sitecore-nuget-feed-is-here/
