Partager via

Options de découpage

  • Article

Les propriétés et éléments MSBuild décrits dans cet article influencent le comportement des déploiements autonomes et 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 dans .NET 5 et versions ultérieures.

Activer le découpage

  • <PublishTrimmed>true</PublishTrimmed>

    Activez le découpage pendant la publication. Ce paramètre désactive également les fonctionnalités incompatibles avec les découpages et active l’analyse de la suppression pendant la génération. Dans les applications .NET 8 et ultérieures, ce paramètre active également la liaison de configuration et demande des générateurs sources délégués.

Remarque

Si vous spécifiez le découpage comme activé à partir de la ligne de commande, votre expérience de débogage diffère 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 supprime tous les assemblys par défaut. Dans .NET 6, seuls les assemblys qui ont choisi de découper via [AssemblyMetadata("IsTrimmable", "True")] (ajoutés dans les projets qui définissent <IsTrimmable>true</IsTrimmable>) ont été supprimé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 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 utiliser cette cible 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 supprimez des éléments ManagedAssemblyToLink, car le Kit de développement logiciel (SDK) calcule ce jeu pendant 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. Ces métadonnées sont prioritaires sur le global TrimMode. La définition de TrimMode sur un assembly implique <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

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

Assemblies racine

Si un assembly n’est pas rogné, il est considéré comme « rooté », ce qui signifie que toutes ses dépendances comprises statiquement seront conservées. Les assemblys supplémentaires peuvent être « rooté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 raciner 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 l’il qui n’est pas accessible statiquement. Les applications qui utilisent la réflexion ou d’autres modèles qui créent des dépendances dynamiques peuvent être rompues en rognant. Pour déclencher un avertissement sur ces modèles, définissez <SuppressTrimAnalysisWarnings> sur false. Ce paramètre affiche des avertissements sur l’ensemble de l’application, y compris votre propre code, votre code de bibliothèque et le code framework.

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 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, le découpage supprime automatiquement les symboles (TrimmerRemoveSymbols la valeur par défaut est true).

Découper les fonctionnalités de la 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.

Propriété MSBuild Description
AutoreleasePoolSupport Lorsqu’il est défini falsesur , supprime le code qui crée des pools de réversion automatique sur les plateformes prises en charge. false est la valeur par défaut du Kit de développement logiciel (SDK) .NET.
DebuggerSupport Lorsqu’il est défini falsesur , supprime le code qui permet une meilleure expérience de débogage. Ce paramètre supprime également les symboles.
EnableUnsafeBinaryFormatterSerialization Lorsqu’il est défini sur false, supprime la prise en charge de la sérialisation BinaryFormatter. Pour plus d’informations, consultez les méthodes de sérialisation BinaryFormatter obsolètes et l’implémentation de BinaryFormatter in box a été supprimée et lève toujours.
EnableUnsafeUTF7Encoding Lorsqu’il est défini falsesur , supprime le code d’encodage UTF-7 non sécurisé. Pour plus d’informations, consultez Les chemins du code UTF-7 sont obsolètes.
EventSourceSupport Lorsqu’il falseest défini sur , supprime le code et la logique liés à EventSource.
HttpActivityPropagationSupport Lorsqu’il falseest défini sur , supprime le code lié à la prise en charge des diagnostics pour System.Net.Http.
InvariantGlobalization Lorsqu’il est défini truesur , supprime le code et les données spécifiques à la mondialisation. Pour plus d’informations, consultez Mode invariant.
MetadataUpdaterSupport Lorsque la valeur est définie false, supprime la logique spécifique à la mise à jour des métadonnées liée au rechargement à chaud.
MetricsSupport Lorsque la valeur est définie false, supprime la prise en charge de l’instrumentation System.Diagnostics.Metrics .
StackTraceSupport (.NET 8+) Lorsque la valeur est définie false, supprime la prise en charge de la génération de traces de pile (par exemple, Environment.StackTrace ou Exception.ToString) par le runtime. La quantité d’informations 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 Lorsqu’il est défini truesur , utilise l’implémentation de plateforme par défaut pour HttpMessageHandler Android et iOS et supprime l’implémentation managée.
UseSystemResourceKeys Lorsqu’il trueest défini sur , supprime les messages d’exception pour System.* les assemblys. Lorsqu’une exception est levée à partir d’un System.* assembly, le message est un ID de ressource simplifié au lieu du message complet.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) Lorsque la valeur est définie false, supprime la prise en charge de la résolution des URL autres que des fichiers dans System.Xml. Seule la résolution du système de fichiers est prise en charge.

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 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 ne sont pas compatibles avec le découpage, car elles nécessitent du code qui n’est pas référencé statiquement. Ces fonctionnalités sont désactivées par défaut dans les applications réduites.

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 de code ResourceManager qui utilisent la réflexion pour les types de ressources personnalisés sont supprimé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 du code avant Main DOTNET_STARTUP_HOOKS n’est pas prise en charge. Pour plus d’informations, consultez crochet de démarrage de l’hôte.