Бөлісу құралы:

Параметры обрезки

  • Мақала

Следующие свойства и элементы MSBuild влияют на поведение обрезанных автономных развертываний. Некоторые параметры упоминают ILLink, то есть имя базового инструмента, реализующего обрезку. Дополнительные сведения о базовом средстве см. в документации по средству обрезки.

Обрезка с помощью параметра PublishTrimmed появилась в .NET Core 3.0. Другие параметры доступны только в .NET 5 и более поздних версиях.

Включение обрезки

  • <PublishTrimmed>true</PublishTrimmed>

    Включение обрезки во время публикации. Этот параметр также отключает несовместимые функции обрезки и включает анализ обрезки во время сборки. В приложениях .NET 8 и более поздних версий этот параметр также включает привязку конфигурации и генераторы источников делегата делегата.

Примечание.

Если вы указали обрезку в командной строке, процесс отладки будет отличаться, и в конечном продукте могут возникнуть дополнительные ошибки.

Поместите этот параметр в файл проекта, чтобы обеспечить применение параметра во время dotnet build, а не только dotnet publish.

Этот параметр позволяет обрезать и обрезать все сборки по умолчанию. В .NET 6 по умолчанию обрезались [AssemblyMetadata("IsTrimmable", "True")] только сборки, которые решили обрезаться. Вы можете вернуться к предыдущему поведению с помощью <TrimMode>partial</TrimMode>.

Этот параметр обрезает все сборки, настроенные для обрезки. При использовании Microsoft.NET.Sdk .NET 6 это включает в себя все сборки с [AssemblyMetadata("IsTrimmable", "True")], что относится к сборкам среды выполнения .NET. В .NET 5 сборки из пакета среды выполнения netcoreapp настраиваются для обрезки с помощью <IsTrimmable> метаданных MSBuild. Другие пакеты SDK могут определять разные значения по умолчанию.

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

Степень детализации обрезки

TrimMode Используйте свойство, чтобы задать для обрезки детализации либо partialfull. Параметр по умолчанию для консольных приложений (и начиная с .NET 8, веб-sdk) — full:

<TrimMode>full</TrimMode>

Чтобы обрезать только сборки, которые выбрали обрезку, задайте для свойства partialзначение :

<TrimMode>partial</TrimMode>

При изменении режима partialобрезки можно выбрать отдельные сборки для обрезки с помощью <TrimmableAssembly> элемента MSBuild.

<ItemGroup>
  <TrimmableAssembly Include="MyAssembly" />
</ItemGroup>

Это эквивалентно настройке [AssemblyMetadata("IsTrimmable", "True")] при сборке сборки.

Следующие параметры степени детализации управляют тем, насколько агрессивно отбрасываются неиспользуемые IL. Их можно настроить в качестве свойства, влияющего на всех сборки, подаваемые на вход средства обрезки, или в качестве метаданных в отдельной сборке, которые переопределяют настроенное свойство.

  • <TrimMode>link</TrimMode>

    Включите функцию обрезки на уровне элементов, которая удаляет неиспользуемые элементы из типов. Используется в .NET 6 и более поздних версиях по умолчанию.

  • <TrimMode>copyused</TrimMode>

    Включите обрезку на уровне сборки, которая сохраняет всю сборку, если используется любая часть (статически понятный способ).

Сборки с метаданными <IsTrimmable>true</IsTrimmable>, но без явного TrimMode будут использовать глобальную TrimMode. Значением по умолчанию параметра TrimMode для Microsoft.NET.Sdk является link в .NET 6 и более поздних версий и copyused в предыдущих версиях.

Обрезка дополнительных сборок

В .NET 6 и более поздних версиях параметр PublishTrimmed обрезает сборки с помощью следующего атрибута уровня сборки:

[AssemblyMetadata("IsTrimmable", "True")]

У библиотек платформы есть этот атрибут. В .NET 6 и более поздних версиях также можно выбрать обрезку библиотеки без использования этого атрибута, указав сборку по имени (без расширения .dll).

