.NET Tools
Essential productivity kit for .NET and game developers
Unity Assembly Definition Files and Rider 2018.2
Last time, we saw how Rider 2018.2 had added support for Unity’s new Packages to the Unity Explorer. This time, we’ll take a look at how Rider supports a key feature of Packages – Assembly Definition Files, with validation, code completion, navigation and even a little bit of refactoring! Let’s see how Rider can help you author and edit your .asmdef files.
In this series:
- Unity Package Explorer
- Assembly Definition Files
- Unity Editor integration updates
- Unity specific code analysis
What are Assembly Definition Files?
Let’s take a look at a bit of background before we dive into new features. Unity 2017.3 introduced Assembly Definition Files as a way to solve a couple of problems.
Firstly, it can help with compile and build time. Traditionally, Unity will generate one big project for most of the source files in your Assets folder (and one or two others for some special folders). A larger Unity project means a larger C# project, which leads to a longer compilation time and a longer delay before your game or visualisation can switch back to play mode.
If you add a .asmdef file to a folder, Unity will generate a new C# project for all of the files in that folder, splitting the single monolithic project up into multiple class libraries. Good from a code structure and design point of view, but with appropriate references and dependencies, it’s also good from a compile time point of view, as you’ll now only compile projects that have changed.
Secondly, Assembly Definition Files are essential to Unity Packages. A package is essentially a folder of source and other assets which you want to add to be able to use from your project, but keep separate from your own Assets folder.
When working with a referenced package, this folder lives in a read-only cache that isn’t part of your Unity project at all. These folders need to be compiled into an assembly and added as an assembly reference to the C# projects in your solution. In order to do this, Unity needs to know how to build the assembly – and that’s exactly what the Assembly Definition File does.
And of course, you can use definition files in your editable, embedded packages in the Packages folder, too, to get the benefits of a faster rebuild by only compiling the projects when they’ve changed.
You can read more about Assembly Definition Files in the Unity docs.
Rider support
When you’re in the Unity Editor, you use the Inspector UI to edit assembly definitions, but when you’re in Rider, you’ll see the underlying JSON file is part of the project. So how does Rider handle Assembly Definition Files?
Since Rider 2018.1, Assembly Definition Files have been integrated with the Unity explorer tool window – if a folder directly or indirectly contains an .asmdef file, we show the assembly definition name next to the folder name, so you know that a folder, or one of its sub-folders is part of another project. With Rider 2018.2 adding Packages to the Unity explorer, we’ve done the same thing with embedded packages that are part of your project (read only reference packages are converted to binary assembly references, so we don’t show project names in this case).
And of course you can create a .asmdef file from the Unity explorer or the Solution explorer. Simply right click on a folder and select Add and select the Assembly Definition File template. You can also edit this template in Preferences | Editor | File Templates | Unity.
For editing the code, we’ve contributed a JSON schema to schemastore.org, which means that Rider (and ReSharper, and in fact any editor that supports JSON schema) will automatically download it and use it to provide basic features to help edit the file and to make sure the content is correct.
The schema describes the expected elements in the file, and Rider can use this information to provide code completion for elements – even for array elements, such as the required platforms. There’s even some context help, with description tooltips.
On top of code completion, Rider uses the schema to validate the file, so Rider will warn you if you have missing required elements, or if there are duplicated elements, or if the array of expected platform contains an unexpected value. There’s also a quick fix to remove duplicate or invalid values.
But there are values in the .asmdef file that can’t be validated purely by schema, so we’ve added some extra Rider functionality on top. For example, the references array object lists other Assembly Definition Files that should be treated as dependencies – added as references in the generated C# project. Rider can help here, too.
Rider will validate these references, and warn you if you have a duplicate reference, or have accidentally added a reference to the current file. Alt+Enter to the rescue!
Even better, Rider will provide code completion of all of the assembly definitions in the project, and provide code completion when trying to add a reference.
You can even use Go To Declaration and Find Usages to see where an assembly is defined, or where it’s being used as a reference. Right now, this only includes the .asmdef files that are included in the C# solution, so any referenced (read only) packages don’t appear in the index, but we’ll adding those in a future release.
And if you need to change the name of an assembly definition, you can use Rider’s Rename refactoring to change the name, and all references will be automatically updated. Rider will even rename the file to match, too.
In fact, if the name of the file and the name element are out of sync, Rider will suggest renaming the file, and provide a quick fix to do this automatically.
In our next post, we’ll see how we’re improving our Unity Editor integration, such as working with Unity logs. Download Rider 2018.2 today, and try it for your Unity development. Let us know how you get on!
Subscribe to a monthly digest curated from the .NET Tools blog:
