Example Project - Assembly Definition Files

Unity Engine
,
1

Important: Assembly Definition Files postponed until Unity 2017.3.

The assembly definition files feature will be disabled in the final release of Unity 2017.2.

The development of the feature was not completed for the release of Unity 2017.2 and is postponed until Unity 2017.3.

Keep an eye out for when the Unity 2017.3 betas become available and try out this feature with complete editor integration.

Hi everybody,
I’d like to share with you an example project to demonstrate usage and capabilities of user-defined managed assemblies, a new feature in Unity 2017.3 with the potential to drastically minimize script compilation times of your projects.

This example project consists of two scripts that run in the editor. One to measure and display editor compilation times in the console, and another to generate lots of generic scripts in separate folders and corresponding assembly definition files. This way you can experience the performance differences custom managed assemblies afford first hand, without having to setup things yourself.

To get started, simply download the project via the link below and open it in 2017.3. The test scripts and their assembly definition files can be generated by clicking on ‘Generate’ in the menu bar.

1280×720 145 KB

The purpose of these scripts and assembly definition files generators is to give you quick access to see what impact custom assemblies can have on compilation times in projects with lots of scripts. The ‘Generate’ menu in the menu bar is exclusive to this example project and not part of the feature itself.

Project link ( 93 kB):
https://oc.unity3d.com/index.php/s/GoVSG4ngRJDFyDC

You can find more information about the update of the script compilation pipeline, assembly definition files, and how to use them here:

Please use this thread to discuss the subject matter.

Edit (10/02/17):
Updated the project to reflect the change of the definition file type from .json to .asmdef.
Edit (09/27/17):
Migrated the thread from the 2017.2 beta forum to the 2017.3 beta forum.
Edit (08/02/17):
Revised folder layout and naming.

5 Likes
2

Hi

Why Assembly Definition info is stored in separate not Unity object text(json) files instead of folder meta files and editor support on it?

Even if this is necessary to have separate file why not use ScriptableObject with exact structure, correct Editor In Inspector and easy script access?

2 Likes
3

The reason we use json files is because we want to standardize the format of the assembly definition files so they can be read and written by third party tooling.

The serialized data format in Unity is not standardized nor documented and could change at any time.

An inspector for the assembly definition files will land in Unity before 2017.2 is released.

2 Likes
4

Opening any of the scripts in Visual Studio Community 2017 results in an error for each of the generated assemblies, with them missing afterwards in the Solution Explorer. Shouldn’t they be suffixed with the assembly name, such AssemblyDefinitions_ExampleProject.Folder0?

5

This is a known issue in the Visual Studio Tools for Unity (VSTU) that has been fixed. The fix should be available in the next release of VSTU.

6

This actually prevents to test this feature at all.

Any idea when the update will be available for VSTU?

7

I love this new feature a lot. I have successfully created assemblies with Visual Studio 2015, but I am asking myself, will there be also a Visual Studio CSharp Project available? I would like to split parts of my application into different assemblies and c# projects by using this feature. Like Unity does with Editor and Plugins today.

Keep up the good work!

8

Hello folks,

Jb from the VSTU team here. In the meantime, we’re making non supported beta builds available for those of you who want to try this feature:

For 2015, just close all Visual Studio instances and install the .msi. You can always revert to the last stable version.
For 2017, you’ll need to install the .msi, and also to install the .vsix in your Visual Studio 2017 instance.

Let us know if you have any issue.

1 Like
9

I’m using VS2012 and it works quite fine. Anything I need to know though?

10

Works perfectly, but how do I reference the default script assembly? Using “ProjectName”, “ProjectName-CSharp” or “Assembly-CSharp” doesn’t seem to work.

This is needed for imported scripts from the Asset Store that use the Editor folder, which gets overriden by custom assemblies.

11

Hi