Параметры обрезки для отдельных сборок

При публикации обрезанного приложения пакет SDK выдает ItemGroup с именем ManagedAssemblyToLink, который представляет набор файлов для обработки обрезки. ManagedAssemblyToLink Может иметь метаданные, которые управляют поведением обрезки для каждой сборки. Чтобы задать эти метаданные, создайте целевой объект, выполняемый перед встроенным целевым объектом PrepareForILLink. В следующем примере показано, как включить обрезку MyAssembly.

<Target Name="ConfigureTrimming"
        BeforeTargets="PrepareForILLink">
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'">
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

Этот целевой объект также можно использовать для переопределения поведения обрезки, указанного автором библиотеки, путем установки сборки <IsTrimmable>false</IsTrimmable> с [AssemblyMetadata("IsTrimmable", "True"])помощью .

Не добавляйте или не удаляйте элементы из ManagedAssemblyToLinkпакета SDK, так как пакет SDK вычисляет этот набор во время публикации и ожидает, что он не изменится. Поддерживаются следующие метаданные.

  • <IsTrimmable>true</IsTrimmable>

    Управление тем, обрезана ли данная сборка.

  • <TrimMode>copyused</TrimMode> или <TrimMode>link</TrimMode>

    Управление степенью детализации этой сборки. Эти метаданные имеют приоритет над глобальным TrimMode. Установка TrimMode для сборки подразумевает <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Управление тем, отображаются ли отдельные предупреждения для этой сборки.

Корневые сборки

Если сборка не обрезана, она считается "корневой", что означает, что она и все его статически понятные зависимости будут сохранены. Дополнительные сборки могут быть "корневыми" по имени (без .dll расширения):

<ItemGroup>
  <TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>

Корневые дескрипторы

Другой способ указания корневых элементов для анализа — использование XML-файла, в котором используется формат дескриптора средства обрезки. Это позволяет использовать корневые члены вместо целой сборки.

<ItemGroup>
  <TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>

Например, MyRoots.xml может корень определенного метода, который динамически обращается к приложению:

<linker>
  <assembly fullname="MyAssembly">
    <type fullname="MyAssembly.MyClass">
      <method name="DynamicallyAccessedMethod" />
    </type>
  </assembly>
</linker>

Предупреждения при анализе

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Включите предупреждения при анализе обрезки.

Обрезка удаляет IL, который недоступен статически. Приложения, использующие отражение или другие шаблоны, которые создают динамические зависимости, могут быть нарушены путем обрезки. Чтобы предупредить об таких шаблонах, установите для этого значение <SuppressTrimAnalysisWarnings>false. Этот параметр выдает предупреждения обо всем приложении, включая собственный код, код библиотеки и код платформы.

Анализатор Roslyn

Параметр PublishTrimmed в .NET 6+ также включает анализатор Roslyn, показывающий ограниченный набор предупреждений анализа. Вы также можете включить или отключить анализатор независимо от PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Включение анализатора Roslyn для подмножества предупреждений анализа обрезки.

Отключение предупреждений

Вы можете отключить отдельные коды предупреждений, используя обычные свойства MSBuild, уважаемые цепочкой инструментов, включая NoWarn, WarningsAsErrorsWarningsNotAsErrorsи TreatWarningsAsErrors. Существует дополнительный параметр, который управляет поведением ilLink warn-as-error независимо:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Не обрабатывайте предупреждения ILLink как ошибки. Это может быть полезно, чтобы избежать включения предупреждений обрезки в ошибки при обработке предупреждений компилятора как ошибок глобально.

Отображение подробных предупреждений

В .NET 6+анализ обрезки создает по крайней мере одно предупреждение для каждой сборки, полученной из нее PackageReference, указывая, что внутренние элементы сборки несовместимы с обрезкой. Можно также отобразить отдельные предупреждения для всех сборок:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Отображение всех подробных предупреждений вместо совмещения их в одном предупреждении для каждой сборки.

