Edit

Share via

Build apps against Microsoft.NETFramework.ReferenceAssemblies

  • Article

When you target a particular version of .NET Framework, by default your application is built by using the reference assemblies that are included with that version's developer pack. In scenarios where the matching developer pack can't be installed on the computer, you can build against reference assemblies distributed via a NuGet package instead.

Update project files

Each project that should build against the reference assemblies NuGet package needs to include a reference to Microsoft.NETFramework.ReferenceAssemblies.

Projects that use a packages.config file should include the following in packages.config.

<packages>
  <package id="Microsoft.NETFramework.ReferenceAssemblies" version="1.0.3" developmentDependency="true" />
</packages>

Projects that use the <PackageReference> MSBuild property should include the following property in the project file.

<ItemGroup>
  <PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" PrivateAssets="All" />
</ItemGroup>

SDK-style projects include this reference by default. For typical .NET Framework projects that were created with Visual Studio, you can add the reference by using the NuGet Package Manager UI in Visual Studio. The package contains reference assemblies for many versions of .NET Framework. The version that's actually used is determined by the TargetFrameworkVersion or TargetFramework property, as already defined in the project file.

Restore the project

Projects that contain a package reference must be restored before they can be built.

After adding the Microsoft.NETFramework.ReferenceAssemblies NuGet package to your project, you must explicitly run the restore action in one of the following ways:

  • If your project is a non SDK-style project and uses the packages.config file to reference NuGet packages:

    1. Install the NuGet CLI tool, and make sure nuget.exe is in the PATH environment variable.
    2. Open a command prompt.
    3. Navigate to the directory that contains your project file.
    4. Run nuget.exe restore.

  • If your project is a non SDK-style project and uses <PackageReference> settings in the project file to reference NuGet packages:

    1. Open Developer Command Prompt for VS 2022. The name of this app might be different based on which version of Visual Studio you've installed.
    2. Navigate to the directory that contains your project file.
    3. Run msbuild /t:restore.

  • If your project is an SDK-style project, you don't need to do anything. The NuGet restore action runs automatically when the project is built.

Important

Using reference assemblies makes it possible to build projects that target unsupported versions of .NET Framework from the command line. However, you still can't load these projects in newer versions of Visual Studio. To continue building these apps in Visual Studio, the only workaround is to use an older version of Visual Studio.