Skip to content

Commit 37cfcdc

Browse files
author
Andrei Borodin
authored
Merge pull request #122 from microsoft/documentation/coreScenarios
Added core scenarios documentation
2 parents 4d36e66 + 962e349 commit 37cfcdc

File tree

6 files changed

+144
-0
lines changed

6 files changed

+144
-0
lines changed

‎Documentation/CoreScenarios.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Core Scenarios w/ MSBuildForUnity (MSB4U)
2+
3+
This documentation outlines instructions for the core scenarios that are enabled with MSB4U, and how to get started with them. Each scenario assumes the reader understand how to add MSB4U to the Unity project, if not, take a look at [the instructions](../README.md#Quick-Start). If you have issues following scenarios, see [troubleshooting](Troubleshooting.md).
4+
5+
## Scenario 1: Adding NuGet Dependency to Unity Project
6+
7+
**GOAL:** We have a Unity project where we want to add the `Newtonsoft.Json` NuGet package for use in the project.
8+
9+
To make this happen, we will simply rely on MSB4U providing us with a top-level MSBuild project that builds itself plus other MSBuild projects in our Unity assets directory, and add our reference to it. As a result, this project will be built, and it's dependencies and references will be brought into it's output directory inside the Unity assets folder.
10+
11+
### Scenario 1 Instructions
12+
13+
1. Find the generated dependencies project in your Assets folder. It is named after your Unity project; ie. `(UnityProjectName).Dependencies.msb4u.csproj`.
14+
2. Double-click the project, to open it in Visual Studio.
15+
3. Right-click on the `(UnityProjectName).Dependencies.msb4u`, and press `Manage NuGet Packages...`
16+
![Manage NuGet Packages](Images/ManageNuGetPackagesVS.png)
17+
4. In the NuGet Manager window, ensure `Browse` is Selected, and select `Newtonsoft.Json`
18+
![Select Newtosnoft.Json Package](Images/SelectNewtonsoftVS.png)
19+
5. On the right side, press `Install` to install it to the project.
20+
> **NOTE:** Ensure to save the project in Visual Studio.
21+
6. *Temporary Limitation:* Open the project file in any text editor, and ensure that the `PackageReference` is above the `Import Targets`, see example below:
22+
23+
```xml
24+
<!-- SDK.props is imported inside this props file -->
25+
<Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.props" />
26+
27+
<ItemGroup>
28+
<PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
29+
</ItemGroup>
30+
31+
<!-- SDK.targets is imported inside this props file -->
32+
<Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.targets" />
33+
```
34+
35+
7. Back in Unity, the build should now happen and your dependency will appear under `Dependencies\{Current TargetFramework}\` folder.
36+
37+
## Scenario 2: Share C# Library between Unity Projects
38+
39+
**GOAL:** We have two Unity projects, and want to share a C# library that contains common code.
40+
41+
This is similar to `Scenario 1`, but we will rely on the editing the dependency project manually here.
42+
43+
### Scenario 2 Instructions
44+
45+
1. Find the generated dependencies project in your Assets folder. It is named after your Unity project; ie. `(UnityProjectName).Dependencies.msb4u.csproj`.
46+
2. Double-click the project, to open it in Visual Studio.
47+
3. Right-click on the `(UnityProjectName).Dependencies.msb4u`, and press `Edit (UnityProjectName).Dependencies.msb4u.csproj`
48+
![Manage NuGet Packages](Images/EditProjectVS.png)
49+
4. In the text window, add your `ProjectReference` as follows:
50+
51+
```xml
52+
<!-- SDK.props is imported inside this props file -->
53+
<Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.props" />
54+
55+
<ItemGroup>
56+
<!--Add NuGet or Project references here-->
57+
<ProjectReference Include="..\Relative\Path\To\Your.csproj" />
58+
</ItemGroup>
59+
60+
<!-- SDK.targets is imported inside this props file -->
61+
<Import Project="$(MSBuildForUnityGeneratedProjectDirectory)\$(MSBuildProjectName).g.targets" />
62+
```
63+
64+
5. Back in Unity, the build should now happen and your compiled project binary will appear under `Dependencies\{Current TargetFramework}\` folder.
65+
66+
## Scenario 3: Distribute Source w/ NuGet Package
67+
68+
**GOAL:** We want to distribute a .unitypackage (or zip file) that has a dependency on a NuGet package.
69+
70+
In `Scenario 1` and `Scenario 2` we seen how we can modify the MSBuild project provided to us by MSB4U to add a reference to our dependencies. Here, we will actually craft a simple MSBuild project where we will specify our dependency, and package it up along with our source code. Then, we will bring this .unitypackage into the consuming Unity project that has MSB4U installed, which will result in our project being built and it's dependency brought into the consuming Unity project assets folder.
71+
72+
> **NOTE:** For this scenario, it is assumed that the reader knows how to create a Unity package and import it into a project.
73+
74+
### Scenario 3 Instructions
75+
76+
1. Open up a Unity project, and setup a folder in the Assets directory with the following files (and contents). The CSProject file is specially documented to explain each piece.
77+
- `MyComponent.csproj`
78+
79+
```xml
80+
<Project>
81+
<!-- Import the MSB4U generated common project as we will rely on it. -->
82+
<Import Project="$([MSBuild]::GetPathOfFileAbove(MSBuildForUnity.Common.props))" Condition="Exists('$([MSBuild]::GetPathOfFileAbove(MSBuildForUnity.Common.props))')" />
83+
84+
<PropertyGroup>
85+
<!-- Specify both of these target frameworks, as we will need to support them for Unity 2018 case. -->
86+
<TargetFrameworks>netstandard2.0;net46</TargetFrameworks>
87+
</PropertyGroup>
88+
89+
<PropertyGroup>
90+
<!-- Make sure Unity ignores the contents of the output path. -->
91+
<BaseIntermediateOutputPath>.obj\</BaseIntermediateOutputPath>
92+
<OutputPath>.bin\</OutputPath>
93+
</PropertyGroup>
94+
95+
<!-- Note that this is the special "NoTarget" SDK to prevent this project from producing a dll. -->
96+
<Import Project="Sdk.props" Sdk="Microsoft.Build.NoTargets" Version="1.0.85" />
97+
98+
<ItemGroup>
99+
<!-- Specify your dependency here -->
100+
<PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
101+
</ItemGroup>
102+
103+
<Import Project="Sdk.targets" Sdk="Microsoft.Build.NoTargets" Version="1.0.85" />
104+
</Project>
105+
```
106+
107+
- `.gitignore`
108+
109+
```text
110+
/.bin/
111+
/.obj/
112+
```
113+
114+
- `MyComponent.cs`
115+
116+
```csharp
117+
using Newtonsoft.Json.Linq;
118+
119+
public class Test
120+
{
121+
public static JObject Property = JObject.Parse("{ Hello: \"World\" }");
122+
}
123+
```
124+
125+
2. Now, this folder could be packaged up and distributed.
126+
3. Create a Unity project that will consume this component, and install MSBuildForUnity.
127+
4. Bring this component in, and it will automatically build it.
128+
129+
## Scenario 4: Distribute a UPM Package w/ NuGet Dependency
130+
131+
**GOAL:** We want to distribute our source through UPM, but need a NuGet dependency.
132+
133+
In order to support this scenario, we simply follow `Scenario 3` in terms of setting up the C# project, and then establish a UPM dependency onto the MSBuildForUnity UPM package. This would bring in the MSBuildForUnity package by default and activate your C# Project.
134+
135+
### Scenario 4 Instructions
136+
137+
Instructions coming soon.

‎Documentation/Images/EditProjectVS.png‎

34.2 KB
Loading

‎Documentation/Images/MSBuildRegenerateMenu.png‎

17.8 KB
Loading

‎Documentation/Images/ManageNuGetPackagesVS.png‎

34.3 KB
Loading

‎Documentation/Images/SelectNewtonsoftVS.png‎

88.2 KB
Loading

‎Documentation/Troubleshooting.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Troubleshooting
2+
3+
## Projects didn't Build or Generate Correctly
4+
5+
If you want a complete generation, ensure that the menu `MSBuild > Full Generation Enabled` is checked, if you don't know then most likely you don't need it. Also, you could trigger the regeneration step manually, by invoking `MSBuild > Regenerate C# SDK Projects`.
6+
7+
![Regenerate Menu](Images\MSBuildRegenerateMenu.png)

0 commit comments

Comments
 (0)