특수 폴더와 스크립트 컴파일 순서
어셈블리 정의 프로퍼티

어셈블리 정의

You can use Assembly Definitions to organize the scripts in your Project into assemblies. When you create an Assembly Definition Asset in a folder, Unity compiles a separate managed assembly from all the scripts in that folder. Scripts in subfolders are included unless the subfolder has its own Assembly Definition. These managed assemblies act as a single library within your Unity Project.

An Assembly Definition Asset is a text file, with a file extension of .asmdef, that contains a JSON string that defines the Assembly Definition properties. Select the asset file to set these properties in a Unity Inspector window. You can also use an external editor to edit the JSON directly. See Assembly Definition File format for information about the JSON syntax.

Assembly Definition benefits

When you separate your code into assemblies that have well-defined dependencies, Unity reduces their compilation time by only rebuilding the dependent assemblies when you make a change to a script. Assembly Definitions also help you manage dependencies in Projects that contain platform and Unity-version-specific code.

Without Assembly Definitions, Unity compiles any C# scripts in your Project into one of the predefined, managed assemblies. Unity must then recompile every script in the entire Project when you change any script. This means that the length of time between making a code change and seeing that change in action grows longer as you add more scripts to the Project.

Note: Although it’s not required, whenever you use Assembly Definitions in a Project, you should do so for all of the code in your Project. Otherwise, when you change scripts in one of the predefined assemblies, Unity has to still recompile all the code in your Project, because the predefined assemblies automatically depend upon any assemblies you create using an Assembly Definition.

다음 그림은 여러 개의 어셈블리로 분할된 프로젝트를 나타냅니다.

사전 정의된 어셈블리 vs 수동으로 정의된 어셈블리
사전 정의된 어셈블리 vs 수동으로 정의된 어셈블리

By default, Unity compiles almost all Project scripts into the Assembly-CSharp.dll managed assembly. The example shows a Project that has been divided up into five separate assemblies instead. The Main.dll assembly depends on Stuff.dll and ThirdParty.dll. Stuff.dll depends on Library.dll, and so on. As a result, Unity doesn’t need to recompile any of the other assemblies because of a change to code in Main.dll. And since Main.dll contains fewer scripts, it compiles faster than Assembly-CSharp.dll. Similarly, if the code in Stuff.dll changes, Unity only needs to recompile Main.dll and Stuff.dll, not ThirdParty.dll or Library.dll.

Note: To find out where Unity compiles a particular C# file, select the script file in the Project window and look at the Assembly Information listing in the Inspector:

Assembly-CSharp-Editor.dll 사전 정의된 어셈블리의 스크립트
Assembly-CSharp-Editor.dll 사전 정의된 어셈블리의 스크립트

Assembly Definition Reference Assets

You can use Assembly Definition Reference Assets to add additional folders to an existing Assembly Definition asset.

Using Assembly Definitions

Add Assembly Definition Assets to folders in a Unity Project to define an assembly. After compilation, the assembly contains all the scripts in the folder and its subfolders (unless the subfolders have their own Assembly Definitions). Set the name of the assembly in the Inspector.

어셈블리 정의는 Unity 에셋의 한 가지 타입입니다. 프로젝트 창에서 기존의 어셈블리 정의를 선택하여 프로퍼티를 보거나 변경할 수 있습니다. 어셈블리 정의 에셋 파일 포맷에 관한 내용은 파일 포맷을 참조하십시오.

어셈블리 정의 에셋을 만들려면 다음 단계를 따르십시오.

  1. In the Project window, select the folder that you want to place the Assembly Definition
  2. Go to Assets > Create > Assembly Definition to create a new Assembly Definition
  3. Select the new Assembly Definition you created
  4. Set its properties in the Inspector window

To create an Assembly Definition Reference Asset:

  1. In the Project window, select the folder that you want to add to an existing Assembly Definition Asset to
  2. Go to Assets > Create > Assembly Definition Reference to create the Assembly Definition Reference Asset
  3. Select the new Assembly Definition Reference you created
  4. Set the Assembly Defintiion property so that it references the Assembly Definition asset that you want to add the additional folder to
Assembly Definition Reference Editor
Assembly Definition Reference Editor

You can only create one Assembly Definition or Assembly Definition Reference per folder.

