NuGet PackageReference for C++ Projects in Visual Studio

Native C++ projects in Visual Studio now support <PackageReference>, the modern, MSBuild-native way to declare NuGet package dependencies directly in your project file. This support is available experimentally for .vcxproj projects in the Visual Studio Insiders Channel starting with version 18.7.

This feature has been the most upvoted feature request on Visual Studio Developer Community, and we’re delivering it based on that feedback and in collaboration with other teams at Microsoft, including Windows and Azure.

NuGet with PackageReferences can be useful for teams that develop both .NET and C++ projects (native or interop) that need a consistent way to deploy their binaries across their repos or to their consumers, or for managing dependencies that aren’t C++ libraries, such as binary SDK packages. We continue to recommend vcpkg for acquiring and managing C++ libraries, as it is more specialized and flexible for these types of dependencies.

What Is PackageReference?

Traditionally, NuGet packages in C++ projects were managed through packages.config, a separate XML file that listed every dependency (including transitive ones) and required a per-solution packages folder. PackageReference eliminates that by declaring dependencies directly in the project file:

<ItemGroup>
  <PackageReference Include="Microsoft.Windows.CppWinRT" Version="2.0.240405.15" />
</ItemGroup>

The key advantages over packages.config:

• Single source of truth. Dependencies live in the project file alongside your other project references. No separate files required.
• Transitive dependency resolution. You only list packages you directly depend on. NuGet resolves the rest automatically at restore time.
• Global package cache. Packages are stored once on disk in a global folder, not duplicated per-solution. This means faster restores and less disk usage.
• MSBuild integration. You can use conditions to vary package references by configuration, platform, or target framework, using the same MSBuild syntax you already know.

For a full overview, see the PackageReference documentation on Microsoft Learn. If you’re migrating an existing project, see Migrate from packages.config to PackageReference.

How It Works

Once enabled, this experience is identical to .NET projects, both in the Visual Studio IDE and on the command line. There is no difference in the core UX. You can add PackageReferences by:

1. Editing the project file directly. Add <PackageReference> items to an <ItemGroup> in your .vcxproj.
2. Using the NuGet Package Manager UI. Right-click your project in Solution Explorer, select Manage NuGet Packages, and install packages as usual.
3. Using the Package Manager Console. Run Install-Package commands.

NuGet restore handles downloading, caching, and making package assets available to your build. The underlying implementation uses core CPS (Common Project System) capabilities, the same infrastructure that powers this feature for .NET projects.

How to Enable It

This feature is experimental and off by default in version 18.7. To opt in, set the EnableNativePackageReferenceSupport MSBuild property to true.

You can do this in your project file’s Globals property group:

<PropertyGroup Label="Globals">
  <EnableNativePackageReferenceSupport>true</EnableNativePackageReferenceSupport>
</PropertyGroup>

Or, to enable it across all projects in a repository, add it to a Directory.Build.props file:

<Project>
  <PropertyGroup>
    <EnableNativePackageReferenceSupport>true</EnableNativePackageReferenceSupport>
  </PropertyGroup>
</Project>

Performance

We designed this feature to be fully compatible with the project load performance improvements shipped since Visual Studio 2017. One of the things holding us back from shipping PackageReference in the past was that a simpler implementation would invalidate this work, causing ongoing performance regressions for customers. Happily, this problem is now solved. The first time you add PackageReferences to a project, there is a one-time cache warm-up cost. After that initial load, the cache is warm and subsequent project operations are fully optimized with no ongoing performance impact.

Current Limitations

This initial release supports native C++ projects (.vcxproj). The following scenarios are not yet supported:

• C++/CLI projects targeting legacy .NET Framework versions. (PackageReference for C++/CLI projects targeting modern .NET is already supported; see our earlier announcement.)
• C++ projects that reference C++/CLI projects or C# projects. We are investigating a solution to this. In the meantime, you can use one of these workarounds:
  • Set <ReferenceOutputAssembly>false</ReferenceOutputAssembly> and <SkipGetTargetFrameworkProperties>true</SkipGetTargetFrameworkProperties> on the <ProjectReference> item, which will allow NuGet to ignore it and not cause restore and build issues.
  • Set AssetTargetFallback to include frameworks compatible with the referenced C# project. For example:

    <PropertyGroup>
    <AssetTargetFallback>net472;net10.0</AssetTargetFallback>
    </PropertyGroup>

What About vcpkg?

This feature does not change our recommendation for vcpkg. We continue to recommend vcpkg as the primary tool for acquiring and managing C and C++ libraries. vcpkg provides source-based builds with binary caching support, ABI compatibility management, support for offline installation, and a curated registry of thousands of open-source libraries optimized for C++ workflows.

PackageReference support complements vcpkg by enabling NuGet-based distribution workflows. For example, teams that publish internal SDK packages via NuGet feeds, or projects that consume Windows-specific packages distributed through NuGet.org. The two tools serve different use cases and work well together. You can also use vcpkg to build library dependencies, then export them as NuGet with the vcpkg export --nuget command.

Try It Out

1. Download Visual Studio Insiders.
2. Enable the feature by setting EnableNativePackageReferenceSupport to true in your project or Directory.Build.props.
3. Add a PackageReference to your .vcxproj and build.

We want your feedback. This is an experimental release, and your input will directly shape how we evolve this feature before enabling it by default. Let us know:

• Does the end-to-end experience work well for your projects?
• Are there gaps or rough edges you encounter?
• How does performance feel in your solutions?

You can share feedback through Developer Community, the blog comments below, or Help → Send Feedback in Visual Studio.