Options de découpage

  • Article

Les propriétés et éléments MSBuild suivants influencent le comportement des déploiements autonomes découpés. Certaines options mentionnent ILLink, qui est le nom de l’outil sous-jacent qui implémente le découpage. Pour plus d’informations sur l’outil sous-jacent, consultez la documentation sur le découpage.

Le découpage avec PublishTrimmed a été introduit dans .NET Core 3.0. Les autres options sont disponibles uniquement dans .NET 5 et versions ultérieures.

Activer le découpage

  • <PublishTrimmed>true</PublishTrimmed>

    Activez le découpage pendant la publication. Cela désactive également les fonctionnalités incompatibles avec le découpage et active l’analyse de découpage pendant la génération.

Notes

Si vous spécifiez le découpage comme activé à partir de la ligne de commande, votre expérience de débogage sera différente et vous risquez de rencontrer des bogues supplémentaires dans le produit final.

Placez ce paramètre dans le fichier projet pour vous assurer que le paramètre s’applique pendant dotnet build, et pas seulement dotnet publish.

Ce paramètre active le découpage et découpe tous les assemblies par défaut. Dans .NET 6, seuls les assemblies qui ont opté pour le découpage via [AssemblyMetadata("IsTrimmable", "True")] sont découpés par défaut. Vous pouvez revenir au comportement précédent à l’aide de <TrimMode>partial</TrimMode>.

Ce paramètre découpe tous les assemblies qui ont été configurés pour le découpage. Avec Microsoft.NET.Sdk dans .NET 6, cela inclut tous les assemblies avec [AssemblyMetadata("IsTrimmable", "True")], ce qui est le cas pour les assemblies runtime .NET. Dans .NET 5, les assemblies du pack runtime netcoreapp sont configurés pour le découpage via les métadonnées MSBuild <IsTrimmable>. D’autres Kits de développement logiciel (SDK) peuvent définir des valeurs par défaut différentes.

Ce paramètre active également l’analyseur Roslyn compatible avec le découpage et désactive les fonctionnalités incompatibles avec le découpage.

Granularité de découpage

Utilisez la propriété TrimMode pour définir la granularité de découpage sur partial ou full. Le paramètre par défaut pour les applications de console (et, à partir de .NET 8, les applications du SDK web) est full :

<TrimMode>full</TrimMode>

Pour découper uniquement les assemblies qui ont choisi le découpage, définissez la propriété sur partial :

<TrimMode>partial</TrimMode>

Si vous remplacez le mode de découpage par partial, vous pouvez choisir des assemblies individuels pour le découpage à l’aide d’un élément MSBuild <TrimmableAssembly>.

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

Cela équivaut à définir [AssemblyMetadata("IsTrimmable", "True")] lors de la génération de l’assembly.

Les paramètres de granularité suivants contrôlent la façon dont le langage intermédiaire inutilisé de manière agressive est ignoré. Ils peuvent être définis en tant que propriété affectant tous les assemblies d’entrée de découpage, ou en tant que métadonnées sur un assembly individuel, ce qui remplace le paramètre de propriété.

  • <TrimMode>link</TrimMode>

    Activez le découpage au niveau du membre, ce qui supprime les membres inutilisés des types. Ceci est la valeur par défaut dans .NET 6 et versions ultérieures.

  • <TrimMode>copyused</TrimMode>

    Activez le découpage au niveau de l’assembly, qui conserve un assembly entier si une partie de celui-ci est utilisée (de manière statique).

Les assemblies avec des métadonnées <IsTrimmable>true</IsTrimmable>, mais aucun élément explicite TrimMode, utilisent le TrimMode global. La valeur par défaut TrimMode de Microsoft.NET.Sdk est link dans .NET 6 et versions ultérieures, et copyused dans les versions précédentes.

Découper des assemblies supplémentaires

Dans .NET 6 et versions ultérieures, PublishTrimmed découpe les assemblies avec l’attribut au niveau de l’assembly suivant :

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

Les bibliothèques d’infrastructure ont cet attribut. Dans .NET 6 et versions ultérieures, vous pouvez également choisir le découpage d’une bibliothèque sans cet attribut, en spécifiant l’assembly par son nom (sans l’extension .dll).

Paramètres de découpage pour des assemblies individuels