If you create an Assembly Definition or Assembly Definition Reference in a subfolder of a folder that already has an Assembly Definition or Assembly Definition Reference, then Unity compiles any scripts in the subfolder and its children into the assembly defined in the subfolder, not the assembly defined in the parent folder.

Use GUID

The Use GUID option controls how Unity serializes the reference to the Assembly Definition Assets. When you enable Use GUID, Unity saves the reference as the Asset’s GUID, instead of the Assembly Definition name. It’s good practice to use the GUID instead of the name, because it means you can make changes to the name of an Assembly Definition Asset without having to update other Assembly Definition or Assembly Definition Reference files that reference it.

Version Defines

Use Version Defines to handle dependencies between different Resources and Packages in your current Project. This is useful if you want to share your Project through a Package Manager package or an Asset Store package.

To set a version, select the plus sign (+). You can add as many Version Defines to an Assembly Definition as you want. To delete a define, select it in the list, and click the minus sign (-).

When you add a Version Define, the following properties appear:

The Version Defines in the Inspector. In this example, there are two active Version Defines.
The Version Defines in the Inspector. In this example, there are two active Version Defines.
프로퍼티 설명
Resource Select the Package or Module you want to set a define for. The list contains all active Packages and Modules in the Project.
Define Set the name for the define. This define is only set if the Expression returns true.
Expression 선택한 모듈 또는 패키지의 시맨틱 버전 범위입니다. 수학적인 간격 표기법을 사용해야 합니다. 와일드카드는 지원되지 않습니다. 이 프로퍼티는 Microsoft의 .NET 패키지 관리자, NuGet과 동일한 버전 범위를 사용합니다.
Expression outcome 표현식이 나타내는 수학적 등식을 표시합니다.

이전 버전과의 호환성 및 암시적 종속 관계

To maintain compatibility with the existing Predefined Compilation System in Unity, the predefined assemblies reference every assembly you create with an Assembly Definition Asset. This is similar to how the predefined assemblies reference all the precompiled assemblies (such as plug-ins or .dlls) in the Project that are compatible with the active build target.

다음 다이어그램은 사전 정의된 어셈블리, 어셈블리 정의 에셋으로 생성된 어셈블리와 사전 컴파일된 어셈블리 간의 기본 종속 관계를 나타냅니다.

Assembly dependencies
Assembly dependencies

다이어그램의 숫자는 어셈블리 간 레퍼런스를 나타냅니다. 이는 다음과 같이 제어할 수 있습니다.

  1. By default, assemblies you create with Assembly Definition Assets are referenced by the predefined assemblies. You can turn this off by disabling the Auto Referenced option in the Inspector for an Assembly Definition Asset. See Assembly Definition properties. !. The predefined assemblies and assemblies created with Assembly Definition Assets both automatically reference Precompiled assemblies (plug-ins). To turn this default behavior off, disable the Auto Referenced option in the Plugin Inspector. For more ifnormation, see Plugin Inspector.
  2. When you turn off Auto Referenced for a plug-in, you can explicitly reference it in the Inspector for an Assembly Definition Asset. Enable the Asset’s Override References option and add a reference to the plug-in. See Assembly Definition properties.

Note: If you turn off the Auto Referenced option for precompiled assemblies or assemblies Assembly Definition Assets creates, then classes in the precompiled assemblies can no longer reference or use the classes in these assemblies. You cannot declare explicit references for the precompiled assemblies.

Special folders

Unity treats scripts in folders with certain, special names differently than scripts in other folders. However, one of these folders loses its special treatment when you create an Assembly Definition Asset inside it or in a folder above it. You might notice this change iwhen you use Editor folders, which might be scattered throughout your Project (depending on how you organize your code and on the Asset packages you use).

Unity normally compiles any scripts in folders named Editor into the predefined Assembly-CSharp-Editor assembly no matter where those scripts are located. However, if you create an Assembly Definition Asset in a folder that has an Editor folder underneath it, Unity no longer puts those Editor scripts into the predefined Editor assembly. Instead, they go into the new assembly created by your Assembly Definition — where they might not belong. To manage Editor folders, you can do the following:

  • 해당하는 각 Editor 폴더에 어셈블리 정의 에셋을 추가하고 해당 어셈블리의 Platform 프로퍼티를 Editor Platform 에만 사용되도록 설정합니다.
  • 어셈블리 정의에 의해 처리되지 않는 중앙 위치로 모든 에디터별 코드를 이동합니다.

