Skip to content

Commit 0624429

Browse files
SimonDarksideJSimonDarksideJ
authored
Add "Preview Packages" usage guide - plus typo fix (#110)
* Add "Preview Packages" usage guide - plus typo fix * Addressed comments and removed toc entry, added links to other guides instead
1 parent d13d82f commit 0624429

8 files changed

+118
-3
lines changed

‎articles/getting_started/1_setting_up_your_os_for_development_macos.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
3434
> [!NOTE]
3535
> You can use `dotnet workload search` to detect any other available workloads you wish to use.
3636
37-
# Apple Silicon Known Issues
37+
## Apple Silicon Known Issues
3838

3939
For the time being, MonoGame requires that you install the x64 version of the .NET runtime if you are running on an Apple Silicon mac in order to be able to build content. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled.
4040

‎articles/getting_started/2_choosing_your_ide_rider.md

+5
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ You can download and install Rider from: [https://www.jetbrains.com/rider/downlo
2626
dotnet new install MonoGame.Templates.CSharp
2727
```
2828

29+
> [!TIP]
30+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
31+
>
32+
> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
33+
2934
## Creating a new MonoGame project
3035

3136
To get you started with Rider, here are the steps for setting up a new Rider MonoGame project.

‎articles/getting_started/2_choosing_your_ide_visual_studio.md

+8-1
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,14 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
3737

3838
> [!WARNING]
3939
> **Visual Studio Extension Issues**
40-
>
40+
>
4141
> The extension that is installed by Visual Studio 2022 is currently outdated.
4242
> Instead of using Visual Studio 2022 to install the templates, run the following command:
43+
>
4344
> ```sh
4445
> dotnet new install MonoGame.Templates.CSharp
4546
> ```
47+
>
4648
> After doing this, you should be able to launch Visual Studio 2022 and create a new project with the newly installed templates.
4749
4850
1. Launch Visual Studio 2022
@@ -66,6 +68,11 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
6668
6769
You now have the MonoGame templates installed and are ready to create new projects.
6870
71+
> [!TIP]
72+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
73+
>
74+
> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
75+
6976
## Creating a new MonoGame project
7077
7178
To get you started with Visual Studio, here are the steps for setting up a new MonoGame project.

‎articles/getting_started/2_choosing_your_ide_vscode.md

+5
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@ By the end, you will be fully equipped to start creating games with MonoGame usi
4949
dotnet new install MonoGame.Templates.CSharp
5050
```
5151

52+
> [!TIP]
53+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
54+
>
55+
> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
56+
5257
## Install Visual Studio Code C# Extensions
5358

5459
To transform Visual Studio Code from a simple text editor into a powerful development environment for C# projects, you must install the Visual Studio Code C# extension. This extension enhances the editor by providing syntax highlighting, code analysis, IntelliSense, and other features that significantly improve the development experience and productivity when working with C#.

‎articles/getting_started/using_development_nuget_packages.md

+5
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ description: How to use the latest development NuGet packages to use the cutting
77

88
When the MonoGame develop branch builds, it publishes development NuGet packages to the MonoGame NuGet Feed on GitHub. If you want to test a new feature or just be on the very latest code you can use this Feed to do that.
99

10+
> [!TIP]
11+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest preview release rather than the raw development code.
12+
>
13+
> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
14+
1015
## Adding a NuGet Source
1116

1217
1. Create a `NuGet.config` in the root or top level directory of your project.

‎articles/getting_to_know/howto/HowTo_Install_Preview_Release.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: How to install a preview release of MonoGame from NuGet
3+
description: This topic describes how to use a preview release of MonoGame in a new or existing project.
4+
---
5+
6+
## Overview
7+
8+
MonoGame provides preview deployments for testing releases prior to the full release of a new version. This gives developers early access to new features before they are made officially available.
9+
10+
> [!WARNING]
11+
> While preview releases still undergo the same rigorous testing used for full releases, some features may not work as expected as it is still classed as developmental code.
12+
>
13+
> *Preview releases should not be used for production deployments.**
14+
>
15+
> The preview packages are intended for testing and validating fixes/updates and new features in your projects without drastically affecting them.
16+
17+
## Updating NuGet package dependencies
18+
19+
To use the preview packages delivered via NuGet you need to update or replace your existing MonoGame references for your project:
20+
21+
- The Platform NuGet package reference - e.g. `MonoGame.Framework.DesktopGL`
22+
- The Builder Task package - `MonoGame.Content.Builder.Task` (Only required if using the Content Pipeline)
23+
24+
The simplest way is from the command line in the folder where your `csproj` is located (if you have multiple projects, please repeat for each) using the following syntax:
25+
26+
```dotnetcli
27+
dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4-preview.1
28+
dotnet add package MonoGame.Content.Builder.Task -v 3.8.4-preview.1
29+
```
30+
31+
**Replacing the preview version with the specific version you wish to install.**
32+
33+
> [!NOTE]
34+
> For Visual Studio, use `Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution/Project`, then click on the `Updates` tab and update each package.
35+
>
36+
> Make sure to select **"Include Prerelease"** for the preview packages to be detected.
37+
38+
## Update `dotnet-tools.json` for Content Manager
39+
40+
To ensure symmetry between the project version and the Content Pipeline Editor (MGCB) the `dotnet-tools.json` configuration in your project `.config` directory will also need updating.
41+
42+
This is simply a matter of updating the tools references, again from the command line in the projects folder, as follows:
43+
44+
```dotnetcli
45+
dotnet tool install dotnet-mgcb --version 3.8.4-preview.1
46+
dotnet tool install dotnet-mgcb-editor --version 3.8.4-preview.1
47+
dotnet tool install dotnet-mgcb-editor-linux --version 3.8.4-preview.1
48+
dotnet tool install dotnet-mgcb-editor-windows --version 3.8.4-preview.1
49+
dotnet tool install dotnet-mgcb-editor-mac --version 3.8.4-preview.1
50+
```
51+
52+
**Replacing the preview version with the specific version you wish to install.**
53+
54+
> [!NOTE]
55+
> Alternatively, simply edit the `dotnet-tools.json` file and replace the **"version"** value across the file.
56+
57+
58+
> [!IMPORTANT]
59+
> Make sure to run `dotnet tool restore` any time you make changes to the `dotnet-tools.json` to refresh the installation of the Content Builder and Editor.
60+
61+
## Installing the preview templates
62+
63+
This step is optional, if you intend to generate a new project using the latest templates, including any automated or templates setup
64+
65+
1. Simply run the following from the command line:
66+
67+
```dotnetcli
68+
dotnet new install MonoGame.Templates.CSharp::3.8.4-preview.1
69+
```
70+
71+
**Replacing the preview version of MonoGame at the end of the command with the specific version you wish to install.**
72+
73+
## Visual Studio Extensions with Preview releases
74+
75+
At this time, the Visual Studio marketplace does not support preview versions of extensions, if you wish to test a preview version of the Visual Studio Extension, you can install it manually.
76+
77+
The Extension can be downloaded from the latest `GitHub Actions` build used to generate the preview build.
78+
79+
1. Go to the [MonoGame GitHub repository](https://github.com/MonoGame/MonoGame/actions) and select the "Actions" tab.
80+
1. Find the build with the associated tag, e.g. [`v3.8.4-preview.1`](https://github.com/MonoGame/MonoGame/actions/runs/14713318149)
81+
1. In the `Artifacts` for the build, you should see the extensions installer `MonoGame.Templates.VSExtension.vsix`
82+
1. Click on the "Download Icon" on the far right-hand side of the row.
83+
1. Once downloaded, run the `vsix` which will update your installation of the extensions package.
84+
85+
## See Also
86+
87+
- [Getting Started with MonoGame](../../getting_started/index.md)
88+
- [Using Development NuGet Packages](../../getting_started/using_development_nuget_packages.md)

‎articles/getting_to_know/howto/index.md

+4
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,7 @@ This section contains articles to help make your MonoGame project successful.
7272
* [How to apply Best Practices for MonoGame Games](HowTo_MobileBestPractices.md)
7373

7474
The practices discussed here will help you have the most success possible with your MonoGame game.
75+
76+
* [How to install MonoGame Preview packages](HowTo_Install_Preview_Release.md)
77+
78+
This topic describes how to use a preview release of MonoGame in a new or existing project.

‎articles/toc.yml

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1+
items:
12
- name: Introduction
2-
href:
3+
href: index.md
34
- name: Roadmap
45
href: /roadmap/
56
- name: What's New

0 commit comments

Comments
 (0)