Opciones de recorte

  • Artículo

Las propiedades y elementos de MSBuild descritos en este artículo influyen en el comportamiento de las implementaciones recortadas y independientes. Algunas de las opciones mencionan ILLink, que es el nombre de la herramienta subyacente que implementa el recorte. Para obtener más información sobre la herramienta subyacente, vea la documentación del recortador.

El recorte PublishTrimmed con se presentó en .NET Core 3.0. Las otras opciones están disponibles en .NET 5 y versiones posteriores.

Habilitación del recorte

  • <PublishTrimmed>true</PublishTrimmed>

    Habilite el recorte durante la publicación. Esta configuración también desactiva las características incompatibles con el recorte y habilita el análisis de recorte durante la compilación. En las aplicaciones de .NET 8 y versiones posteriores, esta configuración también habilita los generadores de origen de delegado de configuración y solicitud.

Nota:

Si especifica el recorte como habilitado desde la línea de comandos, la experiencia de depuración variará y es posible que encuentre errores adicionales en el producto final.

Coloque este valor en el archivo del proyecto para asegurarse de que se aplica durante dotnet build, no solo dotnet publish.

Esta configuración permite recortar y recortar todos los ensamblados de forma predeterminada. En .NET 6, solo se recortaron los ensamblados que optaron por recortar a través [AssemblyMetadata("IsTrimmable", "True")] de (agregados en proyectos que establecieron <IsTrimmable>true</IsTrimmable>) de forma predeterminada. Puede volver al comportamiento anterior mediante <TrimMode>partial</TrimMode>.

Este valor recorta todos los ensamblados que se hayan configurado para el recorte. Con Microsoft.NET.Sdk en .NET 6, se incluyen los ensamblados con [AssemblyMetadata("IsTrimmable", "True")], como sucede con los ensamblados de entorno de ejecución .NET. En .NET 5, los ensamblados del paquete en tiempo de ejecución netcoreapp se configuran para el recorte mediante los metadatos <IsTrimmable> de MSBuild. Otros SDK pueden definir valores predeterminados diferentes.

Este valor también habilita el analizador Roslyn de compatibilidad con el recorte y deshabilita las características que no son compatibles con el recorte.

Granularidad del recorte

Use la propiedad TrimMode para establecer la granularidad de recorte en partial o full. La configuración predeterminada para las aplicaciones de consola (y, a partir de .NET 8, aplicaciones del SDK web) es full:

<TrimMode>full</TrimMode>

Para recortar solo los ensamblados que han optado por el recorte, establezca la propiedad en partial:

<TrimMode>partial</TrimMode>

Si cambia el modo de recorte a partial, puede participar en ensamblados individuales para recortar mediante un elemento de MSBuild <TrimmableAssembly>.

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

Esto equivale a establecer [AssemblyMetadata("IsTrimmable", "True")] al compilar el ensamblado.

La siguiente configuración de granularidad controla la agresividad con la que se descarta el IL sin usar. Esto se puede establecer como una propiedad que afecta a todos los ensamblados de entrada del recortador, o bien como metadatos en un ensamblado individual, lo que invalida el establecimiento de la propiedad.

  • <TrimMode>link</TrimMode>

    Habilite el recorte a nivel de miembro, lo que quita los miembros sin usar de los tipos. Este es el valor predeterminado en .NET 6+.

  • <TrimMode>copyused</TrimMode>

    Habilita el recorte en el nivel de ensamblado, lo que mantendrá un ensamblado completo si se usa cualquier parte de este (de manera estática).

Los ensamblados con metadatos de <IsTrimmable>true</IsTrimmable>, pero sin un valor de TrimMode explícito, usarán el valor global de TrimMode. El valor TrimMode predeterminado de Microsoft.NET.Sdk es link en .NET 6+, y copyused en versiones anteriores.

Recorte de ensamblados adicionales

En .NET 6 y versiones posteriores, PublishTrimmed recorta los ensamblados con el atributo de nivel de ensamblado siguiente:

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

Las bibliotecas de marco tienen este atributo. En .NET 6+, también puede optar por recortar una biblioteca sin este atributo, si especifica el ensamblado por nombre (sin la extensión .dll).

