Skip to content

Commit 99710f5

Browse files
dellis1972dellis1972
authored
Create using_development_nuget_packages.md (#62)
Add some documentation on how to use the GitHub NuGet Feed.
1 parent 0a7b299 commit 99710f5

File tree

1 file changed

+138
-0
lines changed

1 file changed

+138
-0
lines changed

‎articles/getting_started/using_development_nuget_packages.md

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Using the Development Nuget Packages
3+
description: How to use the latest development NuGet packages to use the cutting edge of MonoGame development in your project.
4+
---
5+
6+
## Overview
7+
8+
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.
9+
10+
## Adding a NuGet Source
11+
12+
1. Create a `NuGet.config` in the root or top level directory of your project.
13+
14+
> [!NOTE]
15+
> NuGet will automatically walk up the directory tree to find `NuGet.config` files.
16+
17+
1. Add the following content:
18+
19+
```xml
20+
<?xml version="1.0" encoding="utf-8"?>
21+
<configuration>
22+
<packageSources>
23+
<add key="MonoGameGitHub" value="https://nuget.pkg.github.com/MonoGame/index.json" />
24+
</packageSources>
25+
</configuration>
26+
```
27+
28+
1. Next (in the root or top level directory), create a `Directory.Build.props` file and add the following content.
29+
30+
```xml
31+
<Project>
32+
<PropertyGroup>
33+
<MonoGamePackageVersion>1.0.0.1233-develop</MonoGamePackageVersion>
34+
</PropertyGroup>
35+
</Project>
36+
```
37+
38+
`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.
39+
40+
> [!NOTE]
41+
> 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.
42+
>
43+
> ```CLI
44+
> nuget search "MonoGame.Framework" -PreRelease -Source MonoGameGitHub
45+
> ```
46+
47+
This will give you the following output
48+
49+
```text
50+
====================
51+
Source: MonoGameGitHub
52+
--------------------
53+
> MonoGame.Framework.Android | 1.0.0.1278-develop | Downloads: 164
54+
The MonoGame runtime for Android.
55+
--------------------
56+
> MonoGame.Framework.Content.Pipeline | 1.0.0.1278-develop | Downloads: 69
57+
The Monogame Content Pipeline for Windows, Mac and Linux is used to compile raw content to xnb files...
58+
--------------------
59+
> MonoGame.Framework.DesktopGL | 1.0.0.1278-develop | Downloads: 337
60+
The MonoGame runtime supporting Windows, Linux and macOS using SDL2 and OpenGL.
61+
--------------------
62+
> MonoGame.Framework.Native | 1.0.0.1278-develop | Downloads: 1
63+
The MonoGame Native platform.
64+
--------------------
65+
> MonoGame.Framework.WindowsDX | 1.0.0.1278-develop | Downloads: 76
66+
The MonoGame runtime for Windows using DirectX API's.
67+
--------------------
68+
> MonoGame.Framework.WindowsUniversal | 3.8.1.1128-develop | Downloads: 54
69+
The MonoGame runtime for UWP (Universal Windows Platform) which supports Windows 10 and Xbox One.
70+
--------------------
71+
> MonoGame.Framework.iOS | 1.0.0.1278-develop | Downloads: 153
72+
The MonoGame runtime for iOS amd iPadOS.
73+
--------------------
74+
```
75+
76+
The version number you want to use is listed in the output.
77+
78+
> [!NOTE]
79+
> As packages are published, the version number will always change. Unfortunately, due to limitations in the way NuGet works, we cannot
80+
> 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.
81+
82+
1. Next update all the `PackageReference` entries in your `csproj`'s which use MonoGame to use `$(MonoGamePackageVersion)` MSBuild property.
83+
For example:
84+
85+
```xml
86+
<ItemGroup>
87+
<PackageReference Include="MonoGame.Framework.DesktopGL" Version="$(MonoGamePackageVersion)" />
88+
<PackageReference Include="MonoGame.Content.Builder.Task" Version="$(MonoGamePackageVersion)" />
89+
</ItemGroup>
90+
```
91+
92+
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.
93+
94+
## Authentication
95+
96+
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.
97+
98+
[managing-your-personal-access-tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
99+
100+
> [!NOTE]
101+
> 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.
102+
103+
Once you have your **PAT**, you can create a new `NuGet.config` file in the directory ABOVE your game project directory.
104+
To be clear, this file should NOT be in your source tree. It should be outside of any directory which is under source control.
105+
106+
```cli
107+
Projects
108+
NuGet.config <-- THIS IS WHERE YOU PUT THE FILE.
109+
MyGame
110+
.git
111+
Directory.Build.props
112+
NuGet.config
113+
MyGame.DesktopGL
114+
MyGame.DesktopGL.csproj
115+
116+
```
117+
118+
> [!IMPORTANT]
119+
> Do Not... **DO NOT** place a `NuGet.config` file with valid `packageSourceCredentials` in your source control.
120+
121+
The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHub username and the `%GITHUB_TOKEN%` with your token.
122+
123+
```xml
124+
<?xml version="1.0" encoding="utf-8"?>
125+
<configuration>
126+
<packageSourceCredentials>
127+
<MonoGameGitHub>
128+
<add key="Username" value="%GITHUB_USER%" />
129+
<add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
130+
</MonoGameGitHub>
131+
</packageSourceCredentials>
132+
</configuration>
133+
```
134+
135+
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.
136+
137+
> [!NOTE]
138+
> 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).

0 commit comments

Comments
 (0)