Lors de la publication d’une application découpée, le Kit de développement logiciel (SDK) calcule un ItemGroup appelé ManagedAssemblyToLink qui représente l’ensemble des fichiers à traiter pour le découpage. ManagedAssemblyToLink peut avoir des métadonnées qui contrôlent le comportement de découpage par assembly. Pour définir ces métadonnées, créez une cible qui s’exécute avant la cible intégrée PrepareForILLink. L’exemple suivant montre comment activer le découpage de MyAssembly.

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

Vous pouvez également l’utiliser pour remplacer le comportement de découpage spécifié par l’auteur de la bibliothèque, en définissant <IsTrimmable>false</IsTrimmable> pour un assembly avec [AssemblyMetadata("IsTrimmable", "True"]).

N’ajoutez pas ou ne supprimez pas d’éléments vers/à partir de ManagedAssemblyToLink, car le Kit de développement logiciel (SDK) calcule cet ensemble lors de la publication et s’attend à ce qu’il ne change pas. Les métadonnées prises en charge sont les suivantes :

  • <IsTrimmable>true</IsTrimmable>

    Contrôlez si l’assembly donné est découpé.

  • <TrimMode>copyused</TrimMode> ou <TrimMode>link</TrimMode>

    Contrôlez la granularité de découpage de cet assembly. Cela est prioritaire sur le TrimMode global. La définition de TrimMode sur un assembly implique <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn> ou <TrimmerSingleWarn>False</TrimmerSingleWarn>

    Contrôlez s’il faut afficher des avertissements uniques pour cet assembly.

Assemblies racine

Si un assembly n’est pas découpé, il est considéré comme « enraciné », ce qui signifie qu’il et toutes ses dépendances comprises statiquement sont conservés. Les assemblies supplémentaires peuvent être « enracinés » par nom (sans l’extension .dll) :

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

Descripteurs racines

Une autre façon de spécifier des racines pour l’analyse consiste à utiliser un fichier XML qui utilise le format de descripteur de découpage. Cela vous permet d’enraciner des membres spécifiques au lieu d’un assembly entier.

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

Par exemple, MyRoots.xml peut enraciner une méthode spécifique accessible dynamiquement par l’application :

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

Avertissements liés à l’analyse

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Activez les avertissements d’analyse de découpage.

Le découpage supprime le langage intermédiaire qui n’est pas accessible de manière statique. Les applications qui utilisent la réflexion ou d’autres modèles qui créent des dépendances dynamiques peuvent être interrompues par le découpage. Pour déclencher un avertissement sur ces modèles, définissez <SuppressTrimAnalysisWarnings> sur false. Cela inclut des avertissements concernant l’ensemble de l’application, y compris votre propre code, le code de bibliothèque et le code d’infrastructure.

Analyseur Roslyn

La définition de PublishTrimmed dans .NET 6 et versions supérieures active également un analyseur Roslyn qui affiche un ensemble limité d’avertissements d’analyse. Vous pouvez également activer ou désactiver l’analyseur indépendamment de PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Activez un analyseur Roslyn pour un sous-ensemble d’avertissements d’analyse de découpage.

Supprimer les avertissements

Vous pouvez supprimer des codes d’avertissement individuels à l’aide des propriétés MSBuild habituelles respectées par la chaîne d’outils, notamment NoWarn, WarningsAsErrors, WarningsNotAsErrors et TreatWarningsAsErrors. Il existe une option supplémentaire qui contrôle le comportement d’avertissement en tant qu’erreur ILLink indépendamment :

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Ne traitez pas les avertissements ILLink comme des erreurs. Cela peut être utile pour éviter de transformer les avertissements d’analyse de découpage en erreurs lors du traitement des avertissements du compilateur comme des erreurs globalement.

Afficher les avertissements détaillés

Dans .NET 6 et versions ultérieures, l’analyse de découpage génère au maximum un avertissement pour chaque assembly qui provient d’un PackageReference, indiquant que les éléments internes de l’assembly ne sont pas compatibles avec le découpage. Vous pouvez également afficher des avertissements individuels pour tous les assemblies :

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Affichez tous les avertissements détaillés, au lieu de les réduire en un seul avertissement par assembly.

Supprimer des symboles