Configuración de recorte de ensamblados individuales

Al publicar una aplicación recortada, el SDK calcula un elemento ItemGroup llamado ManagedAssemblyToLink que representa el conjunto de archivos que se va a procesar para el recorte. ManagedAssemblyToLink puede tener metadatos que controlan el comportamiento de recorte por ensamblado. Para establecer estos metadatos, cree un destino que se ejecute antes del destino PrepareForILLink integrado. En el ejemplo siguiente se muestra cómo habilitar el recorte de MyAssembly.

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

También puede usar este destino para invalidar el comportamiento de recorte especificado por el autor de la biblioteca estableciendo <IsTrimmable>false</IsTrimmable> para un ensamblado con [AssemblyMetadata("IsTrimmable", "True"]).

No agregue ni quite elementos de ManagedAssemblyToLink, ya que el SDK calcula este conjunto durante la publicación y espera que no cambie. Los metadatos admitidos son:

  • <IsTrimmable>true</IsTrimmable>

    Controle si se ha recortado el ensamblado especificado.

  • <TrimMode>copyused</TrimMode> o <TrimMode>link</TrimMode>

    Controle la granularidad del recorte de este ensamblado. Estos metadatos tienen prioridad sobre el global TrimMode. La configuración del valor TrimMode en un ensamblado implica <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Controle si se muestran advertencias únicas para este ensamblado.

Ensamblados raíz

Si no se recorta un ensamblado, se considera "root", lo que significa que se conservarán todas sus dependencias comprendidas estáticamente. Los ensamblados adicionales pueden ser "rooteados" por nombre (sin la .dll extensión):

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

Descriptores raíz

Otra manera de especificar las raíces para el análisis consiste en usar un archivo XML que use el formato de descriptor del recortador. Esto le permite enraizar miembros específicos en lugar de un ensamblado completo.

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

Por ejemplo, MyRoots.xml puede raízr un método específico al que accede dinámicamente la aplicación:

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

Advertencias de análisis

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Habilite las advertencias de análisis de recorte.

El recorte quita il que no es accesible estáticamente. Las aplicaciones que usan reflexión u otros patrones que crean dependencias dinámicas pueden romperse mediante el recorte. Para advertir sobre tales patrones, configure <SuppressTrimAnalysisWarnings> en false. Esta configuración mostrará advertencias sobre toda la aplicación, incluido su propio código, código de biblioteca y código de marco.

Analizador de Roslyn

Al establecer PublishTrimmed en .NET 6+ también se habilita un analizador de Roslyn que muestra un conjunto limitado de advertencias de análisis. También puede habilitar o deshabilitar el analizador independientemente de PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Habilite un analizador de Roslyn para un subconjunto de advertencias de análisis de recorte.

Suprimir advertencias

Puede suprimir los códigos de advertencia individuales mediante las propiedades de MSBuild habituales que respeta la cadena de herramientas, incluidas NoWarn, WarningsAsErrors, WarningsNotAsErrors y TreatWarningsAsErrors. Hay una opción adicional que controla el comportamiento de advertencia como error de ILLink de forma independiente:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    No trate las advertencias de ILLink como errores. Esto puede ser útil para evitar convertir advertencias de análisis de recorte en errores al tratar las advertencias del compilador como errores globalmente.

Representación de advertencias detalladas

En .NET 6+, el análisis de recorte genera como máximo una advertencia para cada ensamblado que procede de un objeto PackageReference, lo que indica que los aspectos internos del ensamblado no son compatibles con el recorte. También puede mostrar advertencias individuales para todos los ensamblados:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Se muestran todas las advertencias detalladas, en lugar de contraerlas en una única advertencia por ensamblado.

Eliminación de símbolos

Normalmente, los símbolos se recortan para que coincidan con los ensamblados recortados. También puede quitar todos los símbolos:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Quite los símbolos de la aplicación recortada, incluidos los archivos PDB incrustados y los archivos PDB independientes. Esto se aplica tanto al código de la aplicación como a las dependencias de los símbolos.

El SDK también permite deshabilitar la compatibilidad del depurador con la propiedad DebuggerSupport. Cuando la compatibilidad con el depurador está deshabilitada, el recorte quita automáticamente los símbolos (TrimmerRemoveSymbols el valor predeterminado es true).

