From c156c282cf62ff13d5f275c5b77ef379d5e3b356 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Sun, 19 Oct 2025 23:01:15 +0100 Subject: [PATCH 1/3] Updated Migration document for 3.8.x upgrade --- articles/migration/migrate_38.md | 128 +++++++++++++++++++++---------- 1 file changed, 87 insertions(+), 41 deletions(-) diff --git a/articles/migration/migrate_38.md b/articles/migration/migrate_38.md index abd78c17..4b937b2e 100644 --- a/articles/migration/migrate_38.md +++ b/articles/migration/migrate_38.md @@ -1,84 +1,119 @@ --- -title: Migrating from 3.8.0 -description: A guide on migrating a MonoGame v3.8.0 project to the current version of MonoGame. +title: Migrating from 3.8.0 or later to 3.8.4.1 +description: A guide on migrating a MonoGame v3.8 project to the current 3.8.4 version of MonoGame. --- -Migrating from 3.8.0 should be straightforward for most platforms. +Migrating from earlier 3.8 releases should be straightforward for most platforms. -The major difference is that 3.8.1 now requires .NET 6 and Visual Studio 2022. You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components. +The major difference is that 3.8.4 onward recommends using .NET 9 in your client project (mandatory for Mobile projects by the DotNet Framework). You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components. -The MGCB Editor is no longer a global .NET tool and we recommend that you use the new Visual Studio 2022 extension which helps with accessing it without the need of CLI commands. +The MGCB Editor is no longer a global .NET tool and the MGCB editor is included as part of the specific project through the use of the dotnet tooling configuration `dotnet-tools.json` file located in the `.config` folder in your solution/project. > [!NOTE] +> If you are using Visual Studio 2022, we recommend that you use the MonoGame extension which helps with accessing the MGCB editor without the need of CLI commands. + +The process of updating your project should be fairly quick and painless without having to change your code or your content project. + +> [!IMPORTANT] > It is also recommended that you uninstall the older global versions of the .NET tools as described below. -## WindowsDX, DesktopGL, and UWP +## Contents -Upgrading from 3.8.0 should be as straightforward as upgrading your ```TargetFramework``` and MonoGame version. +- [Updating DotNet Target Framework](#updating-dotnet-target-framework) +- [Update MonoGame references](#update-monogame-references) +- [Add/Update `dotnet-tools.json` Configuration](#addupdate-dotnet-toolsjson-configuration) +- [Remove `RestoreDotnetTools` section from csproj](#remove-restoredotnettools-section-from-csproj) +- [iOS/iPadOS, and Android Considerations](#iosipados-and-android-considerations) -Edit your csproj file to change your ```TargetFramework```: +## Updating DotNet Target Framework -```xml -net6.0 -``` +Modern MonoGame projects now use the DotNet framework (older project used to rely on the NetCore/NetFramework libraries). As MonoGame has used DotNet project templates since 3.8.x, you only need to replace the `TargetFramework` element of any `csproj` files referencing MonoGame libraries, namely: -Then edit your MonoGame ```PackageReference``` to point to 3.8.1: +- Replace any `` entries to the following: ```xml - - +net9.0 ``` -### Accessing MGCB and MCGB Editor without a global tool +> [!NOTE] +> Using `DotNet 9` is only a **recommendation**, you can use any version of DotNet (from 8.0 and above) so long as it supports the MonoGame Dotnet 8 dependency. This includes the upcoming DotNet 10 LTS. -The MGCB Editor is no longer a .NET global tool, and does not need to be installed or registered. When migrating from 3.8.0, it is recommended that you **uninstall** the global versions of the tools. You can accomplish that with these commands: +Make sure to update any and all projects in your solution, especially you have a multi-project solution similar to those in the [MonoGame.Samples](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Platformer2D) -```sh -dotnet tool uninstall dotnet-mgcb -g -dotnet tool uninstall dotnet-2mgfx -g -dotnet tool uninstall dotnet-mgcb-editor -g -``` +## Update MonoGame references + +Ensure you update the MonoGame references to the latest version, this can be achieved by either: + +- Editing the `csproj` files that reference MonoGame to the latest version + + > [!NOTE] + > The MonoGame templates set the Version number as `Version="3.8.*"`, this means that it will use the LATEST public version of MonoGame (not including preview releases) that is available. However, this does mean your `tools` configuration can become out of sync with your project and potentially cause issue. + +- Use the [Updating NuGet package dependencies](../getting_to_know/howto/HowTo_Install_Preview_Release.md#updating-nuget-package-dependencies) documentation as part of the "Preview Release installation instructions", which states you just need to run the following commands (for `DesktopGL`, use other platforms accordingly): + + ```dotnetcli + dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4.1 + dotnet add package MonoGame.Content.Builder.Task -v 3.8.4.1 + ``` -::: tip -**Do not** run the ``` dotnet tool install ``` on 3.8.1, as it would break 3.8.1. -::: + > [!NOTE] + > The `MonoGame.Content.Builder.Task` is only needed for client projects and not libraries. -You will also need to setup a dotnet-tools configuration file. +This will ensure your project is using the intended version of MonoGame. -- Next to your ```.csproj```create a folder named ```.config``` -- Add a file within the folder named ```dotnet-tools.json``` with the following content: +> [!IMPORTANT] +> Always ensure your `dotnet-tools.json` version matches any updates to the version of MonoGame you are using, see next section. -```json +## Add/Update `dotnet-tools.json` Configuration + +MonoGame DotNet projects currently **Require** DotNet tools configuration to be able to locate and run the `MGCB` editor which is installed locally per project (preventing issues when working with multiple projects using different versions of MonoGame). + +> [!IMPORTANT] +> The MGCB Editor is no longer a .NET global tool, and does not need to be installed or registered. When migrating from 3.8.0, it is recommended that you **uninstall** the global versions of the tools. You can accomplish that with these commands: +> +> ```sh +> dotnet tool uninstall dotnet-mgcb -g +> dotnet tool uninstall dotnet-2mgfx -g +> dotnet tool uninstall dotnet-mgcb-editor -g +> ``` + +You can either copy the configuration from a new project template (e.g. `dotnet new mgdesktopgl -o `), +alternatively you can do the following: + +- Create a new folder in the root of your project named `.config` +- Add a new file called `dotnet-tools.json` and replace its contents with the following: + +```text { "version": 1, "isRoot": true, "tools": { "dotnet-mgcb": { - "version": "3.8.1.303", + "version": "3.8.4.1", "commands": [ "mgcb" ] }, "dotnet-mgcb-editor": { - "version": "3.8.1.303", + "version": "3.8.4.1", "commands": [ "mgcb-editor" ] }, "dotnet-mgcb-editor-linux": { - "version": "3.8.1.303", + "version": "3.8.4.1", "commands": [ "mgcb-editor-linux" ] }, "dotnet-mgcb-editor-windows": { - "version": "3.8.1.303", + "version": "3.8.4.1", "commands": [ "mgcb-editor-windows" ] }, "dotnet-mgcb-editor-mac": { - "version": "3.8.1.303", + "version": "3.8.4.1", "commands": [ "mgcb-editor-mac" ] @@ -87,23 +122,34 @@ You will also need to setup a dotnet-tools configuration file. } ``` -Please note that you cannot use the ```3.8.1.*``` wildcard in the ```dotnet-tools.json``` file (tool versions have to be fully qualified). We strongly recommand that the versions match the MonoGame version referenced in your ```.csproj``` (if you are using the ```*``` wildcard, make sure that they do not end up mismatching if the nugets are updated without you noticing). +> [!NOTE] +> Please note that you cannot use the ```3.8.*``` wildcard in the ```dotnet-tools.json``` file (tool versions have to be fully qualified). We strongly recommand that the versions match the MonoGame version referenced in your ```.csproj``` (if you are using the ```*``` wildcard, make sure that they do not end up mismatching if the nuget's are updated without you noticing). -You will also need to add this to your ```.csproj```: +The file is the same regardless of which platform / target you are intending to use. If you have a solution, you only need a **SINGLE** configuration at the root of the project for all client projects. + +## Remove `RestoreDotnetTools` section from csproj + +From `3.8.4.1` and above, the `RestoreDotnetTools` section is no longer required in client project `csproj` files, as the processing is now handled within the MonoGame deliverables. + +> [!NOTE] +> Earlier versions of MonoGame, e.g. 3.8.0 does not have this configuration in the project template, if your `csproj` does not have a `RestoreDotnetTools` element, you can safely ignore this section. ```xml - + ``` -With these changes, .NET will automatically install the MGCB Editor for you when launching Visual Studio 2022 (if you want to install it manually and skip adding the Target, run ```dotnet tool restore``` within the project directory). +> [!NOTE] +> The XML has changed over versions with various messages and layout, but the section to remove is always titled `Name="RestoreDotnetTools"` -Then, if you installed the Visual Studio extension, you should also be able to just double-click an ```.mgcb``` file to open the MGCB Editor. You can also open the MGCB Editor with the CLI via ```dotnet mgcb-editor``` when executed from within the project directory. +Simply remove this section safely from any and all `csproj` files located in your solution that are dependent on MonoGame. -This new configuration has the advantage of allowing to have per-project versions of MGCB and its Editor (instead of per-machine like a global tool). +## iOS/iPadOS, and Android Considerations -## iOS/iPadOS, and Android +DotNet 9 is MANDATORY for iOS and Android due to platform requirements, as well as the following configurations: -.NET 6 introduced breaking changes in how csproj are defined for iOS/iPadOS and Android. We recommand that you create new projects using the 3.8.1 templates and that you copy over your project files there. +- MonoGame 3.8.4.1 is **REQUIRED** to comply with the Google Policies on 16kb pages and other affordances. +- The Android `targetSdkVersion` in the `AndroidManifest.xml` **MUST** be a minimum "35" to comply with the latest Google policies. +- iOS **MUST** use a minimum `SupportedOSPlatformVersion` of `12.2` in both the `csproj` and in the `info.plist` configuration for the project. From affa0147fed669c2305aa130def1f951a687c4d5 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Sun, 19 Oct 2025 23:04:46 +0100 Subject: [PATCH 2/3] Update TOC and document name --- articles/migration/migrate_38.md | 6 +++--- articles/toc.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/migration/migrate_38.md b/articles/migration/migrate_38.md index 4b937b2e..a2fe4a66 100644 --- a/articles/migration/migrate_38.md +++ b/articles/migration/migrate_38.md @@ -1,9 +1,9 @@ --- -title: Migrating from 3.8.0 or later to 3.8.4.1 -description: A guide on migrating a MonoGame v3.8 project to the current 3.8.4 version of MonoGame. +title: Upgrading MonoGame projects from 3.8.0 or later to 3.8.4.1 +description: A guide on upgrading a MonoGame v3.8 project to the current 3.8.4.1 + versions of MonoGame. --- -Migrating from earlier 3.8 releases should be straightforward for most platforms. +Upgrading existing projects from earlier 3.8 releases should be straightforward for most platforms. The major difference is that 3.8.4 onward recommends using .NET 9 in your client project (mandatory for Mobile projects by the DotNet Framework). You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components. diff --git a/articles/toc.yml b/articles/toc.yml index 7442b238..837d07e2 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -94,7 +94,7 @@ items: href: migration/migrate_xna.md - name: Migrating from 3.7 href: migration/migrate_37.md - - name: Migrating from 3.8.0 + - name: Upgrading 3.8.x to latest href: migration/migrate_38.md - name: Updating Versions href: migration/updating_versions.md From a73bdb35162540642d5455be180e23f4577aff53 Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Mon, 20 Oct 2025 15:06:49 +0100 Subject: [PATCH 3/3] Finalize migration document --- articles/migration/migrate_38.md | 68 +++++++++++++++++--------------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/articles/migration/migrate_38.md b/articles/migration/migrate_38.md index a2fe4a66..d7b56217 100644 --- a/articles/migration/migrate_38.md +++ b/articles/migration/migrate_38.md @@ -1,55 +1,61 @@ --- -title: Upgrading MonoGame projects from 3.8.0 or later to 3.8.4.1 -description: A guide on upgrading a MonoGame v3.8 project to the current 3.8.4.1 + versions of MonoGame. +title: Upgrading MonoGame from 3.8.x to latest +description: A guide on upgrading a MonoGame v3.8 project to the current 3.8.4.1+ releases of MonoGame. --- Upgrading existing projects from earlier 3.8 releases should be straightforward for most platforms. -The major difference is that 3.8.4 onward recommends using .NET 9 in your client project (mandatory for Mobile projects by the DotNet Framework). You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components. +> [!NOTE] +> If you are migrating/upgrading from [XNA](./migrate_xna.md) or [MonoGame 3.7 or earlier](./migrate_37.md) then check the dedicated guides for those actions before returning here. + +- The critical difference from pre 3.8.2 builds, [is that the MGCB Editor is no longer a global .NET tool](#addupdate-dotnet-toolsjson-configuration) and the MGCB editor is now included as part of the specific project through the use of the dotnet tooling configuration `dotnet-tools.json` file located in the `.config` folder in your solution/project. + +- The major difference from 3.8.4 onwards is that we recommend using .NET 9 in your client project, but it is not mandatory, we are also simplifying the `csproj` configuration to reduce management for developers from 3.8.4.1. + + > For iOS/Android however, DotNet 9 at a minimum is Mandatory, [see details here](#iosipados-and-android-considerations). -The MGCB Editor is no longer a global .NET tool and the MGCB editor is included as part of the specific project through the use of the dotnet tooling configuration `dotnet-tools.json` file located in the `.config` folder in your solution/project. +You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components. > [!NOTE] > If you are using Visual Studio 2022, we recommend that you use the MonoGame extension which helps with accessing the MGCB editor without the need of CLI commands. The process of updating your project should be fairly quick and painless without having to change your code or your content project. -> [!IMPORTANT] -> It is also recommended that you uninstall the older global versions of the .NET tools as described below. - ## Contents -- [Updating DotNet Target Framework](#updating-dotnet-target-framework) +- [Updating DotNet Target Framework](#updating-the-dotnet-target-framework) - [Update MonoGame references](#update-monogame-references) - [Add/Update `dotnet-tools.json` Configuration](#addupdate-dotnet-toolsjson-configuration) -- [Remove `RestoreDotnetTools` section from csproj](#remove-restoredotnettools-section-from-csproj) +- [Remove `RestoreDotNetTools` section from csproj](#remove-restoredotnettools-section-from-csproj) - [iOS/iPadOS, and Android Considerations](#iosipados-and-android-considerations) -## Updating DotNet Target Framework +## Updating the DotNet Target Framework -Modern MonoGame projects now use the DotNet framework (older project used to rely on the NetCore/NetFramework libraries). As MonoGame has used DotNet project templates since 3.8.x, you only need to replace the `TargetFramework` element of any `csproj` files referencing MonoGame libraries, namely: +Modern MonoGame projects now use the DotNet framework (older projects used to rely on the NetCore/NetFramework libraries). As MonoGame has used DotNet project templates since 3.8.x, you only need to update the `TargetFramework` element of any `csproj` files referencing MonoGame libraries, namely: -- Replace any `` entries to the following: +- Replace any `` entries with the following: ```xml net9.0 ``` > [!NOTE] -> Using `DotNet 9` is only a **recommendation**, you can use any version of DotNet (from 8.0 and above) so long as it supports the MonoGame Dotnet 8 dependency. This includes the upcoming DotNet 10 LTS. +> Using `DotNet 9` is only a **recommendation**, you can use any version of DotNet (from 8.0 and above) so long as it supports the MonoGame DotNet 8 dependency. This includes the upcoming DotNet 10 LTS. Make sure to update any and all projects in your solution, especially you have a multi-project solution similar to those in the [MonoGame.Samples](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Platformer2D) ## Update MonoGame references -Ensure you update the MonoGame references to the latest version, this can be achieved by either: +Make sure you update the MonoGame references to the latest version, this can be achieved by either: -- Editing the `csproj` files that reference MonoGame to the latest version +- Editing the `csproj` files that reference MonoGame to the latest version. > [!NOTE] - > The MonoGame templates set the Version number as `Version="3.8.*"`, this means that it will use the LATEST public version of MonoGame (not including preview releases) that is available. However, this does mean your `tools` configuration can become out of sync with your project and potentially cause issue. + > The MonoGame templates set the Version number as `Version="3.8.*"`, this means that it will use the LATEST public version of MonoGame (not including preview releases) that is available. + > + > However, this does mean your `tools` configuration can become out of sync with your project and potentially cause issue. -- Use the [Updating NuGet package dependencies](../getting_to_know/howto/HowTo_Install_Preview_Release.md#updating-nuget-package-dependencies) documentation as part of the "Preview Release installation instructions", which states you just need to run the following commands (for `DesktopGL`, use other platforms accordingly): +- Use the [Updating NuGet package dependencies](../getting_to_know/howto/HowTo_Install_Preview_Release.md#updating-nuget-package-dependencies) documentation as part of the "Preview Release installation instructions", which states you should run the following commands (the example is for `DesktopGL`, use other platforms accordingly): ```dotnetcli dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4.1 @@ -62,14 +68,14 @@ Ensure you update the MonoGame references to the latest version, this can be ach This will ensure your project is using the intended version of MonoGame. > [!IMPORTANT] -> Always ensure your `dotnet-tools.json` version matches any updates to the version of MonoGame you are using, see next section. +> Always ensure your `dotnet-tools.json` version matches any updates to the version of MonoGame you are using, as detailed in the next section. ## Add/Update `dotnet-tools.json` Configuration MonoGame DotNet projects currently **Require** DotNet tools configuration to be able to locate and run the `MGCB` editor which is installed locally per project (preventing issues when working with multiple projects using different versions of MonoGame). > [!IMPORTANT] -> The MGCB Editor is no longer a .NET global tool, and does not need to be installed or registered. When migrating from 3.8.0, it is recommended that you **uninstall** the global versions of the tools. You can accomplish that with these commands: +> The MGCB Editor is no longer a .NET global tool, and does not need to be installed or registered separately. When migrating from 3.8.0, it is recommended that you **uninstall** the global versions of the tools. You can accomplish that with these commands: > > ```sh > dotnet tool uninstall dotnet-mgcb -g @@ -77,10 +83,10 @@ MonoGame DotNet projects currently **Require** DotNet tools configuration to be > dotnet tool uninstall dotnet-mgcb-editor -g > ``` -You can either copy the configuration from a new project template (e.g. `dotnet new mgdesktopgl -o `), -alternatively you can do the following: +You can either copy the `config` folder with the configuration from a new project template (e.g. `dotnet new mgdesktopgl -o `), +or alternatively you can do the following: -- Create a new folder in the root of your project named `.config` +- Create a new folder in the root of your project named `.config`. - Add a new file called `dotnet-tools.json` and replace its contents with the following: ```text @@ -123,26 +129,26 @@ alternatively you can do the following: ``` > [!NOTE] -> Please note that you cannot use the ```3.8.*``` wildcard in the ```dotnet-tools.json``` file (tool versions have to be fully qualified). We strongly recommand that the versions match the MonoGame version referenced in your ```.csproj``` (if you are using the ```*``` wildcard, make sure that they do not end up mismatching if the nuget's are updated without you noticing). +> Please note that you cannot use the ```3.8.*``` wildcard in the ```dotnet-tools.json``` file (tool versions have to be fully qualified). We strongly recommend that the versions match the MonoGame version referenced in your ```.csproj``` (if you are using the ```*``` wildcard, make sure that they do not end up mismatching if the NuGet packages are updated without you noticing). -The file is the same regardless of which platform / target you are intending to use. If you have a solution, you only need a **SINGLE** configuration at the root of the project for all client projects. +The file is the same regardless of which platform / target you are intending to use. If you have a multi-project solution, you only need a **SINGLE** configuration at the root of the project for all client projects. -## Remove `RestoreDotnetTools` section from csproj +## Remove `RestoreDotNetTools` section from csproj -From `3.8.4.1` and above, the `RestoreDotnetTools` section is no longer required in client project `csproj` files, as the processing is now handled within the MonoGame deliverables. +From `3.8.4.1` and above, the `RestoreDotNetTools` section is no longer required in client project `csproj` files, as the processing is now handled within the MonoGame deliverables. > [!NOTE] -> Earlier versions of MonoGame, e.g. 3.8.0 does not have this configuration in the project template, if your `csproj` does not have a `RestoreDotnetTools` element, you can safely ignore this section. +> Earlier versions of MonoGame, e.g. 3.8.0 do not have this configuration in the project template, if your `csproj` does not have a `RestoreDotNetTools` element, you can safely ignore this section. ```xml - + ``` -> [!NOTE] -> The XML has changed over versions with various messages and layout, but the section to remove is always titled `Name="RestoreDotnetTools"` +> [!TIP] +> The XML has changed over versions with various messages and layout, but the section to remove is always titled `Name="RestoreDotNetTools"` Simply remove this section safely from any and all `csproj` files located in your solution that are dependent on MonoGame. @@ -151,5 +157,5 @@ Simply remove this section safely from any and all `csproj` files located in you DotNet 9 is MANDATORY for iOS and Android due to platform requirements, as well as the following configurations: - MonoGame 3.8.4.1 is **REQUIRED** to comply with the Google Policies on 16kb pages and other affordances. -- The Android `targetSdkVersion` in the `AndroidManifest.xml` **MUST** be a minimum "35" to comply with the latest Google policies. +- The Android `targetSdkVersion` in the `AndroidManifest.xml` **MUST** be a minimum "35" to comply with the latest Google policies. The templates set the minimum to `21` which is safe, only the `TARGET` SDK is critical. - iOS **MUST** use a minimum `SupportedOSPlatformVersion` of `12.2` in both the `csproj` and in the `info.plist` configuration for the project.