Les symboles sont généralement découpés pour correspondre aux assemblies découpés. Vous pouvez également supprimer tous les symboles :

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Supprimez les symboles de l’application découpée, y compris les fichiers PDB incorporés et les fichiers PDB distincts. Cela s’applique à la fois au code de l’application et aux dépendances fournies avec des symboles.

Le Kit de développement logiciel (SDK) permet également de désactiver la prise en charge du débogueur à l’aide de la propriété DebuggerSupport. Lorsque la prise en charge du débogueur est désactivée, la découpe supprime automatiquement les symboles (TrimmerRemoveSymbols a la valeur par défaut true).

Découpage des fonctionnalités de bibliothèque d’infrastructure

Plusieurs zones de fonctionnalités des bibliothèques d’infrastructure sont fournies avec des directives de découpage qui permettent de supprimer le code pour les fonctionnalités désactivées.

  • <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (valeur par défaut)

    Supprimez le code qui crée des pools de versions automatiques sur les plateformes prises en charge. Consultez AutoreleasePool pour les threads managés. Il s'agit de la valeur par défaut pour le Kit de développement logiciel (SDK) .NET.

  • <DebuggerSupport>false</DebuggerSupport>

    Supprimez le code qui permet de meilleures expériences de débogage. Ce paramètre supprime également les symboles.

  • <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

    Supprimez la prise en charge de la sérialisation BinaryFormatter. Pour plus d’informations, consultez Les méthodes de sérialisation BinaryFormatter sont obsolètes.

  • <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

    Supprimez le code d’encodage UTF-7 non sécurisé. Pour plus d’informations, consultez Les chemins du code UTF-7 sont obsolètes.

  • <EventSourceSupport>false</EventSourceSupport>

    Supprimez le code ou la logique liés à EventSource.

  • <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

    Supprimez le code lié à la prise en charge des diagnostics pour System.Net.Http.

  • <InvariantGlobalization>true</InvariantGlobalization>

    Supprimez le code et les données propres à la globalisation. Pour plus d’informations, consultez le mode indifférent.

  • <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

    Supprimez la logique spécifique à la mise à jour des métadonnées liée au rechargement à chaud.

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

    Supprimez la prise en charge de la génération de traces de pile (par exemple, Environment.StackTraceou Exception.ToString) par le runtime. La quantité d’informations qui seront supprimées des chaînes de trace de pile peut dépendre d’autres options de déploiement. Cette option n’affecte pas les traces de pile générées par les débogueurs.

  • <UseNativeHttpHandler>true</UseNativeHttpHandler>

    Utilisez l’implémentation de plateforme par défaut de HttpMessageHandler pour Android/iOS et supprimez l’implémentation managée.

  • <UseSystemResourceKeys>true</UseSystemResourceKeys>

    Supprimez les messages d’exception pour les assemblies System.*. Lorsqu’une exception est levée à partir d’un assembly System.*, le message est un ID de ressource simplifié au lieu du message complet.

Ces propriétés entraînent le découpage du code associé et la désactivation des fonctionnalités via le fichier runtimeconfig. Pour plus d’informations sur ces propriétés, y compris les options runtimeconfig correspondantes, consultez les commutateurs de fonctionnalités. Certains Kits de développement logiciel (SDK) peuvent avoir des valeurs par défaut pour ces propriétés.

Fonctionnalités de l’infrastructure désactivées lors du découpage

Les fonctionnalités suivantes sont incompatibles avec le découpage, car elles nécessitent du code qui n’est pas référencé de manière statique. Elles sont désactivées par défaut dans les applications découpées.

Avertissement

Activez ces fonctionnalités à vos propres risques. Elles sont susceptibles d’interrompre les applications découpées sans travail supplémentaire pour conserver le code référencé dynamiquement.

  • <BuiltInComInteropSupport>

    La prise en charge de COM intégrée est désactivée.

  • <CustomResourceTypesSupport>

    L’utilisation de types de ressources personnalisés n’est pas prise en charge. Les chemins du code ResourceManager qui utilisent la réflexion pour les types de ressources personnalisés sont découpés.

  • <EnableCppCLIHostActivation>

    L’hôte C++/CLI est désactivé.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializer l’utilisation de la sérialisation BinaryFormatter est désactivée.

  • <StartupHookSupport>

    L’exécution de code avant Main avec DOTNET_STARTUP_HOOKS n’est pas prise en charge. Pour plus d’informations, consultez crochet de démarrage de l’hôte.