MonoGame Pipeline Extensions with .NET 7

.NET 7 has just been released! If you’re like me, you like to get everything updated to the latest as soon as possible. And, if you’ve been working with MonoGame, doing so should be relatively painless.

You actually shouldn’t have to do anything: it should just work! That is unless you’re doing anything special, such as writing an extension to MonoGame’s content pipeline. If your extension is targeting .NET 7, it isn’t going to work.

This article is going to go over how we can set up an environment where all our game-related components are targeting .NET 7 without having any errors thrown in our faces.

This is something that will be eventually addressed by the MonoGame team; however, given that .NET 6 was out for almost a year before an official MonoGame fix was released, I feel like this article will have value for a good amount of time.

The Problem

Developing a game using MonoGame involves referencing several libraries. In previous releases, they were of the typical .NET Standard v2.0 variety; however, they are targeting .NET 6 as of the latest release.

That little bit of minutia is neither here nor there, however, as referencing a .NET 6 library from a .NET 7 library or application is fine and will result in no errors.

A computer game involves more work than just a standard software application: we also need to be aware of all the game-related content that needs to be shipped with and ultimately rendered in the game.

Content Building Involves a Number of Tools

A game powered by MonoGame loads pre-processed game-related data in a platform-neutral manner using its content pipeline. This requires said data to be stored in MonoGame’s XNB format, the encoding of which is achieved by using MonoGame’s content builder tools.

The first tool involved is the MGCB Editor, a graphical interface used to organize the .mgcb file that defines the assets bundled with the game and the manner of their bundling.

The second tool is the MonoGame Content Builder, which builds the content, available as a .NET tool, and is invoked either at build-time by the MonoGame.Content.Builder.Task or manually through either the MGCB Editor or via the command line.

.NET 7 Pipeline Extensions Cause All MGCB Tools to Fail

Although it’s fine that the MonoGame libraries we’re referencing target a (now) older version of .NET, it suddenly becomes a problem if our pipeline extension targets a newer version, since the content pipeline’s libraries and tools need to load our extension.

And, as you might know, although .NET assemblies are backward compatible, they most definitely are not forward compatible.

The MonoGame.Content.Builder.Task and the .NET tool it invokes need to load the pipeline extension so it can use its content importers and processors. The MGCB Editor needs to load the pipeline extension to discover what importers and processors it makes available.

All of these tools will fail to function, a problem that can only be remedied by retargeting these libraries and tools so that they target the latest version of .NET. Luckily for you, I took care of this already so you don’t have to!

Use Bad Echo’s Assemblies in the Interim

Last time I checked, MonoGame’s experimental NuGet package feed did not reflect the latest source on its GitHub. When targeting .NET 6 was an issue, we all had to wait until a stable release came out.

Until such a release fixing our .NET 7 problem arrives, you can use the assemblies I built and published. They were compiled using the latest source (at the time of this article’s publishing) but are powered instead by .NET 7.

Here’s What You Need to Grab

Everything needed can be found on the official nuget.org feed through Visual Studio’s “Manage NuGet Packages…” interface. Note that all these packages are marked as pre-releases (so don’t forget to check that one box!).

First, you’ll need to install the MonoGame.Content.Builder.BadEchoTask NuGet package to your game or whatever other kind of project you have that needs to build content relying on .NET 7 powered pipeline extensions.

You will, of course, want to remove any existing reference to the MonoGame.Content.Builder.Task package. Worlds will collide otherwise!

Next, you must install the MGCB .NET tool packages, shown here:

However, you can’t just search for these NuGet packages and click “Install”. Nope, that would be far too easy my friend.

These are .NET tool packages, and their use requires some things that would otherwise be taken care of by a Visual Studio project template (you’d need to grab some updated MonoGame template projects, and sorry, not interested in packaging modified versions of those up).

Installing the .NET Tools Locally

To switch what you’re using to my .NET 7 friendly version, go to your project’s root directory and look for a .config directory. There should be one in there if you’ve been using MonoGame’s current version!

Inside this folder, there will be a dotnet-tools.json file. This contains the project’s .NET tool configuration, and we’ll want to update that so that the tool packages I published get used.

dotnet-tools.json

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "bad-echo-mgcb": {
      "version": "3.8.2.1-develop",
      "commands": [
        "mgcb"
      ]
    },
    "bad-echo-mgcb-editor": {
      "version": "3.8.2.1-develop",
      "commands": [
        "mgcb-editor"
      ]
    },
    "bad-echo-mgcb-editor-windows": {
      "version": "3.8.2.1-develop",
      "commands": [
        "mgcb-editor-windows"
      ]
    }
  }
}

The configuration shown above should be used in place of any preexisting entries for dotnet-mgcb, dotnet-mgcb-editor, and dotnet-mgcb-editor-windows.

That’s it! Enjoy developing your game in a now-fully-.NET-7.0 environment.