Удаление символов

Символы обычно обрезаются в соответствии с обрезными сборками. Можно также удалить все символы.

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Удалите символы из обрезанного приложения, включая внедренные PDB-файлы и отдельные PDB. Это относится как к коду приложения, так и к любым зависимостям, которые входят в состав символов.

Пакет SDK также позволяет отключить поддержку отладчика, используя свойство DebuggerSupport. Если поддержка отладчика отключена, обрезка автоматически удаляет символы (TrimmerRemoveSymbols по умолчанию — true).

Усечение функций библиотеки инфраструктуры

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

  • <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (по умолчанию)

    Удалите код, который создает пулы автоосвобождения на поддерживаемых платформах. См. раздел AutoreleasePool для управляемых потоков. Это значение по умолчанию для пакета SDK для .NET.

  • <DebuggerSupport>false</DebuggerSupport>

    Удалите код, обеспечивающий лучшую отладку. Этот параметр также удаляет символы.

  • <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

    Удалите поддержку сериализации BinaryFormatter. Дополнительные сведения см. в разделе Методы сериализации BinaryFormatter устарели.

  • <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

    Удалите небезопасный код кодировки UTF-7. Дополнительные сведения см. в разделе Пути к коду в кодировке UTF-7 устарели.

  • <EventSourceSupport>false</EventSourceSupport>

    Удалите код или логику, связанную с EventSource.

  • <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

    Удалите код, связанный с поддержкой диагностики для System.Net.Http.

  • <InvariantGlobalization>true</InvariantGlobalization>

    Удалите код и данные, связанные с глобализацией. Дополнительные сведения см. в разделе Инвариантный режим.

  • <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

    Удалите логику обновления метаданных, связанную с горячей перезагрузкой.

  • <StackTraceSupport>false</StackTraceSupport> (.NET 8+)

    Удалите поддержку создания трассировок стека (например, Environment.StackTraceили Exception.ToString) среды выполнения. Объем информации, которая будет удалена из строк трассировки стека, может зависеть от других параметров развертывания. Этот параметр не влияет на трассировки стека, созданные отладчиками.

  • <UseNativeHttpHandler>true</UseNativeHttpHandler>

    Используйте реализацию платформы HttpMessageHandler по умолчанию для Android/iOS и удалите управляемую реализацию.

  • <UseSystemResourceKeys>true</UseSystemResourceKeys>

    Удалите сообщения об исключениях для сборок System.*. При возникновении исключения из System.* сборки сообщение является упрощенным идентификатором ресурса вместо полного сообщения.

Эти свойства вызывают обрезку связанного кода, а также отключение функций с помощью файла среды выполнения . Дополнительные сведения об этих свойствах, включая соответствующие параметры runtimeconfig, см. в разделе, посвященном переключению функций. Некоторые пакеты SDK могут иметь значения по умолчанию для этих свойств.

Функции платформы, отключенные при обрезке

Следующие функции несовместимы с обрезкой, так как для них требуется код, на который не ссылается статически. Эти функции отключены по умолчанию в обрезаемых приложениях.

Предупреждение

Включите эти функции на свой собственный риск. Они, скорее всего, нарушат работу обрезанных приложений, которые не доработаны, чтобы сохранить код, на который имеются динамические ссылки.

  • <BuiltInComInteropSupport>

    Встроенная поддержка COM отключена.

  • <CustomResourceTypesSupport>

    Использование пользовательских типов ресурсов не поддерживается. Пути кода ResourceManager, использующие отражение для пользовательских типов ресурсов, обрезаются.

  • <EnableCppCLIHostActivation>

    Активация узла C++/CLI отключена.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    Использование DesigntimeLicenseContextSerializer сериализации BinaryFormatter отключено.

  • <StartupHookSupport>

    Выполнение кода до MainDOTNET_STARTUP_HOOKS этого не поддерживается. Дополнительные сведения см. в разделе Перехватчик запуска узла.