The assembly definition files cannot reference the default script assemblies (Assembly-CSharp, etc.). As this would create cyclic references, as the default script assemblies have automatic references to to all compatible assembly definition file assemblies.

Just like the default assemblies have automatic references to all compatible pre-compiled managed assemblies.

I’m not sure what you mean by “This is needed for imported scripts from the Asset Store that use the Editor folder, which gets overriden by custom assemblies.”

The assembly definition file assemblies do not override anything in the Editor folder unless they are put inside the Editor folder. Which I think should be avoided. If you have editor only assemblies, you can just specify that it in the “includePlatforms” in the assembly definition file and put the file in any folder in your project.

The current documentation does not explain these details, but it will be addressed in the final documentation in the Unity manual.

2 Likes
12

I think @TFlippy is talking about something I was also mentioning here.

It’s about assetstore packages. If I want to commit an editor tool to the AS and my tool is referencing the UnityEditor.dll, how will that work out if the user, who is downloading my package is using a different version of the UnityEditor.dll?

13

I’m currently using FullInspector from the Asset Store for its inspector extensions, which utilizes several attributes to determine how the objects are serialized or appear in the inspector. But since I moved it in its own assembly in order to be able to use those, the “Editor” folder inside the addon gets ignored and compiles unconditionally when building the game (which results in an error, as it can’t include Editor-related stuff).

Would have it been possible to add a way to have them conditionally compiled / ignored similiar to the way the Editor folder works?

14

@TFlippy Try moving the Editor scripts from FullInspector in a new folder under Assets\Editor and set a different assembly for that(e.g. FullInspector-Editor).

That should do it.

15

Any idea if this works / will work with JetBrains Rider?

16

What’s the workflow when we add, remove or rename a script?

17

Jetbrains team are aware of the feature and looking into anything necessary on their end to support this. But the .sln file should be working correctly, as it uses the same .sln generator as we use for MonoDevelop.

Assembly definition files do not contain any references to script filenames and includes all scripts in the folder it is located it (and child folders, if those do not contain assembly definition files). So adding, removing and renaming scripts does not require any additional editing of the assembly definition files.

18

It works, I was testing it yesterday.
There were minor issue for the case, when Assembly Definition name contain sln name.
Fix was done https://github.com/JetBrains/resharper-unity/commit/aa422b7ca1db2950e4b67abe3bfb00ae9e81041e, but it might not get to the current release. So for now, avoid sln name in Assembly Definition name, which I suppose is a rear case anyway.

19

I have a one improvement request.

Currently, the generated csproj lists files using full path from the root of the Assets directory. So if we have an assembly in following structure:

Assets / Code / Assembly1 / Assembly1.assembly.json
Assets / Code / Assembly1 / Script1.cs
Assets / Code / Assembly1 / Utils /Script2.cs

Both project would contains “Assembly / Code / Assembly1” folders until they actually start showing script files relevant to our assembly. So it would be:

Assets → Code → Assembly1 → Script1.cs
Assets → Code → Assembly1 → Utils → Script2.cs

Since we are only presented in files at or below the level, where assembly definition file is located, would it be possible to display the files in relation to where assembly file is located, instead of in relation to the root of Assets folder?

In the example I would expect that the project would contain files like this:

Script1.cs
Utils → Script2.cs

I think this is probably more a request to VSTU, not unity. However, it would make some external tools, like Resharper work way better in respect to the namespaces, most probably we do not want to have “Assets.Code.Assembly1” in our namespace.

1 Like
20

Gotcha, so what you’ve decided to implement is an extension to the already existing folder structure where Plugins and StandardAssets have their own .dll
It’s not bad but why didn’t you chose namespaces as a split boundary? I mean if you look at who knows about interdependencies, it’s not the level designer, not the animator or anyone else that has the ability to move files around the project, it’s the programmer, so why not bind assembly definition to the code itself? That was hinted a few years back by Lucas and made so much sense from my end that I started using namespace :slight_smile: