← Руководство

Ссылка XML на форматирование

Этот справочник содержит информацию о правильном форматировании файлов link.xml, включая действительные элементы и атрибуты XML и примеры использования.

Примечание: Формат link.xml Unity основан на формате дескриптора ILLink (Intermediate Language Linker), используемом линкером .NET. Для авторитетной ссылки на этот формат, обратитесь к документации в dotnet/runtime репозитории.

Поддерживаемые XML элементы

Следующие элементы XML поддерживаются в файлах link.xml:

Элемент	Описание
`<linker></linker>`	Должен использоваться во всех файлах `link.xml` в качестве наиболее внешнего элемента, окружающего все остальные элементы.
`<assembly></assembly>`	Заявление аннотаций сохранения кода, специфичных для сборки.
`<type></type>`	Заявление аннотаций сохранения кода, специфичных для типа.
`<field></field>`	Заявление аннотаций сохранения кода, специфичных для поля.
`<method></method>`	Заявление аннотаций сохранения кода, специфичных для метода.
`<property></property>`	Заявление аннотаций сохранения кода, специфичных для свойства.
`<event></event>`	Объявление аннотаций сохранения кода, специфичных для события.

Примеры использования всех этих элементов см. в Примеры использования.

Поддерживаемые атрибуты XML

Атрибут	Описание
`accessors`	Применяется к элементу `<property>`, чтобы указать, какие из методов доступа к свойству сохранить.
`feature`	Исключение сохранений для функций, которые не поддерживаются на основе параметров текущей сборки. Дополнительные сведения и пример использования см. в Исключения функций.
`fullname`	Идентифицируйте кодовый элемент по имени, включая его родительское имя сборки в качестве префикса. Используйте `fullname` всякий раз, когда `name` может быть неоднозначным.
`ignoreIfMissing`	Применяется к элементу `<assembly>` для объявления сохранений для сборки, которая не существует во время всех сборок Player. Например, см. Игнорирование недостающей сборки.
`ignoreIfUnreferenced`	Применяется к элементу `<assembly>` для сохранения объектов в сборке только в том случае, если хотя бы один из его членов имеет ссылку на другую сборку. Примеры использования см. в Игнорирование не имеющей ссылки сборки.
`name`	Идентифицируйте кодовый элемент только по имени, без родительской сборки в качестве префикса. Если имя сборки уже было указано с `fullname` в родительском элементе XML, дочерние элементы XML могут идентифицировать кодовый элемент только по `name`.
`preserve`	Укажите уровень элементов кода, которые должны быть сохранены от удаления. Допустимые значения: `all`: Сохранить весь элемент и все его члены. `fields`: Сохранить тип и все его поля, но не методы. `methods`: Сохранить тип и все его методы, но не поля. `nothing`: Сохранить существование типа/метаданных, но не его членов.
`signature`	Идентифицируйте элемент кода по его подписи. Подпись метода состоит из типа возврата, имени и параметров. Подпись поля, свойства или события состоит из типа и имени. Для примера использования см. Примеры использования.
`windowsruntime`	Должен быть добавлен к элементу `<assembly>` в файле `link.xml` при определении сохранений для сборки Windows Runtime Metadata (.winmd). Примеры использования см. в Windows Сборка метаданных времени выполнения.

Примеры использования всех этих атрибутов см. в Примеры использования.

Примеры использования

Следующие примеры демонстрируют правильное использование поддерживаемых элементов и атрибутов XML.

Различные способы объявления корневых типов сборки

Следующие примеры иллюстрируют различные способы объявления корневых типов сборок проекта с помощью файла link.xml:

<linker>
  <!--Preserve types and members in an assembly-->
  <assembly fullname="AssemblyName">
    <!--Preserve an entire type-->
    <type fullname="AssemblyName.TypeName" preserve="all"/>

    <!--No "preserve" attribute and no members specified means preserve all members-->
    <type fullname="AssemblyName.TypeName"/>

    <!--Preserve all fields on a type-->
    <type fullname="AssemblyName.TypeName" preserve="fields"/>

    <!--Preserve all methods on a type-->
    <type fullname="AssemblyName.TypeName" preserve="methods"/>

    <!--Preserve the type only-->
    <type fullname="AssemblyName.TypeName" preserve="nothing"/>

    <!--Preserving only specific members of a type-->
    <type fullname="AssemblyName.TypeName">
        
      <!--Fields-->
      <field signature="System.Int32 FieldName" />

      <!--Preserve a field by name rather than signature-->
      <field name="FieldName" />
      
      <!--Methods-->
      <method signature="System.Void MethodName()" />

      <!--Preserve a method with parameters-->
      <method signature="System.Void MethodName(System.Int32,System.String)" />

      <!--Preserve a method by name rather than signature-->
      <method name="MethodName" />

      <!--Properties-->

      <!--Preserve a property, its backing field (if present), 
          getter, and setter methods-->
      <property signature="System.Int32 PropertyName" />

      <property signature="System.Int32 PropertyName" accessors="all" />

      <!--Preserve a property, its backing field (if present), and getter method-->
      <property signature="System.Int32 PropertyName" accessors="get" />

      <!--Preserve a property, its backing field (if present), and setter method-->
      <property signature="System.Int32 PropertyName" accessors="set" />

      <!--Preserve a property by name rather than signature-->
      <property name="PropertyName" />

      <!--Events-->

      <!--Preserve an event, its backing field (if present), add, and remove methods-->
      <event signature="System.EventHandler EventName" />

      <!--Preserve an event by name rather than signature-->
      <event name="EventName" />

    </type>
  </assembly>
</linker>

Объявление целых сборок корнями

В следующем примере показано, как можно объявить целые сборки:

<!--Preserve an entire assembly-->
  <assembly fullname="AssemblyName" preserve="all"/>

  <!--No "preserve" attribute and no types specified means preserve all-->
  <assembly fullname="AssemblyName"/>

  <!--Fully qualified assembly name-->
  <assembly fullname="AssemblyName, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null">
    <type fullname="AssemblyName.Foo" preserve="all"/>
  </assembly>

  <!--Force an assembly to be processed for roots but don't explicitly preserve anything in particular. Useful when the assembly isn't referenced.-->
  <assembly fullname="AssemblyName" preserve="nothing"/>

Сохранение вложенных или общих типов

В следующем примере показано, как сохранить вложенные или общие типы:

<!--Examples with generics-->
    <type fullname="AssemblyName.G`1">

      <!--Preserve a field with generics in the signature-->
      <field signature="System.Collections.Generic.List`1<System.Int32> FieldName" />

      <field signature="System.Collections.Generic.List`1<T> FieldName" />

      <!--Preserve a method with generics in the signature-->
      <method signature="System.Void MethodName(System.Collections.Generic.List`1<System.Int32>)" />

      <!--Preserve an event with generics in the signature-->
      <event signature="System.EventHandler`1<System.EventArgs> EventName" />

    </type>

    <!--Preserve a nested type-->
    <type fullname="AssemblyName.H/Nested" preserve="all"/>

    <!--Preserve all fields of a type if the type is used.  If the type isn't used, it will be removed-->
    <type fullname="AssemblyName.I" preserve="fields" required="0"/>

    <!--Preserve all methods of a type if the type is used. If the type isn't used, it will be removed-->
    <type fullname="AssemblyName.J" preserve="methods" required="0"/>

    <!--Preserve all types in a namespace-->
    <type fullname="AssemblyName.SomeNamespace*" preserve="all"/>

    <!--Preserve all types with a common prefix in their name-->
    <type fullname="Prefix*" preserve="all"/>

Игнорирование отсутствующей сборки

Используйте атрибут ignoreIfMissing элемента <assembly>, если вам нужно объявить сохранения для сборки, которая не существует во время всех сборок Player:

<linker>
  <assembly fullname="Foo" ignoreIfMissing="1">
    <type name="TypeName"/>
  </assembly>
</linker>

Игнорирование нессылочной сборки

Используйте атрибут ignoreIfUnreferenced элемента <assembly>, чтобы сохранить объекты в сборке только тогда, когда хотя бы один тип упоминается в другой сборке:

<linker>
  <assembly fullname="Bar" ignoreIfUnreferenced="1">
    <type name="TypeName"/>
  </assembly>
</linker>

Windows Сборка метаданных времени выполнения

Атрибут windowsruntime элемента <assembly> должен использоваться при определении сохранений для сборки метаданных времени выполнения Windows (.winmd):

<linker>
  <assembly fullname="Windows" windowsruntime="true">
    <type name="TypeName"/>
 </assembly>
</linker>

Исключения функций

Этот атрибут используется в файле mscorlib.xml, встроенном в mscorlib.dll, но вы можете использовать его в любом файле link.xml, когда это уместно.

В ходе Высокая уровень стрипинга, Unity linker исключает сохранения для функций, которые не поддерживаются в соответствии с настройками текущей сборки:

remoting — Исключается при нацеливании на IL2CPP скриптовый бэкэнд.
sre — Исключается при нацеливании на IL2CPP скриптовый бэкэнд.
com — исключается при таргетировании платформ, не поддерживающих COM..

Например, следующий файл link.xml сохраняет один метод типа на платформах, поддерживающих COM, и один метод на всех платформах:

<linker>

    <assembly fullname="Foo">

        <type fullname="Type1">

            <!--Preserve FeatureOne on platforms that support COM-->

            <method signature="System.Void FeatureOne()" feature="com"/>

            <!--Preserve FeatureTwo on all platforms-->

            <method signature="System.Void FeatureTwo()"/>

        </type>

    </assembly>

</linker>