MSBuildForUnity

MSBuildForUnity solves the problem of establishing clear dependency relationships between Unity project and other .NET components such as external (to Unity) C# projects, or NuGet packages. It creates a familiar to .NET developers project structure and ensures that the dependencies are resolved and brought into the Unity project as appropriate. With this component, you can:

• Share code between Unity and other .NET projects (such as UWP XAML apps, Xamarin apps, etc.).
• Consuming existing .NET components (e.g. NuGet packages).

The samples included in this repository best convey the simplicity and value of this component:

• Simple NuGet Dependency Sample - Showcases the simplest and most minimal usage of this component to pull in a dependency.
• Integrated Dependencies Sample - Showcases the power of this component by relying on project generation.
• Cross Unity Dependencies Sample - Showcases how to establish a dependency between two Unity projects (almost like AsmDef-to-AsmDef).

Builds and Packages

Build	Build Status	Package Feed
UPM		Azure DevOps
NuGet

Quick Start

The following are basic instructions for taking advantage of MSBuildForUnity for some common scenarios.

Bring NuGet packages and MSBuild projects into a Unity project

This scenario leverages the MSBuildForUnity Project Builder and the MSBuildForUnity NuGet Package.

1. Add the com.microsoft.msbuildforunity UPM (Unity Package Manager) package.

   • Edit the Packages/manifest.json file in your Unity project.

   • Add the following near the top of the file:

     "scopedRegistries": [
         {
             "name": "Microsoft",
             "url": "https://pkgs.dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_packaging/UnityDeveloperTools/npm/registry/",
             "scopes": [
                 "com.microsoft"
             ]
         }
     ],

   • Add the following to the dependencies section of the file:

       "com.microsoft.msbuildforunity": "<version>"

     NOTE: Replace <version> with the latest package version from the MSBuildForUnity UPM feed.

2. MSBuildForUnity will create a top-level project in your Assets folder named after your Unity project name: {UnityProjectName}.Dependencies.msb4u.csproj, edit this project file to add additional references to any NuGet packages or C# projects you want to use in your Unity project.

   <Project ToolsVersion="15.0">
   <!--GENERATED FILE-->
   <!--
       This file can be modified and checked in.
       
       It is different from the other generated C# Projects in that it will be the one gathering all dependencies and placing them into the Unity asset folder.
       
       You can add project level dependencies to this file, by placing them below:
       - <Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.props" />
       and before:
       - <Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.targets" />
       
       Do not add any source or compilation items.
       
       Examples of how you can modify this file:
       - Add NuGet package references:
           <ItemGroup>
               <PackageReference Include="Newtonsoft.Json" Version="11.0.1" />
           </ItemGroup>
       - Add external C# project references:
       <ItemGroup>
           <ProjectReference Include="..\..\..\ExternalLib\ExternalLib.csproj" />
       </ItemGroup>
   -->
   
   <Import Project="$([MSBuild]::GetPathOfFileAbove(MSBuildForUnity.Common.props))" Condition="Exists('$([MSBuild]::GetPathOfFileAbove(MSBuildForUnity.Common.props))')" />
   
   <PropertyGroup>
       <TargetFramework>$(UnityCurrentTargetFramework)</TargetFramework>
   </PropertyGroup>
   
   <!-- SDK.props is imported inside this props file -->
   <Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.props" />
   
   <ItemGroup>
       <!--Add NuGet or Project references here-->
   </ItemGroup>
   
   <!-- SDK.targets is imported inside this props file -->
   <Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.targets" />
   </Project>

3. For additional instructions, see Core Scenarios.

Extended Instructions

Here you can find additional instructions for various things you may want to accomplish:

• Add Support MSB4U to a NuGet Package
• OSX and Linux Support

Features

MSBuildForUnity has several features that can be used independently or in conjunction.

MSBuild Project Builder

The MSBuild Project Builder provides a means of building MSBuild projects from within Unity, where the output is generally consumed by the Unity project.

For details, see the documentation, source, and samples.

MSBuild Project Generator

The MSBuild Project Generator will generate a Visual Studio solution configured for building the Unity project into DLLs outside of Unity. This solution is configured for each of the platforms installed with Unity and the InEditor/Player variants of the assemblies.

MSBuildForUnity NuGet Package

The MSBuildForUnity NuGet package augments the default MSBuild build logic to ensure the build output is suitable for Unity consumption. This package can be referenced from MSBuild projects that are built by the MSBuild Project Builder to add these features:

• Meta file generation - generates .meta files for build output such as .dlls.
• Dependency resolution - all dependencies (through PackageReferences or ProjectReferences) are resolved and sent to the output directory (which is typically under the Unity project's Assets directory).
• Debug symbol patching - enables debugging pre-built dlls (e.g. from NuGet packages) while running in the Unity Editor.

For details, see the documentation, source, and samples.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Prerequisites

The following tools are required to contribute to this project:

• Visual Studio 2017+
• Unity 2018+

To get started, clone the repo, and then run git submodule update --init to initialize submodules.