From a2c63173f4e154c36010f4d69a35ae5d01faa7a6 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 09:53:24 +0100 Subject: [PATCH 01/10] Create using_development_nuget_packages.md Add some documentation on how to use the GitHub NuGet Feed. --- .../using_development_nuget_packages.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 articles/getting_started/using_development_nuget_packages.md diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md new file mode 100644 index 00000000..3c4d6e59 --- /dev/null +++ b/articles/getting_started/using_development_nuget_packages.md @@ -0,0 +1,85 @@ +# Using the Development Nuget Packages + +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. + +## Adding a NuGet Source + +Create a `NuGet.config` in the root or top level directory of your project. +NuGet will automattically walk up the directory tree to find `NuGet.config` files. +Then add the following content. + +```xml + + + + + + +``` + +Next again in the root or top level directory create a `Directory.Build.props` file and add the following content. + +```xml + + + 1.0.0.1233-develop + + +``` + +`Directory.Build.props` is a MSBuild file which will be imported by all projects in your game. +Its like a file to contain global variables. In this case the version of MonoGame we want to use. + +Next update all the `PackageReference` entires in your csprojs which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. +For example + +```xml + + + + +``` + +If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not open. You need +to be a valid GitHub user to use them. + +## Authentication + +You need to create an Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. +See the following documentation on how to create your PAT. +(https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens] +Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic] for details. + +Once you have your PAT you can create a new `NuGet.config` file in the directory ABOVE your game project directory. +To be clean this file should NOT be in your source tree. It should be outside of any directory which is under source control. + +``` + Projects + NuGet.confing <-- THIS IS WHERE YOU PUT THE FILE. + MyGame + NuGet.config + MyGame.DesktopGL + MyGame.DesktopGL.csproj + +``` +Do Not... DO NOT place this NuGet.config file in your source control. + +The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHub username and the `%GITHUB_TOKEN%` with your token. + +``` + + + + + + + + + +``` + +The really good thing about placing these credentials outside of source control is they are safe, but also any +new projects you create under that folder can also make use of these createntials. So its a good idea to keep them in one place. +you From a51e85bfeb35853fa0497375dbcde34679f0732f Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 09:54:27 +0100 Subject: [PATCH 02/10] Update using_development_nuget_packages.md --- articles/getting_started/using_development_nuget_packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 3c4d6e59..9df160b7 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -49,8 +49,8 @@ to be a valid GitHub user to use them. You need to create an Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. See the following documentation on how to create your PAT. -(https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens] -Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic] for details. +(managing-your-personal-access-tokens)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens] +Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See (creating-a-personal-access-token-classic)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic] for details. Once you have your PAT you can create a new `NuGet.config` file in the directory ABOVE your game project directory. To be clean this file should NOT be in your source tree. It should be outside of any directory which is under source control. From 55f179db145238672db15a1820dc2bb6fc0c9732 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 09:55:04 +0100 Subject: [PATCH 03/10] Update using_development_nuget_packages.md --- articles/getting_started/using_development_nuget_packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 9df160b7..a503329d 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -49,8 +49,8 @@ to be a valid GitHub user to use them. You need to create an Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. See the following documentation on how to create your PAT. -(managing-your-personal-access-tokens)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens] -Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See (creating-a-personal-access-token-classic)[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic] for details. +[managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details. Once you have your PAT you can create a new `NuGet.config` file in the directory ABOVE your game project directory. To be clean this file should NOT be in your source tree. It should be outside of any directory which is under source control. From 4d9fb6e4e58f86e2c0a05daac36b25fd34da8a24 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 10:29:59 +0100 Subject: [PATCH 04/10] Update using_development_nuget_packages.md --- .../using_development_nuget_packages.md | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index a503329d..53badffd 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -28,10 +28,48 @@ Next again in the root or top level directory create a `Directory.Build.props` f ``` - `Directory.Build.props` is a MSBuild file which will be imported by all projects in your game. Its like a file to contain global variables. In this case the version of MonoGame we want to use. +To get the latest version from the GitHub feed we have to do a manual search with the following + +```CLI +nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub +``` + +This will give you the following output + +``` +==================== +Source: MonoGameGitHub +-------------------- +> MonoGame.Framework.Android | 1.0.0.1278-develop | Downloads: 164 + The MonoGame runtime for Android. +-------------------- +> MonoGame.Framework.Content.Pipeline | 1.0.0.1278-develop | Downloads: 69 + The Monogame Content Pipeline for Windows, Mac and Linux is used to compile raw content to xnb files... +-------------------- +> MonoGame.Framework.DesktopGL | 1.0.0.1278-develop | Downloads: 337 + The MonoGame runtime supporting Windows, Linux and macOS using SDL2 and OpenGL. +-------------------- +> MonoGame.Framework.Native | 1.0.0.1278-develop | Downloads: 1 + The MonoGame Native platform. +-------------------- +> MonoGame.Framework.WindowsDX | 1.0.0.1278-develop | Downloads: 76 + The MonoGame runtime for Windows using DirectX API's. +-------------------- +> MonoGame.Framework.WindowsUniversal | 3.8.1.1128-develop | Downloads: 54 + The MonoGame runtime for UWP (Universal Windows Platform) which supports Windows 10 and Xbox One. +-------------------- +> MonoGame.Framework.iOS | 1.0.0.1278-develop | Downloads: 153 + The MonoGame runtime for iOS amd iPadOS. +-------------------- +``` + +The version number you want to use is listed in the output. +Note: As builds are done the version number will always be changing. Unfortunately due to limitations in the way NuGet works we cannot +use a wildcard with a prerelease package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest verion you want to use. + Next update all the `PackageReference` entires in your csprojs which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. For example From 54e8577118a631289382410d2de05beebe707235 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 14:06:46 +0100 Subject: [PATCH 05/10] Update using_development_nuget_packages.md --- articles/getting_started/using_development_nuget_packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 53badffd..2e401aca 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -31,7 +31,7 @@ Next again in the root or top level directory create a `Directory.Build.props` f `Directory.Build.props` is a MSBuild file which will be imported by all projects in your game. Its like a file to contain global variables. In this case the version of MonoGame we want to use. -To get the latest version from the GitHub feed we have to do a manual search with the following +To get the latest version you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). To get the information from the GitHub feed by doing a command line search with the following ```CLI nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub From 208690db4a548bf3deb86fd047c58961d1b86047 Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 15:04:57 +0100 Subject: [PATCH 06/10] Update using_development_nuget_packages.md --- .../getting_started/using_development_nuget_packages.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 2e401aca..23df4158 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -97,6 +97,8 @@ To be clean this file should NOT be in your source tree. It should be outside of Projects NuGet.confing <-- THIS IS WHERE YOU PUT THE FILE. MyGame + .git + Directory.Build.props NuGet.config MyGame.DesktopGL MyGame.DesktopGL.csproj @@ -119,5 +121,5 @@ The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHu ``` The really good thing about placing these credentials outside of source control is they are safe, but also any -new projects you create under that folder can also make use of these createntials. So its a good idea to keep them in one place. -you +new projects you create under that folder can also make use of these createntials. So its a good idea to keep them in one place. +For more information to you read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files). From e89553762984bae3e550d761e97ae655f5c37c5d Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 15:12:05 +0100 Subject: [PATCH 07/10] Update using_development_nuget_packages.md --- articles/getting_started/using_development_nuget_packages.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 23df4158..e94ed02e 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -104,7 +104,9 @@ To be clean this file should NOT be in your source tree. It should be outside of MyGame.DesktopGL.csproj ``` -Do Not... DO NOT place this NuGet.config file in your source control. + +> [!IMPORTANT] +> Do Not... DO NOT place a NuGet.config file with valid `packageSourceCredentials` in your source control. The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHub username and the `%GITHUB_TOKEN%` with your token. From 8ebe2130a89e6cc0529ff16d9196bbae9fee39bb Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 16:29:35 +0100 Subject: [PATCH 08/10] Update using_development_nuget_packages.md --- .../using_development_nuget_packages.md | 40 ++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index e94ed02e..d989f4d1 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -1,6 +1,6 @@ # Using the Development Nuget Packages -When the MonoGame develop branch builds it publishes development NuGet packages to the +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. @@ -19,7 +19,7 @@ Then add the following content. ``` -Next again in the root or top level directory create a `Directory.Build.props` file and add the following content. +Next, again in the root or top level directory, create a `Directory.Build.props` file and add the following content. ```xml @@ -28,10 +28,10 @@ Next again in the root or top level directory create a `Directory.Build.props` f ``` -`Directory.Build.props` is a MSBuild file which will be imported by all projects in your game. -Its like a file to contain global variables. In this case the version of MonoGame we want to use. +`Directory.Build.props` is an MSBuild file which will be imported by all projects in your game. +It is like a file that contains global variables. In this case the version of MonoGame we want to use. -To get the latest version you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). To get the information from the GitHub feed by doing a command line search with the following +To find out the latest version number, you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). Or to get the information from the GitHub feed, you can run the following command. ```CLI nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub @@ -67,31 +67,35 @@ Source: MonoGameGitHub ``` The version number you want to use is listed in the output. -Note: As builds are done the version number will always be changing. Unfortunately due to limitations in the way NuGet works we cannot -use a wildcard with a prerelease package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest verion you want to use. -Next update all the `PackageReference` entires in your csprojs which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. -For example +> [!IMPORTANT] +> As packages are published, the version number will always change. Unfortunately, due to limitations in the way NuGet works, we cannot +> use a wildcard with a pre-release package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest verion you want to use. + +Next update all the `PackageReference` entries in your csproj's which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. +For example: ```xml - + ``` -If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not open. You need +If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not public. You need to be a valid GitHub user to use them. ## Authentication -You need to create an Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. +You need to create a Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. See the following documentation on how to create your PAT. [managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) -Note: You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details. -Once you have your PAT you can create a new `NuGet.config` file in the directory ABOVE your game project directory. -To be clean this file should NOT be in your source tree. It should be outside of any directory which is under source control. +> [!IMPORTANT] +> You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details. + +Once you have your PAT, you can create a new `NuGet.config` file in the directory ABOVE your game project directory. +To be clear, this file should NOT be in your source tree. It should be outside of any directory which is under source control. ``` Projects @@ -122,6 +126,6 @@ The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHu ``` -The really good thing about placing these credentials outside of source control is they are safe, but also any -new projects you create under that folder can also make use of these createntials. So its a good idea to keep them in one place. -For more information to you read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files). +The really good thing about placing these credentials outside of source control is that they are safe. But also any +new projects you create under that folder can also make use of these createntials. So it is a good idea to keep them in one place. +For more information, you can read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files). From 84d558f37e7d5324561a4d0c9d99e7a0c7ff4d2f Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Sat, 14 Sep 2024 16:31:02 +0100 Subject: [PATCH 09/10] Update using_development_nuget_packages.md --- articles/getting_started/using_development_nuget_packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index d989f4d1..46b01fb7 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -68,7 +68,7 @@ Source: MonoGameGitHub The version number you want to use is listed in the output. -> [!IMPORTANT] +> [!NOTE] > As packages are published, the version number will always change. Unfortunately, due to limitations in the way NuGet works, we cannot > use a wildcard with a pre-release package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest verion you want to use. @@ -91,7 +91,7 @@ You need to create a Personal Access Token (PAT) on your GitHub account in order See the following documentation on how to create your PAT. [managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) -> [!IMPORTANT] +> [!NOTE] > You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details. Once you have your PAT, you can create a new `NuGet.config` file in the directory ABOVE your game project directory. From 46eb6ffd8c88818590aa31f29e134c3edb4555ec Mon Sep 17 00:00:00 2001 From: "Simon (Darkside) Jackson" Date: Thu, 26 Sep 2024 20:14:16 +0100 Subject: [PATCH 10/10] Updated for docfx formatting --- .../using_development_nuget_packages.md | 181 +++++++++--------- 1 file changed, 94 insertions(+), 87 deletions(-) diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 46b01fb7..91635aa3 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -1,78 +1,85 @@ -# Using the Development Nuget Packages - -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. - -## Adding a NuGet Source - -Create a `NuGet.config` in the root or top level directory of your project. -NuGet will automattically walk up the directory tree to find `NuGet.config` files. -Then add the following content. - -```xml - - - - - - -``` - -Next, again in the root or top level directory, create a `Directory.Build.props` file and add the following content. - -```xml - - - 1.0.0.1233-develop - - -``` -`Directory.Build.props` is an MSBuild file which will be imported by all projects in your game. -It is like a file that contains global variables. In this case the version of MonoGame we want to use. - -To find out the latest version number, you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). Or to get the information from the GitHub feed, you can run the following command. - -```CLI -nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub -``` - -This will give you the following output - -``` -==================== -Source: MonoGameGitHub --------------------- -> MonoGame.Framework.Android | 1.0.0.1278-develop | Downloads: 164 - The MonoGame runtime for Android. --------------------- -> MonoGame.Framework.Content.Pipeline | 1.0.0.1278-develop | Downloads: 69 - The Monogame Content Pipeline for Windows, Mac and Linux is used to compile raw content to xnb files... --------------------- -> MonoGame.Framework.DesktopGL | 1.0.0.1278-develop | Downloads: 337 - The MonoGame runtime supporting Windows, Linux and macOS using SDL2 and OpenGL. --------------------- -> MonoGame.Framework.Native | 1.0.0.1278-develop | Downloads: 1 - The MonoGame Native platform. --------------------- -> MonoGame.Framework.WindowsDX | 1.0.0.1278-develop | Downloads: 76 - The MonoGame runtime for Windows using DirectX API's. --------------------- -> MonoGame.Framework.WindowsUniversal | 3.8.1.1128-develop | Downloads: 54 - The MonoGame runtime for UWP (Universal Windows Platform) which supports Windows 10 and Xbox One. --------------------- -> MonoGame.Framework.iOS | 1.0.0.1278-develop | Downloads: 153 - The MonoGame runtime for iOS amd iPadOS. --------------------- -``` - -The version number you want to use is listed in the output. - -> [!NOTE] -> As packages are published, the version number will always change. Unfortunately, due to limitations in the way NuGet works, we cannot -> use a wildcard with a pre-release package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest verion you want to use. - -Next update all the `PackageReference` entries in your csproj's which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. +--- +title: Using the Development Nuget Packages +description: How to use the latest development NuGet packages to use the cutting edge of MonoGame development in your project. +--- + +## Overview + +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. + +## Adding a NuGet Source + +1. Create a `NuGet.config` in the root or top level directory of your project. + + > [!NOTE] + > NuGet will automatically walk up the directory tree to find `NuGet.config` files. + +1. Add the following content: + + ```xml + + + + + + + ``` + +1. Next (in the root or top level directory), create a `Directory.Build.props` file and add the following content. + + ```xml + + + 1.0.0.1233-develop + + + ``` + + `Directory.Build.props` is an MSBuild file which will be imported by all projects in your game. It is like a file that contains global variables. In this case the version of MonoGame we want to use. + + > [!NOTE] + > To find out the latest version number, you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). Or to get the information from the GitHub feed, you can run the following command. + > + > ```CLI + > nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub + > ``` + + This will give you the following output + + ```text + ==================== + Source: MonoGameGitHub + -------------------- + > MonoGame.Framework.Android | 1.0.0.1278-develop | Downloads: 164 + The MonoGame runtime for Android. + -------------------- + > MonoGame.Framework.Content.Pipeline | 1.0.0.1278-develop | Downloads: 69 + The Monogame Content Pipeline for Windows, Mac and Linux is used to compile raw content to xnb files... + -------------------- + > MonoGame.Framework.DesktopGL | 1.0.0.1278-develop | Downloads: 337 + The MonoGame runtime supporting Windows, Linux and macOS using SDL2 and OpenGL. + -------------------- + > MonoGame.Framework.Native | 1.0.0.1278-develop | Downloads: 1 + The MonoGame Native platform. + -------------------- + > MonoGame.Framework.WindowsDX | 1.0.0.1278-develop | Downloads: 76 + The MonoGame runtime for Windows using DirectX API's. + -------------------- + > MonoGame.Framework.WindowsUniversal | 3.8.1.1128-develop | Downloads: 54 + The MonoGame runtime for UWP (Universal Windows Platform) which supports Windows 10 and Xbox One. + -------------------- + > MonoGame.Framework.iOS | 1.0.0.1278-develop | Downloads: 153 + The MonoGame runtime for iOS amd iPadOS. + -------------------- + ``` + + The version number you want to use is listed in the output. + + > [!NOTE] + > As packages are published, the version number will always change. Unfortunately, due to limitations in the way NuGet works, we cannot + > use a wildcard with a pre-release package (so you cannot do `1.0.0.*-develop`). So this is the best way to find the latest version you want to use. + +1. Next update all the `PackageReference` entries in your `csproj`'s which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property. For example: ```xml @@ -82,24 +89,23 @@ For example: ``` -If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not public. You need -to be a valid GitHub user to use them. +If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not public. You need to be a valid GitHub user to use them. ## Authentication -You need to create a Personal Access Token (PAT) on your GitHub account in order to use the NuGet feed. -See the following documentation on how to create your PAT. +You need to create a **Personal Access Token** (PAT) on your GitHub account in order to use the NuGet feed. See the following documentation on how to create your PAT. + [managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) > [!NOTE] > You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details. -Once you have your PAT, you can create a new `NuGet.config` file in the directory ABOVE your game project directory. +Once you have your **PAT**, you can create a new `NuGet.config` file in the directory ABOVE your game project directory. To be clear, this file should NOT be in your source tree. It should be outside of any directory which is under source control. -``` +```cli Projects - NuGet.confing <-- THIS IS WHERE YOU PUT THE FILE. + NuGet.config <-- THIS IS WHERE YOU PUT THE FILE. MyGame .git Directory.Build.props @@ -110,11 +116,11 @@ To be clear, this file should NOT be in your source tree. It should be outside o ``` > [!IMPORTANT] -> Do Not... DO NOT place a NuGet.config file with valid `packageSourceCredentials` in your source control. +> Do Not... **DO NOT** place a `NuGet.config` file with valid `packageSourceCredentials` in your source control. The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHub username and the `%GITHUB_TOKEN%` with your token. -``` +```xml @@ -126,6 +132,7 @@ The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHu ``` -The really good thing about placing these credentials outside of source control is that they are safe. But also any -new projects you create under that folder can also make use of these createntials. So it is a good idea to keep them in one place. -For more information, you can read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files). +The really good thing about placing these credentials outside of source control is that they are safe. But also any new projects you create under that folder can also make use of these credentials. So it is a good idea to keep them in one place. + +> [!NOTE] +> For more information, you can read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files).