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:

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.

Assembly Definition File contents

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).

Unity explorer showing assembly definition names

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.

JSON code completion inside an assembly definition file

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.

JSON validation of assembly definition files

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.

JSON quick fix

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!

Warning on reference to self

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.

Code completion of references

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.

Find usages of assembly definition

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.

Rename assembly definition

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.

Rename file to match assembly definition name quick fix

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!

This entry was posted in How-To's and tagged , , . Bookmark the permalink.

One Response to Unity Assembly Definition Files and Rider 2018.2

  1. Pingback: Dew Drop - September 27, 2018 (#2812) - Morning Dew

Leave a Reply

Your email address will not be published. Required fields are marked *