Adding References Using NuGet Versus an Extension SDK


The new home for Visual Studio documentation is Visual Studio 2017 Documentation on

The latest version of this topic can be found at Adding References Using NuGet Versus an Extension SDK.

You can provide a package for consumption within Visual Studio projects by using either the NuGet extension to Visual Studio or a software development kit (SDK). By describing the similarities and differences between the two mechanisms, this topic can help you choose the best one for your task.

  • NuGet is an open-source, package-management system that simplifies the process of incorporating libraries into a project solution. For more information, see NuGet Overview.

  • An SDK is a collection of files that Visual Studio treats as a single reference item. The Reference Manager dialog box lists all SDKs that are relevant to the project that’s open when you display that dialog box. When you add an SDK to a project, you can access all of the contents of that SDK through IntelliSense, the Toolbox, designers, the Object Browser, MSBuild, deployment, debugging, and packaging. For more information about SDKs, see Creating a Software Development Kit.

The following table helps you compare the referencing features of an SDK with the referencing features of NuGet.

FeatureSDK SupportSDK NotesNuGet SupportNuGet Notes
The mechanism references one entity and then all the files and functionality are available.YYou add an SDK by using the Reference Manager dialog box, and all the files and functionality are available during the development workflow.Y
MSBuild automatically consumes assemblies and Windows metadata (.winmd) files.YReferences in the SDK are automatically passed to the compiler.Y
MSBuild automatically consumes the .h or .lib files.YThe SDKName.props file tells Visual Studio how to set up the Visual C++ directory, and so forth, for automatic .h or .lib file consumption.N
MSBuild automatically consumes the .js or .css files.YIn Solution Explorer, you can expand the JavaScript SDK reference node to show individual .js or .css files and then generate <source include/> tags by dragging those files to their source files. The SDK supports F5 and automatic package setup.Y
MSBuild automatically adds the control in the Toolbox.YThe Toolbox can consume SDKs and show controls in the tabs that you specify.N
The mechanism supports Visual Studio Installer for extensions (VSIX).YVSIX has a special manifest and logic to create SDK packagesYThe VSIX can be embedded in another setup program.
The Object Browser enumerates references.YThe Object Browser automatically gets the list of references in SDKs and enumerates them.N
Files and links automatically get added to the Reference Manager dialog box (help links, and so forth auto populate)YThe Reference Manager dialog box automatically enumerates SDKs, along with help links and the list of SDK dependencies.NNuGet provides its own Manage NuGet Packages dialog box.
The mechanism supports multiple architectures.YSDKs can ship multiple configurations. MSBuild consumes the appropriate files for each project configuration.N
The mechanism supports multiple configurations.YSDKs can ship multiple configurations. Depending on project architecture, MSBuild consumes the appropriate files for each project architecture.N
The mechanism can specify “not to copy.”YDepending on whether files are dropped in the \redist or \designtime folder, you can control which files to copy into the consuming application's package.NYou declare which files to copy in the package manifest.
Content appears in localized files.YLocalized XML documents in SDKs are automatically included for a better design-time experience.N
MSBuild supports consuming multiple versions of an SDK simultaneously.YThe SDK supports consuming multiple versions simultaneously.NThis isn't referencing. You can’t have more than one version of NuGet files in your project at a time.
The mechanism supports specifying applicable target frameworks, Visual Studio versions, and project types.YThe Reference Manager dialog box and the Toolbox show only the SDKs that apply to a project, so that users can more easily choose the appropriate SDKs.Y (partial)Pivot is the Target Framework. There is no filtering on user interface. At installation time, it might return an error.
The mechanism supports specifying registration info for native WinMDs.YYou can specify the correlation between the .winmd file and the .dll file in SDKManifest.xml.N
The mechanism supports specifying dependencies on other SDKs.YThe SDK only notifies the user; the user must still install them and reference them manually.YNuGet pulls them automatically; the user isn't notified.
The mechanism integrates with Windows Store concepts such as app manifest and Framework ID.YThe SDK must pass concepts that are specific to the Store so that packaging and F5 work correctly with SDKs that are available in theStore.N
The mechanism integrates with the app debugging pipeline for Windows 8.x Store apps.YThe SDK must pass Store-specific concepts so that packaging and F5 work correctly with SDKs available in the Store.YNuGet content becomes part of the project. No special F5 consideration is needed.
The mechanism integrates with app manifests.YThe SDK must pass Store-specific concepts so that packaging and F5 work correctly with SDKs available in the Store.YNuGet content becomes part of the project. No special F5 consideration is needed.
The mechanism deploys non-reference files (for example, deploy test framework upon which to run tests of Windows 8.x Store apps).YIf you drop the files in the \redist folder, the files are automatically deployed.Y
The mechanism automatically adds the platform SDKs in Visual Studio IDE.YIf you drop the Windows 8 SDK or the Windows Phone SDK in a specific location with a specific layout, the SDK is automatically integrated with all the Visual Studio features.N
The mechanism supports a clean developer machine. (That is, no installation is required, and simple retrieval from source code control will work.)NBecause you reference an SDK, you must check in your solution and the SDK separately. You can check in the SDK from the two non-registry default locations from which MSBuild iterates SDKs (for details, see Creating a Software Development Kit). As an alternative, if a custom location consists of the SDKs, you can specify the following code in the project file:

 <PropertyGroup> <SDKReferenceDirectoryRoot>C:\MySDKs</SDKReferenceDirectoryRoot> </PropertyGroup>

Then check the SDKs into that location.
YYou can check out the solution, and Visual Studio immediately recognizes and acts on the files.
You can join a large existing community of package authors.N/AThe community is new.Y
You can join a large existing community of package consumers.N/AThe community is new.Y
You can join an ecosystem of partners (custom galleries, repositories, and so forth).N/AThe available repositories include Visual Studio Gallery, Microsoft Download Center, and Windows Store.Y
The mechanism integrates with continuous-integration build servers for both package creation and consumption.YThe SDK must pass the checked-in location (SDKReferenceDirectoryRoot property) on command line to MSBuild.Y
The mechanism supports both stable and pre-release package versions.YThe SDK supports adding references to multiple versions.Y
The mechanism supports auto-update for installed packages.YIf shipped as VSIX or part of Visual Studio automatic updates, SDK provides automatic notifications.Y
The mechanism contains a stand-alone .exe file for creating and consuming packages.YThe SDK contains MSBuild.exe.Y
Packages can be checked into version control.YYou can’t check in anything outside the Documents node, which means that the Extension SDKs might not be checked in.The size of Extension SDK might be large.Y
You can use a PowerShell interface to create and consume packages.Y (consumption), N (creation)No tooling for creating an SDK. Consumption is executing MSBuild on the command line.Y
You can use a Symbol package for debugging support.YIf you drop .pdb files in the SDK, the files get picked up automatically.Y
The mechanism supports package manager auto-updates.N/AThe SDK gets revised with MSBuild.Y
The mechanism supports a lightweight manifest format.YSDKManifest.xml supports many attributes, but a small subset is usually necessary.Y
The mechanism is available for all Visual Studio editions.YThe SDK supports all Visual Studio editions, from Visual Studio Express through Visual Studio Ultimate.YNuGet supports all Visual Studio editions, Express up through Visual Studio Ultimate.
The mechanism is available for all project types.NThe SDK supports Windows 8.x Store apps starting in Visual Studio 2012.NYou can review a list of allowed projects.

Managing references in a project