ドキュメント

Unity Engine

Unity Engine

注釈を使用したコード保持

C# 属性または link.xml ファイルの形式で注釈を使用し、Unity リンカーが削除しないコード部分を指定します。
読み終わるまでの所要時間 15 分最終更新 6日前

注釈を使用して、Unity リンカーがコードの特定のセクションをストリッピングしないようにすることができます。これは、アプリケーションが、例えばリフレクションによって、Unity が静的分析を実行するときに存在しないランタイムコードを生成する場合に役立ちます。注釈は、Unity リンカーに、削除しないコードパターンに関する一般的なガイダンスを提供するか、または、特定の定義済みコードセクションを削除しないように指示します。
コードに注釈を付けてマネージコードのストリッピング処理からコードを保持するために使用できるアプローチは、大きく分けて 2 つあります。
  • ルートアノテーションは、コードの一部をルートとして識別します。Unity リンカーは、ルートとしてマークされたコードを削除しません。ルート注釈の使用はそれほど複雑ではありませんが、Unity リンカーが削除すべきコードを保持している可能性もあります。
  • 依存関係注釈はコード要素間の接続を定義します。依存関係注釈は、ルート注釈に比べて不要なコード保存を削減できます。
これらの各技法は、高いストリッピング レベルでUnityリンカーがストリップするコード量をよりコントロールし、重要なコードがストリップされる可能性を減らします。注釈は、コードがリフレクションを通じて他のコードを参照する場合に特に便利です。なぜなら、Unity リンカーが常にリフレクションの使用を検出できるとは限らないからです。
リフレクションを使用するコードやランタイムに他のコードを生成するコードを保持して、アプリケーション実行時に予期しない動作が発生する可能性を大幅に低減します。Unity リンカーが認識できるリフレクション パターンの例については、Unity 中間言語リンカー リフレクション テスト スイートを参照してください。

ルートアノテーション

ルート注釈は、Unity リンカーにコード要素をルートとして扱わせ、コードストリッピング処理で除去されないようにします。使用できるルート注釈には、コンストラクターやアセンブリとともに個々の型を保持する必要があるかどうかに応じて、次の 2 種類があります。
  • 属性の保持:個々の型をルートとしてアノテーションし、保持します。
  • Link.xml:アセンブリと、それらのアセンブリ内の型、またはその他のコード Entities をルートとしてアノテーションし、保存します。

Preserve 属性を使用したルートのアノテーション

[Preserve]
属性を使用して、コードの特定のセクションを Unity リンカーの静的分析から個別に除外します。この属性を持つコードに注釈を付けるには、保持するコードの最初の部分の直前に
[Preserve]
を追加します。以下のリストは、異なるコード要素を
[Preserve]
属性で注釈付けするときに Unity リンカーが保持する Entities を示しています。
  • アセンブリアセンブリで使用および定義されたすべての型を保持します。
    [Preserve]
    属性をアセンブリに割り当てるには、アセンブリに含まれる任意の C# ファイル内で、名前空間宣言の前に属性宣言を配置します。
  • Type (型): クラスまたは型とそのデフォルトコンストラクタを保持します。
  • "method":メソッド、メソッドを宣言する型、メソッドが返す型、メソッドのすべての引数の型を保持します。
  • プロパティプロパティ、プロパティを宣言する型、プロパティの値の型、およびプロパティ値を取得および設定するメソッドを保持します。
  • フィールドフィールド、フィールド型、フィールドを宣言する型を保持します。
  • Event (イベント): イベント、イベントを宣言する型、型、イベントが返す型、
    [add]
    アクセサー、および
    [remove]
    アクセサーを保持します。
  • delegateデリゲートタイプとデリゲートが呼び出すすべてのメソッドを保持します。
[Preserve]
属性は、型とそのデフォルトコンストラクタの両方を保持したい場合に使用します。どちらか一方を保持し、両方を保持しない場合は、
link.xml
ファイルを使用します。
[Preserve]
属性は、任意のアセンブリと名前空間で定義できます。
PreserveAttribute
クラスを使用したり、サブクラスを作成したり、独自のクラスを作成することができます。例を次に示します。
クラス Foo{ [保存] public void PreservedMethod(){}}
プロジェクトに
link.xml
という名前の .xml ファイルを含めると、特定のアセンブリまたはアセンブリの一部のリストを保持できます。
link.xml
ファイルは、プロジェクトの
Assets
フォルダーまたは
Assets
フォルダーのサブディレクトリに存在し、 ファイルに
<linker>
タグが含まれている必要があります。Unity リンカーは、
link.xml
ファイルに保存されているアセンブリ、型、またはメンバーをルートタイプとして扱います。
プロジェクト内の
link.xml
ファイルはいくつでも使用できます。その結果、プラグインごとに個別の保存宣言を提供できます。パッケージに
link.xml
ファイルを含めることはできませんが、非パッケージ
link.xml
ファイルからパッケージアセンブリを参照できます。
link.xml
ファイルの形式の詳細については、Link XML 形式リファレンス を参照してください。

依存関係アノテーション

依存関係アノテーションは、さまざまなコード要素間の依存関係を定義します。これらのアノテーションは、リフレクションなど、Unity リンカーが静的に分析できないコードパターンを保持するのに役立ちます。また、これらの注釈は、ルート要素が使用されないときにコード要素が誤って保持されないようにします。Unity リンカーがコード要素を処理する方法を変更するには、2 つの方法があります。
  • 注釈属性:これらの属性は、Unity リンカーが特定のコードパターン (注釈付き型から派生した型など) を保持する必要があることを示します。
  • AlwaysLinkAssemblyAttribute:この属性を使用して、プロジェクト内の他のアセンブリから参照されていない場合でも、Unity リンカーがアセンブリを処理することを示します。

注釈属性

[Preserve]
属性は、API が常に必要な場合に便利です。その他の属性は、より一般的な保存に役立ちます。例えば、
[RequireImplementorsAttribute]
でインターフェースに注釈を付けることで、特定のインターフェースを実装するすべての型を保持できます。
特定のコーディングパターンに注釈を付けるには、以下の属性を 1 つ以上使用します。
  • このインターフェースを実装するすべての型を依存関係としてマークします。
  • この型から派生したすべての型を依存関係としてマークします。
  • 型のインターフェース実装を依存関係としてマークします。
  • タイプのすべてのメンバーを依存関係としてマークします。
  • カスタム属性を依存関係としてマークします。
これらの属性をさまざまな方法で組み合わせることで、Unity リンカーがコードを保持する方法をより正確にコントロールできます。

AlwaysLinkAssembly attribute

[AlwaysLinkAssembly]
属性は、アセンブリがビルドに含まれる別のアセンブリによって参照されているかどうかにかかわらず、Unity リンカーにアセンブリの検索を強制します。属性はアセンブリにのみ適用できます。
属性は、アセンブリ内のコードを直接保持しません。代わりに、この属性は Unity リンカーにルートマーキングルールをアセンブリに適用するよう指示します。アセンブリのルートマーキング規則に一致するコード要素がない場合でも、Unity リンカーはそのアセンブリをビルドから削除します。
この属性は、
[RuntimeInitializeOnLoadMethod]
属性を持つ 1 つ以上のメソッドを含むプリコンパイル済みアセンブリまたはパッケージアセンブリで使用します。ただし、プロジェクト内のどのシーンでも直接または間接的に使用される型を含まない場合があります。
アセンブリが
[assembly: AlwaysLinkAssembly]
を定義し、ビルドに含まれる別のアセンブリによっても参照されている場合、属性は出力にエフェクトをもたらしません。

追加リソース