테스트 어셈블리

Test assemblies contain code that tests other code in your Project. As such, they don’t need to be included in release builds of your Project and other, non-test assemblies should not depend on them. You can designate that Unity build a test assembly by checking the Test Assemblies option in the Assembly Definition Asset properties. Setting this property does the following:

  • 사전 정의된 어셈블리가 테스트 어셈블리를 참조하지 못하도록 방지
  • 테스트 어셈블리를 빌드에서 제외
  • NUnit 어셈블리에 대한 레퍼런스 추가

Note: Use BuildOption.IncludeTestAssemblies in your building script to include a testing assembly in a Release or Development build. This only includes the assemblies in your build and does not execute any tests.

API

UnityEditor.Compilation 네임스페이스에서 CompilationPipeline 클래스를 사용하면 Unity가 프로젝트를 위해 빌드한 모든 어셈블리에 대한 정보를 검색해서 가져올 수 있습니다. 여기에는 어셈블리 정의 에셋에 기반하여 생성된 어셈블리도 포함됩니다.

예를 들어 다음 스크립트는 CompilationPipeline을 사용하여 프로젝트의 모든 현재 플레이어 어셈블리를 나열합니다.

using UnityEditor;
using UnityEditor.Compilation;

public static class AssemblyLister
{

    [MenuItem("Tools/List Player Assemblies in Console")]
    public static void PrintAssemblyNames()

    {
        UnityEngine.Debug.Log("== Player Assemblies ==");
        Assembly[] playerAssemblies = 
            CompilationPipeline.GetAssemblies(AssembliesType.Player);

        foreach (var assembly in playerAssemblies)
        {
            UnityEngine.Debug.Log(assembly.name);
        }
    }
}

어셈블리 정의 파일 포맷

Assembly Definition and Assembly Definition Reference Assets are JSON files. You can edit the Assets inside the Unity Editor or modify the JSON content with an external tool.

An Assembly Definition is a JSON object with the following fields:

필드 타입
name 문자열
references (optional) 문자열 배열
includePlatforms (optional) 문자열 배열
excludePlatforms (optional) 문자열 배열
allowUnsafeCode(optional) bool
autoReferenced(optional) bool
overrideReferences(optional) bool
precompiledReferences(optional) 문자열 배열
defineConstraints(optional) 문자열 배열
optionalUnityReferences(optional) 문자열 배열

includePlatformsexcludePlatforms 필드는 같은 어셈블리 정의 파일에서 함께 사용될 수 없습니다.

어셈블리의 이름이나 에셋의 GUID를 사용하여 references 필드에 어셈블리 정의 에셋을 지정할 수 있습니다. 에셋 GUID를 사용하려면 값은 GUID:Asset GUID 와 같은 형태여야 합니다. 예를 들어 “GUID:0ec2b662ccc592241854c1b507df8a89” 를 사용할 수 있습니다. AssetDatabase.AssetPathToGUID는 에셋의 GUID를 검색해서 가져옵니다.

CompilationPipeline.GetAssemblyDefinitionPlatforms() 함수로 플랫폼 이름 스트링을 검색하여 가져올 수 있습니다(현재 에디터에 플랫폼 지원 설치 필요).

An Assembly Definition Reference is a JSON object with the following field:

필드 타입
reference 문자열

The referenced Assembly Definition Asset can be specified by using either the name of the assembly or the GUID of the asset. To use the asset GUID, the value should take the form GUID:Asset GUID, for example “GUID:0ec2b662ccc592241854c1b507df8a89”. AssetDatabase.AssetPathToGUID can be used to retrieve the GUID of an asset.

예시 어셈블리 정의 JSON

MyLibrary.asmdef

{
    "name": "MyLibrary",
    "references": [ "Utility" ],
    "includePlatforms": ["Android", "iOS"]
}

MyLibrary2.asmdef

{
    "name": "MyLibrary2",
    "references": [ "GUID:0ec2b662ccc592241854c1b507df8a89" ],
     "excludePlatforms": ["WebGL"]
}
특수 폴더와 스크립트 컴파일 순서
어셈블리 정의 프로퍼티