21a1f248a3
Add support for .NET Framwork 4.7.1 with Unity 2021.2 or newer |
||
---|---|---|
AzurePipelines | ||
Documentation | ||
Samples | ||
Source | ||
Tests/ProjectGeneration | ||
.gitattributes | ||
.gitmodules | ||
CODE_OF_CONDUCT.md | ||
Directory.Build.props | ||
LICENSE | ||
README.md | ||
SECURITY.md |
README.md
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.
-
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.
-
-
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>
-
For additional instructions, see Core Scenarios.
Extended Instructions
Here you can find additional instructions for various things you may want to accomplish:
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
PackageReference
s orProjectReference
s) 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 opencode@microsoft.com with any additional questions or comments.
Prerequisites
The following tools are required to contribute to this project:
To get started, clone the repo, and then run git submodule update --init
to initialize submodules.