Managing Legacy Dotnet Packages

Legacy .NET Framework Package Management

Overview

Manage NuGet packages in old-style .NET Framework projects where packages use packages.config (classic NuGet format) or PackageReference in non-SDK-style csproj files.

This skill is different from managing-package-references which handles SDK-style projects with PackageReference and Central Package Management (CPM). Legacy .NET Framework projects have different package management mechanics.

Detecting Package Management Format

Before modifying packages, determine which format the project uses:

Quick Detection Steps

1. Check for packages.config in the project directory.
2. If not found, check csproj for <PackageReference> elements.
3. Check if csproj root is <Project Sdk="..."> (SDK-style) or <Project ToolsVersion="..."> (old-style).

Workflow: packages.config Projects

Understanding packages.config

packages.config is an XML file listing all NuGet packages and their versions:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Newtonsoft.Json" version="13.0.1" targetFramework="net472" />
  <package id="System.Net.Http" version="4.3.4" targetFramework="net472" />
</packages>

The csproj file references the package assemblies via <Reference> with <HintPath>:

<Reference Include="Newtonsoft.Json, Version=13.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed">
  <HintPath>..\packages\Newtonsoft.Json.13.0.1\lib\net45\Newtonsoft.Json.dll</HintPath>
</Reference>

Updating a Package Version

To update a package (e.g., Newtonsoft.Json from 13.0.1 to 13.0.3):

1. Update packages.config: Change the version attribute.

   <package id="Newtonsoft.Json" version="13.0.3" targetFramework="net481" />
   

   Also update targetFramework to net481 if upgrading the project TFM.

2. Update <HintPath> in csproj: The HintPath contains the version number in the path.

   <!-- Before -->
   <HintPath>..\packages\Newtonsoft.Json.13.0.1\lib\net45\Newtonsoft.Json.dll</HintPath>
   <!-- After -->
   <HintPath>..\packages\Newtonsoft.Json.13.0.3\lib\net45\Newtonsoft.Json.dll</HintPath>
   

   ⚠️ Important: The lib\{tfm}\ subfolder in the HintPath depends on which TFM the package ships for. After restore, check the actual folder name. Common patterns:

   • lib\net45\ — works for net45 through net481
   • lib\net472\ — specific to net472+
   • lib\net48\ — specific to net48+
   • lib\netstandard2.0\ — .NET Standard (works on .NET Framework 4.6.1+)

3. Restore packages: Run msbuild {SolutionPath/ProjectPath} /t:Restore. If MSBuild restore is unavailable for a packages.config solution, use nuget restore as a fallback.

4. Verify HintPath: After restore, confirm the DLL exists at the expected path. If the package ships different TFM folders for the new version, update the HintPath accordingly.

5. Build: Run msbuild {SolutionPath/ProjectPath} /t:Build to verify the project compiles.

Adding a New Package

1. Add entry to packages.config:

   <package id="PackageName" version="1.0.0" targetFramework="net481" />
   

2. Add <Reference> to csproj with appropriate <HintPath>:

   <Reference Include="PackageName">
     <HintPath>..\packages\PackageName.1.0.0\lib\net45\PackageName.dll</HintPath>
   </Reference>
   

3. Run msbuild {SolutionPath/ProjectPath} /t:Restore. If MSBuild restore is unavailable for a packages.config solution, use nuget restore as a fallback.

Removing a Package

1. Remove the <package> entry from packages.config.
2. Remove the corresponding <Reference> from the csproj.
3. Remove any using directives for the package's namespaces if no longer needed.

Workflow: PackageReference in Old-Style csproj

Some old-style projects use <PackageReference> instead of packages.config. This is less common but valid.

Updating a Package Version

Edit the Version attribute directly in the csproj:

<!-- Before -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
<!-- After -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Then run msbuild {SolutionPath/ProjectPath} /t:Restore so restore uses MSBuild for old-style projects.

Adding a New Package

Add a <PackageReference> element to an <ItemGroup>:

<ItemGroup>
  <PackageReference Include="PackageName" Version="1.0.0" />
</ItemGroup>

⚠️ Do NOT use dotnet add package — it may attempt to convert the project to SDK-style format or produce incorrect XML for old-style projects.

Removing a Package

Remove the <PackageReference> element from the csproj.

Key Differences from SDK-Style Package Management

Common Issues

HintPath version mismatch after package update

Symptom: Build error — assembly not found. Cause: packages.config version was updated but <HintPath> in csproj still points to old version. Fix: Update the version number in the HintPath to match the new package version.

Package not compatible with target framework

Symptom: NuGet restore warning about package not supporting target framework. Cause: Package doesn't have a compatible TFM folder. Fix: Find a compatible version of the package, or check if a newer version supports net481.

Mixed package management in solution

Symptom: Some projects use packages.config, others use PackageReference. Cause: Projects were created at different times or partially migrated. Fix: Handle each project according to its format. Do NOT convert between formats during a Framework version upgrade.

Build Validation

After package changes, always build with msbuild:

msbuild {SolutionPath} /t:Build /p:Configuration=Debug

Or using the dotnet wrapper:

dotnet msbuild {SolutionPath} /t:Build /p:Configuration=Debug