MonoGame Framework and Content Pipeline Version Mismatch After Failed Upgrade

Question

Goal: achieve a consistent MonoGame version across the game project’s framework assemblies and the Content Pipeline extension so that runtime loading and content builds succeed after a failed upgrade.

Constraints: a partial upgrade can leave disparate NuGet package versions, conditional references in the project file may lock to different package IDs, and the Pipeline VSIX may not match the framework, which together create uncertainty about which version to standardize and how to keep the project file uniform across team members without introducing content incompatibility.

What steps confirm that all MonoGame NuGet packages resolve to a single version after recovery? How should the Content Pipeline VSIX version be aligned with the framework version when only part of the upgrade succeeded? Should the conditional elements be updated manually or rely on NuGet restore to maintain consistency across developers?

Tasadduq Burney · Answer

Answer the question first

When a MonoGame upgrade fails you can end up with a framework DLL at one version, a content‑pipeline VSIX at another, and project references that still point to the old one. Runtime loading will throw "assembly version mismatch" and content builds will fail with a similar error. The goal is to bring every NuGet package and the VSIX back to the same version, verify the alignment, and keep the .csproj uniform across all developers.

Step 1 – Pick a target version

Decide which MonoGame release you want to target (usually the latest stable, e.g., 3.8.0.0). Note the exact version string.
All NuGet references and the VSIX must match this string.

Step 2 – Clean the solution

dotnet clean

Removes stale bin and obj folders so old DLLs don’t linger.

Step 3 – Align NuGet packages

Open the .csproj in a text editor.
Replace every <PackageReference Include="MonoGame.Framework" Version="*" /> with the target version, e.g., Version="3.8.0.0".
Do the same for MonoGame.Framework.DesktopGL, MonoGame.Framework.WindowsDX, and any other MonoGame packages.
Update conditional <ItemGroup> elements (e.g., Condition="'$(OS)' == 'Windows'") to use the same version. Conditional references are evaluated at restore time, so they must match.
Save the file and run dotnet restore to download the specified versions.

Step 4 – Verify a single resolved version

After restore, open obj/project.assets.json and confirm the version field for MonoGame.Framework is the target string everywhere.
Alternatively run dotnet list package --include-transitive and check that no duplicate entries appear.

Step 5 – Match the Content Pipeline VSIX

In Visual Studio, open Tools → Extensions and Updates.
Uninstall any MonoGame VSIX that does not match the target version.
Install the VSIX that matches the framework (e.g., 3.8.0.0). Download it from the MonoGame releases page.
Verify the pipeline executable’s version: mgcb --version should print the same string as the framework.

Step 6 – Check the content project

Open the .mgcb file or the Content project in Visual Studio.
Ensure the PipelineVersion (if present) matches the framework version.
Rebuild the content project. Success indicates the alignment is correct.

Step 7 – Commit the clean configuration

Commit the updated .csproj and any changed .mgcb files.

Optionally add a Directory.Build.props to centralize the MonoGame version for the repository, e.g.:

<Project>
  <ItemGroup>
    <PackageReference Include="MonoGame.Framework" Version="3.8.0.0" />
    <PackageReference Include="MonoGame.Framework.DesktopGL" Version="3.8.0.0" />
  </ItemGroup>
</Project>

Push the changes so all developers pull the same configuration.

Should conditional elements be edited manually?

Yes. Conditional references are evaluated at restore time, so they must contain the same version string. Updating them manually guarantees consistency across machines. After the change, a simple dotnet restore will bring everyone in sync.

Diagnostic question

Do your developers currently rely on a global NuGet cache that could override the project settings? If so, clearing the cache or pinning the version in global.json may be required.