Recorte de las características de la biblioteca de marcos

Varias áreas de características de las bibliotecas de marco incluyen directivas de recortador que permiten eliminar el código de las características deshabilitadas.

Propiedad de MSBuild Descripción
AutoreleasePoolSupport Cuando se establece falseen , quita el código que crea grupos autorelease en plataformas admitidas. false es el valor predeterminado para el SDK de .NET.
DebuggerSupport Cuando se establece en false, quita el código que permite mejorar las experiencias de depuración. Esta configuración también quita símbolos.
EnableUnsafeBinaryFormatterSerialization Cuando se establece en false, quita la compatibilidad con la serialización BinaryFormatter. Para obtener más información, vea Los métodos de serialización BinaryFormatter están obsoletos y la implementación de BinaryFormatter integrada se ha quitado y siempre se produce.
EnableUnsafeUTF7Encoding Cuando se establece falseen , quita el código de codificación UTF-7 no seguro. Para obtener más información, vea la sección Rutas de acceso al código UTF-7 obsoletas.
EventSourceSupport Cuando se establece en false, quita el código y la lógica relacionados con EventSource.
HttpActivityPropagationSupport Cuando se establece en false, quita el código relacionado con la compatibilidad de diagnósticos con System.Net.Http.
InvariantGlobalization Cuando se establece en true, quita el código y los datos específicos de la globalización. Para obtener más información, consulte Modo invariable.
MetadataUpdaterSupport Cuando se establece en false, quita la lógica específica de actualización de metadatos relacionada con la recarga activa.
MetricsSupport Cuando se establece en false, quita la compatibilidad con System.Diagnostics.Metrics la instrumentación.
StackTraceSupport (.NET 8+) Cuando se establece falseen , quita la compatibilidad con la generación de seguimientos de pila (por ejemplo, Environment.StackTrace o Exception.ToString) por el tiempo de ejecución. La cantidad de información que se quita de las cadenas de seguimiento de pila puede depender de otras opciones de implementación. Esta opción no afecta a los seguimientos de pila generados por los depuradores.
UseNativeHttpHandler Cuando se establece trueen , usa la implementación de plataforma predeterminada de HttpMessageHandler para Android e iOS y quita la implementación administrada.
UseSystemResourceKeys Cuando se establece en true, quita los mensajes de excepción para System.* los ensamblados. Cuando se produce una excepción desde un System.* ensamblado, el mensaje es un identificador de recurso simplificado en lugar del mensaje completo.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) Cuando se establece falseen , quita la compatibilidad para resolver direcciones URL que no son de archivo en System.Xml. Solo se admite la resolución del sistema de archivos.

Estas propiedades hacen que el código relacionado se recorte y también deshabilitan las características a través del archivo runtimeconfig. Para obtener más información sobre estas propiedades, incluidas las opciones de runtimeconfig correspondientes, vea modificadores de características. Algunos SDK pueden tener valores predeterminados para estas propiedades.

Características del marco deshabilitadas al recortar

Las siguientes características no son compatibles con el recorte porque requieren código al que no se hace referencia estáticamente. Estas características están deshabilitadas de forma predeterminada en aplicaciones recortadas.

Advertencia

Habilite estas características por su cuenta y riesgo. Es probable que se interrumpan las aplicaciones recortadas sin trabajo adicional para conservar el código al que se hace referencia de forma dinámica.

  • <BuiltInComInteropSupport>

    La compatibilidad integrada con COM está deshabilitada.

  • <CustomResourceTypesSupport>

    No se admite el uso de tipos de recursos personalizados. Las rutas de acceso de código de ResourceManager que usan la reflexión para los tipos de recursos personalizados se recortan.

  • <EnableCppCLIHostActivation>

    La activación del host de C++/CLI está deshabilitada.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    Se ha deshabilitado el uso de la serialización BinaryFormatter en DesigntimeLicenseContextSerializer.

  • <StartupHookSupport>

    No se admite la ejecución de código antes Main de con DOTNET_STARTUP_HOOKS . Para obtener más información, vea Hospedaje del enlace de inicio.