Resolving MGCB Editor Not Found Error

, , , ,
1

I was asked to make a separate post regarding this issue and the resolutions, so here it is.

The problem

The Monogame MGCB Editor does not open when you double-click the Content.mgcb file in Visual Studio, or you try to execute the command dotnet mgcb-editor ./Content/Content.mgcb and you get the following error message

Could not execute because the specified command or file was not found.
Possible reasons for this include:

    You misspelled a built-in dotnet command.
    You intended to execute a .NET program, but dotnet-mgcb-editor does not exist.
    You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH

Steps To Resolve

The following steps will generally resolve this issue for you. This information is also provided in the official documentation in the MonoGame GitHub Repo, but it hasn’t been updated on the actual website yet.

  1. If you just created a brand new Monogame 3.8.1 game project, you may need to do a NuGet restore. This is usually done automatically when using Visual Studio, but not in other IDE environments (e.g. Visual Studio Code). Just open a command line/terminal in the project directory (the directory with your game .csproj file) and run the command dotnet restore. This should restore the MonoGame NuGets as well as the tools.

otherwise if you are updating your project from a version prior to MonoGame 3.8, or if the above did not work, perform the following:

  1. If you are updating from a version of MonoGame prior to 3.7 when you actually had to download and install the framework and tooling, ensure you have uninstalled them.

  2. Ensure you do not have the mgcb-editor installed as a global dotnet tool. Prior to MonoGame 3.8.1, the editor was a global tool, however this is no longer the case and should not be used as a global tool. To ensure you do not have it, or its dependencies as a global tool you can run the following commands from a terminal/command line

dotnet tool uninstall -g dotnet-mgcb
dotnet tool uninstall -g dotnet-mgcb-editor
dotnet tool uninstall -g dotnet-mgcb-editor-windows
dotnet tool uninstall -g dotnet-mgcb-editor-mac
dotnet tool uninstall -g dotnet-mgcb-editor-linux
  1. Ensure in your game project directory (this is the directory with the .csproj file) that you have a .config directory with a file called dotnet-tools.json. If you do not have this directory and/or file, perform the following:
    3.1 Open a command line/terminal from your project directory and enter the command dotnet new tool-manifest. This will create the directory and manifest dotnet-tools.json file for you
    3.2 Open the dotnet-tools.json file and replace the contents with the following: Note: at the time of this writing, the current versions are 3.8.1.303 as shown in the contents below. This version should match the version number of MonoGame that you are using, so edit accordingly.
{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-mgcb": {
      "version": "3.8.1.303",
      "commands": [
        "mgcb"
      ]
    },
    "dotnet-mgcb-editor": {
      "version": "3.8.1.303",
      "commands": [
        "mgcb-editor"
      ]
    },
    "dotnet-mgcb-editor-linux": {
      "version": "3.8.1.303",
      "commands": [
        "mgcb-editor-linux"
      ]
    },
    "dotnet-mgcb-editor-windows": {
      "version": "3.8.1.303",
      "commands": [
        "mgcb-editor-windows"
      ]
    },
    "dotnet-mgcb-editor-mac": {
      "version": "3.8.1.303",
      "commands": [
        "mgcb-editor-mac"
      ]
    }
  }
}
  1. Open your .csproj file and ensure the following is in it
<Target Name="RestoreDotnetTools" BeforeTargets="Restore">
    <Message Text="Restoring dotnet tools" Importance="High" />
    <Exec Command="dotnet tool restore" />
</Target>

Assuming you have followed the steps above, that you do not have it installed as a global tool, that you have the .config/dotnet-tools.json file in your project directory and that the contents of the file are as shown above, execute the dotnet restore command from your project directory. This should download the tool.

After this, you should be good to go. Below I will explain a little more in detail about all of this so if you’re interested, keep reading, otherwise, the solution is above.

MGCB Editor History

So why does this solution work, who is it for, and why is it needed?

Prior to MonoGame 3.7, using MonoGame was an actual install you did on your desktop. This install included the Content Pipeline Tool (now known as the MGCB Editor). This tool was an actual installed program on your computer.

When MonoGame 3.7 released, a lot of things were changed with how the templates worked, namely that they are no longer something you have to install. Instead, everything was moved to NuGet packages, and the Content Pipeline Tool was renamed the MGCB Editor and was moved to being a dotnet tool. If you are not familiar with how “dotnet tools” work, you can read more about them at .NET tools - .NET CLI | Microsoft Learn. The short of it is that dotnet tools are console applications that are installed via NuGet packages. During the MonoGame 3.7 era, the tool was in fact recommended as being installed as a global tool.

