NuGetForUnity is a NuGet client built from scratch to run inside the Unity Editor. NuGet is a package management system which makes it easy to create packages that are distributed on a server and consumed by users. NuGet supports sematic versioning for packages as well as dependencies on other packages.
You can learn more about NuGet here: nuget.org
NuGetForUnity provides a visual editor window to see available packages on the server, see installed packages, and see available package updates. A visual interface is also provided to create and edit .nuspec files in order to define and publish your own NuGet packages from within Unity.
Install via Package Manager
- Open Package Manager window (Window | Package Manager)
- Click
+
button on the upper-left of a window, and select "Add package from git URL..." - Enter the following URL and click
Add
button
https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity
NOTE: To install a concreate version you can specify the version by prepending #v{version} e.g.
#v2.0.0
. For more see Unity UPM Documentation.
-
Close Unity Editor
-
Open Packages/manifest.json by any Text editor
-
Insert the following line after
"dependencies": {
, and save the file."com.glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity",
-
Reopen Unity project in Unity Editor
Install via OpenUPM
The package is available on the openupm registry. So you can install it via openupm-cli.openupm add com.github-glitchenzo.nugetforunity
Install via .unitypackage file
Install the provided Unity package into your Unity project. Located here.
Download the *.unitypackage
file. Right-click on it in File Explorer and choose "Open in Unity."
To launch, select NuGet → Manage NuGet Packages
After several seconds (it can take some time to query the server for packages), you should see a window like this:
The Online tab shows the packages available on the NuGet server.
Enable Show All Versions to list all old versions of a package (doesn't work with nuget.org). Disable Show All Versions to only show the latest version of a package.
Enable Show Prelease to list prerelease versions of packages (alpha, beta, release candidate, etc). Disable Show Prerelease to only show stable releases.
Type a search term in the Search box to filter what is displayed.
Press the Refresh button to refresh the window with the latest query settings. (Useful after pushing a new package to the server and wanting to see it without closing and reopening the window.)
The name of the package, the version of the package (in square brakets), and a description are displayed.
Click the View License to open the license in a web browser.
Click the Install to install the package. Note: If the package is already installed an Uninstall button will be displayed which lets you uninstall the package. If the Install button is disabled, it means the package is already imported by Unity.
The Installed tabs shows the packages already installed in the current Unity project.
The Installed packages part of the list shows packages directly installed as project dependencies.
The Implicitly installed packages part shows packages that are installed as transitive dependencies.
Click the Uninstall button to uninstall the package. When uninstalling an explicitely installed package, all of its dependencies that are not a dependency of any other package or the project itself will also be uninstalled.
If Add as explicit is clicked on an implicitly installed package, it will be moved to the first part of the list and will not be automatically uninstalled in a scenario described above.
The Updates tab shows the packages currently installed that have updates available on the server.
The version in brackets on the left is the new version number. The version in brackets in the Update button is the currently installed version.
Click the Update button to uninstall the current package and install the new package.
NuGetForUnity loads the NuGet.config file in the Unity project (automatically created if there isn't already one) in order to determine the server it should pull packages down from and push packages up to. By default, this server is set to the nuget.org package source.
The default NuGet.config file:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="NuGet" value="http://www.nuget.org/api/v2/" />
</packageSources>
<activePackageSource>
<add key="NuGet" value="http://www.nuget.org/api/v2/" />
</activePackageSource>
<config>
<add key="repositoryPath" value="./Packages" />
<add key="DefaultPushSource" value="http://www.nuget.org/api/v2/" />
</config>
</configuration>
You can change this to any other NuGet server (such as NuGet.Server or ProGet - see below). The NuGet → Reload NuGet.config menu item is useful if you are editing the NuGet.config file.
See more information about NuGet.config files here: https://docs.nuget.org/consume/nuget-config-settings
NuGetForUnity installs packages into the local repository path defined in the NuGet.config file (repositoryPath
). By default, this is set to the Assets/Packages
folder. In the NuGet.config file, this can either be a full path, or it can be a relative path based on the project's Assets folder. Note: You'll probably want your Packages folder to be ignored by your version control software to prevent NuGet packages from being versioned in your repository.
When a package is installed, the packages.config file in the project is automatically updated with the specific package information, as well as all of the dependencies that are also installed. This allows for the packages to be restored from scratch at any point. The Restore
operation is automatically run every time the project is opened or the code is recompiled in the project. It can be run manually by selecting the NuGet → Restore Packages menu item.
Note: Depending on the size and number of packages you need to install, the Restore
operation could take a long time, so please be patient. If it appears the Unity isn't launching or responding, wait a few more minutes before attempting to kill the process.
If you are interested in the process NuGetForUnity follows or you are trying to debug an issue, you can force NuGetForUnity to use verbose logging to output an increased amount of data to the Unity console. Add the line <add key="verbose" value="true" />
to the <config>
element in the NuGet.config file. You can disable verbose logging by either setting the value to false or completely deleting the line.
The .nupkg files downloaded from the NuGet server are cached locally in the current user's Application Data folder. (C:\Users\[username]\AppData\Local\NuGet\Cache
). Packages previously installed are installed via the cache folder instead of downloading it from the server again.
To disable the automatic referenceing of assemblies of a NuGet package you can sett the autoReferenced
attribute of a package inside the packages.config
to false
. Currently this setting is not available from UI.
<?xml version="1.0" encoding="utf-8" ?>
<packages>
<package id="Serilog" version="2.12.0" autoReferenced="false" />
</packages>
When this setting is set to false
the assemblies of the NuGet package are only referenced by Unity projects that explicitly list them inside there *.asmdef
file.
First, you'll need to create a .nuspec file that defines your package. In your Project window, right click where you want the .nuspec file to go and select NuGet → Create Nuspec File.
Select the new .nuspec file and you should see something like this:
Input the appropriate information for your package (ID, Version, Author, Description, etc). Be sure to include whatever dependencies are required by your package.
Press the Pack button to pack your package into a .nupkg file that is saved in the C:\Users\[username]\AppData\Local\NuGet\Cache
folder.
Press the Push button to push your package up to the server. Be sure to set the correct API Key that give you permission to push to the server (if you server is configured to use one).
You can use NuGet.Server, NuGet Gallery, ProGet, etc to create your own NuGet server.
Note: NuGetForUnity currently only supports NuGet Api version v2
Alternatively, you can use a "local feed" which is just a folder on your hard-drive or a network share.
Be sure to set the proper URL/path in the NuGet.config file and you should be good to go!
Read more information here: http://docs.nuget.org/create/hosting-your-own-nuget-feeds
For those with projects using automated build solutions like continuous integration, NuGetForUnity provides the ability to restore your NuGet packages directly from the command line without starting Unity. This is achieved using a seperate NuGetForUnity.Cli NuGet package containing a .Net Tool.
- As a global tool using:
dotnet tool install --global NuGetForUnity.Cli
. - If you don't have a tool manifest (local tool instalation context) first creat one with:
dotnet new tool-manifest
. Than install NuGetForUnity.Cli using:dotnet tool install NuGetForUnity.Cli
.
For more information see .Net Tool Documentaion.
Restore nuget packages of a single Unity Project: dotnet nugetforunity restore <PROJECT_PATH>
. If installed as a global tool it can be called without the dotnet
prefix: nugetforunity restore <PROJECT_PATH>
.
In the .Net ecosystem Unity is relatively special as it doesn't use the standard .Net runtime from Microsoft instead, it uses a fork of the Mono runtime. For some platforms Unity even uses IL2CPP that compiles all C# code to C++ code. So Unity also uses a different build-system. This can lead to some issues with NuGet packages that heavily depend on the standard .Net build-system. NuGetForUnity tries to handle most of the changes needed to allow using NuGet packages inside Unity but it is not able to resolve all issues. This section contains some common issues and potential solutions.
If two NuGet packages depend on the same package but reference different versions of it, Unity shows a error like:
Assembly 'Assets/Packages/System.Diagnostics.EventLog.4.7.0/lib/netstandard2.0/System.Diagnostics.EventLog.dll' will not be loaded due to errors:
System.Diagnostics.EventLog references strong named System.Security.Principal.Windows Assembly references: 4.1.1.0 Found in project: 4.1.3.0.
Assembly Version Validation can be disabled in Player Settings "Assembly Version Validation"
As mentioned in the message this error can be suppressed by changing a setting. Just go to Edit -> Project Settings -> Player -> Scroll down and expand "Other Settings" than uncheck "Assembly Version Validation" under the "Configuration" section.
When targeting .Net Framework, the 'Api Compatibility Level' setting under Edit -> Project Settings -> Player -> Other Settings is set to .NET Framework, Unity doesn't include some System libraries by default. See also Unity documentation about system libraries and Unity documetnation about .Net Profiles. Libraries that are not imported by default are e.g. System.Drawing
, System.IO.Compression
, System.IO.Compression.FileSystem
and System.Net.Http
. If you try to use one of this libraries you get a error like:
The type `HttpClient` is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Net.Http, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.
To import one of the System libraries and resolve the error you need to create a csc.rsp
file with the content e.g. to import System.Net.Http
-r:System.Net.Http.dll
and place it inside the containing project that requires the library e.g. the Assets
folder. It can also be placed in a folder that contains a .asmdef
to only add the reference to the sub-project. For example NuGetForUnity also uses a csc.rsp
file see csc.rsp.