Introduction

Legacy .NET Framework 4.0 projects often build locally and then fail on CI for reasons that have nothing to do with the code. The usual problem is that the build agent is missing the exact Windows tooling, reference assemblies, or package-restore behavior that the project expects.

The First Thing to Check

A .NET Framework 4.0 project is not built with the modern dotnet SDK workflow. It typically needs Windows, MSBuild, the correct targeting pack, and any referenced native or COM components.

A good baseline build command on a Windows agent looks like this:

nuget restore MySolution.sln
msbuild MySolution.sln /p:Configuration=Release /m /verbosity:minimal

If nuget restore is skipped, CI often fails with missing packages even though local Visual Studio builds succeed because local package caches hide the problem.

Missing Targeting Pack and Reference Assemblies

A classic error on CI is that reference assemblies for .NETFramework,Version=v4.0 are not installed. The project file targets the framework, but the agent only has newer SDKs or runtimes.

Symptoms include messages about missing reference assemblies or unresolved framework libraries.

The fix is to install the .NET Framework 4.0 developer pack or compatible Visual Studio build tools on the agent. Merely having the runtime is not enough for compilation.

NuGet and Package Path Problems

Older solutions often expect a packages folder checked into or restored beside the solution. CI failures happen when:

• 'packages.config dependencies were never restored'
• the agent restores into a different path than the project expects
• private package feeds are unavailable on the build server

If the solution still uses packages.config, keep the restore step explicit. Also verify NuGet.Config is present on the agent if the build depends on private feeds.

Platform and Toolchain Mismatches

Some older projects only build correctly under a specific platform target such as x86. Others depend on tools that are present in Visual Studio but missing on a minimal CI image.

If the project references native libraries, try building with the same platform configuration used locally:

msbuild MySolution.sln /p:Configuration=Release /p:Platform=x86

Also compare these items between local and CI:

• Visual Studio or Build Tools version
• installed Windows SDKs
• platform target
• environment variables
• custom build events and hard-coded paths

Hard-Coded Paths and Build Events

Legacy .NET Framework solutions often contain pre-build or post-build scripts that assume local drive letters, developer usernames, or installed tools.

Example of a fragile build event:

copy C:\ThirdParty\Tool\config.xml $(OutDir)

This works on one developer machine and fails everywhere else. Replace hard-coded paths with repository-relative files, build variables, or checked-in tooling.

Making CI More Predictable

A useful stabilization checklist is:

1. restore packages explicitly
2. build with msbuild, not dotnet build
3. install the correct targeting pack on the agent
4. remove machine-specific paths from scripts
5. log environment details during the build

For noisy failures, increase MSBuild verbosity temporarily:

msbuild MySolution.sln /v:detailed > build.log

That usually exposes which import, target, or assembly resolution step broke.

Common Pitfalls

The most common mistake is treating .NET Framework 4.0 like a modern .NET project and trying to fix CI with global.json or dotnet restore. That is usually the wrong toolchain.

Another frequent issue is assuming the runtime is enough. Compilation needs targeting packs and build tools.

A third pitfall is relying on locally cached packages or Visual Studio components that were never declared in the CI environment.

Summary

• '.NET Framework 4.0 CI builds usually require Windows, MSBuild, and the correct targeting pack.'
• Use nuget restore and msbuild explicitly for older solutions.
• Check reference assemblies, package paths, and private feed access.
• Match platform settings such as x86 when native dependencies are involved.
• Remove hard-coded local paths from build events and scripts.