Then MonoGame 3.8 was release and it changed again. Starting with MonoGame 3.8, the tool should no longer be installed as a global tool. Instead the 3.8.x templates now include the .config/dotnet-tools.json manifest file when a new project is created that contains the configuration to give you all of the tooling necessary and installs them as a local tool.

Now, this doesn’t mean that new tools files are downloaded and stored on your computer for every single project you make. NuGet stores packages/tools downloaded to a common directory (%USERPROFILE%\.nuget\packages on Windows and ~/.nuget/packages on Mac/Linux). So the tools are only ever downloaded once and the NuGet package is cached and reused in additional projects.

:bulb: Global vs Local Tool
So if NuGet caches on download, what’s the difference between a Global and Local Tool?

Global tools can be executed from a command line/terminal no matter what directory the command line/terminal is in.

Local tools can only be executed from a command line/terminal when the command line/terminal is in the project directory

Users that are starting with MonoGame 3.8 should not run into this issue since the templates will have the configurations setup for you. If you are using Visual Studio, the NuGet’s should restore automatically when you create the project. If you are using VSCode or a similar setup, you may need to run dotnet tool restore manually on the project to ensure that it downloads the tools after the project is created.

But What If I Want It As A Global Tool?

There is really no reason to have it as a global tool. As mentioned above, dotnet tools are cached in the NuGet packages directory, so you are not downloading the tools for every project taking up additional disk space.

The other advantage to having it as a local tool is the dotnet-tools.json manifest file included in the templates includes the packages for Windows, Mac, and Linux. So if you move your development between environments, you don’t have to worry about ensuring the correct global tools are installed for each one.

Also, even if you install all necessary components as a global tool, it will throw errors and fail because it expects it to be setup as a local tool.

3 Likes
2

I can use the command dotnet mgcb-editor ./Content/Content.mgcb to open MGCB,but I can’t double-click the Content.mgcb file in Visual Studio, why? :smiling_face_with_tear:

3

emmm,solved,so weird

4

I’m at a loss as to why I can’t get these tools to work.
On a new and an older project both using v3.8.1.303.

I run dotnet tool restore it lists the various mgcb tools installed, says restore successful, and I can see them in my .nuget/packages cache directory.
But if I try and build my project, or if I try and run the tool from CLI directly, it cannot find the tools.

dotnet mgcb
dotnet mgcb-editor
dotnet mgcb-editor .\Content\Content.mgcb

All of these result in an error similar to Run "dotnet tool restore" to make the "mgcb-editor" command available.

I can find the mgcb-editor-windows.exe in the .nuget/packages directory, and run it fine.

Attempting to build a project, even a new empty one gets the following.

MSBuild version 17.9.8+b34f75857 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  Tool 'dotnet-mgcb' (version '3.8.1.303') was restored. Available commands: mgcb
  Tool 'dotnet-mgcb-editor' (version '3.8.1.303') was restored. Available commands: mgcb-editor
  Tool 'dotnet-mgcb-editor-linux' (version '3.8.1.303') was restored. Available commands: mgcb-editor-linux
  Tool 'dotnet-mgcb-editor-windows' (version '3.8.1.303') was restored. Available commands: mgcb-editor-windows
  Tool 'dotnet-mgcb-editor-mac' (version '3.8.1.303') was restored. Available commands: mgcb-editor-mac

  Restore was successful.
  Run "dotnet tool restore" to make the "mgcb" command available.
C:\Users\<username>\.nuget\packages\monogame.content.builder.task\3.8.1.303\build\MonoGame.Content.Builder.Task.targets(142,5): error MSB3073: The command "dotnet mgcb /quiet /@:"H:\SimpleGame\Content\Content.mgcb" /platform:Des
ktopGL /outputDir:"H:/SimpleGame/Content/bin/DesktopGL/Content" /intermediateDir:"H:/SimpleGame/Content/obj/DesktopGL/net6.0/Content" /workingDir:"H:/SimpleGame/Content/"" exited with code 1. [H:\SimpleGame\SimpleGame.csproj]

Briefly, I can run dotnet tool install dotnetsay and this sample tool works after install.
Why don’t any of the MGCB tools work?

I have 2x Windows 11 Machines both running into the same problem.