Options du compilateur C# qui contrôlent la génération de code

  • Article

Les options suivantes contrôlent la génération du code par le compilateur. La nouvelle syntaxe MSBuild est affichée en gras. La syntaxe csc.exe plus ancienne est indiquée dans code style.

  • DebugType / -debug : émettre (ou ne pas émettre) des informations de débogage.
  • Optimize / -optimize : activer les optimisations.
  • Déterministic / -deterministic : produire une sortie équivalente octet pour octet à partir de la même source d’entrée.
  • ProduceOnlyReferenceAssembly / -refonly : produire un assembly de référence, au lieu d’un assembly complet, en tant que sortie principale.

Remarque

Reportez-vous à la section Options du compilateur pour plus d'informations sur la configuration de ces options pour votre projet.

DebugType

L’option DebugType fait en sorte que le compilateur génère des informations de débogage et les place dans les fichiers de sortie. Les informations de débogage sont ajoutées par défaut.

<DebugType>pdbonly</DebugType>

Pour toutes les versions du compilateur à partir de C# 6.0, il n’existe aucune différence entre pdbonly et full. Choisissez pdbonly. Pour modifier l’emplacement du fichier .pdb, consultez PdbFile.

Les valeurs suivantes sont valides :

Value Signification
full Émettez des informations de débogage dans le fichier .pdb à l’aide du format par défaut pour la plateforme actuelle :
Windows : un fichier pdb Windows.
Linux/macOS : un fichier PDB portable.
pdbonly Comme pour full. Pour plus d’informations, consultez la remarque ci-dessous.
portable Émettez des informations de débogage dans le fichier .pdb à l’aide du format PDB portable multiplateforme.
embedded Émettez des informations de débogage dans le .dll/.exe lui-même (le fichier .pdb n’est pas produit) à l’aide du format PDB portable.

Important

Les informations suivantes s’appliquent uniquement aux compilateurs antérieurs à C# 6.0. La valeur de cet élément peut être full ou pdbonly. L’argument full, qui est en vigueur si vous ne spécifiez pas pdbonly, permet d’attacher un débogueur pour le programme en cours d’exécution. Le fait de spécifier pdbonly active le débogage du code source quand le programme est démarré dans le débogueur, mais affiche uniquement un assembleur quand le programme en cours d’exécution est attaché au débogueur. Utilisez cette option pour créer des versions Debug. Si vous utilisez Full, sachez qu’il y a un impact sur la vitesse et la taille du code optimisé JIT, ainsi qu’un faible impact sur la qualité du code avec full. Nous vous recommandons d’utiliser pdbonly ou aucun PDB pour la génération du code de version finale. L’une des différences entre pdbonly et full est qu’avec full, le compilateur émet un DebuggableAttribute, qui est utilisé pour signaler au compilateur JIT que des informations de débogage sont disponibles. Ainsi, une erreur se produit si votre code contient un DebuggableAttribute avec la valeur false si vous utilisez full. Pour plus d’informations sur la façon de configurer les performances de débogage d’une application, consultez Simplification du débogage d’une image.

Optimiser

L’option Optimize active ou désactive les optimisations effectuées par le compilateur pour réduire la taille de votre fichier de sortie et le rendre plus rapide et plus efficace. L’option Optimize est activée par défaut pour une configuration de build Release. C’est désactivé par défaut pour une configuration Debug et toute autre configuration de construction.

<Optimize>true</Optimize>

Vous définissez l’option Optimize à partir de la page de propriétés Build pour votre projet dans Visual Studio.

Optimize indique aussi au Common Language Runtime d’optimiser le code au moment de l’exécution. Par défaut, les optimisations sont désactivées. Pour activer les optimisations, spécifiez Optimize+. Quand vous créez un module destiné à être utilisé par un assembly, utilisez les mêmes paramètres Optimize que ceux de l’assembly. Il est possible de combiner les options Optimize et Debug.

Déterministe

Indique au compilateur de générer un assembly dont la sortie octet-pour-octet est identique dans les compilations pour les entrées identiques.

<Deterministic>true</Deterministic>

Par défaut, la sortie du compilateur d’un ensemble donné d’entrées est unique, car le compilateur ajoute un timestamp et un MVID (un Module.ModuleVersionId. Fondamentalement, il s’agit d’un GUID qui identifie de manière unique le module et la version.) qui est généré à partir de nombres aléatoires. Utilisez l’option <Deterministic> pour générer un assembly déterministe, dont le contenu binaire sera identique dans les compilations tant que l’entrée restera la même. Dans une telle build, les champs timestamp et MVID sont remplacés par des valeurs dérivées d’un hachage de toutes les entrées de compilation. Le compilateur prend en compte les entrées suivantes qui affectent le déterminisme :

  • La séquence des paramètres de ligne de commande.
  • Le contenu du fichier réponse .rsp du compilateur.
  • La version précise du compilateur utilisée et ses assemblys référencés.
  • Le chemin de répertoire actif.
  • Le contenu binaire de tous les fichiers explicitement passés au compilateur directement ou indirectement, notamment :
    • Fichiers sources
    • Assemblys référencés
    • Modules référencés
    • Ressources
    • Fichier de clé de nom fort
    • Fichiers réponse @
    • Analyseurs
    • Ensembles de règles
    • Autres fichiers susceptibles d’être utilisés par les analyseurs
  • La culture actuelle (pour le langage dans lequel les diagnostics et les messages d’exception sont produits).
  • L’encodage par défaut (ou la page de codes active) si l’encodage n’est pas spécifié.
  • L’existence, la non-existence et le contenu des fichiers sur les chemins de recherche du compilateur (spécifiés, par exemple, par -lib ou -recurse).
  • Plateforme CLR (Common Language Runtime) sur laquelle le compilateur est exécuté.
  • La valeur de %LIBPATH%, qui peut affecter le chargement des dépendances de l’analyseur.

La compilation déterministe peut servir à établir si un fichier binaire est compilé à partir d’une source approuvée. La sortie déterministe peut être utile lorsque la source est disponible publiquement. Elle peut également déterminer si les étapes de génération dépendent des modifications apportées au fichier binaire utilisé dans le processus de génération.

ProduceOnlyReferenceAssembly

L’option ProduceOnlyReferenceAssembly indique qu’un assembly de référence doit être généré à la place d’un assembly d’implémentation, en tant que sortie principale. Le paramètre ProduceOnlyReferenceAssembly désactive sans assistance la génération de fichiers PDB, car les assemblys de référence ne peuvent pas être exécutés.

<ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>

Les assemblys de référence sont un type spécial d’assembly. Les assemblys de référence contiennent uniquement la quantité minimale de métadonnées requises pour représenter la surface d’API publique de la bibliothèque. Ils incluent des déclarations pour tous les membres qui sont significatifs lors du référencement d’un assembly dans les outils de génération, mais excluent toutes les implémentations de membres et déclarations de membres privés qui n’ont aucun impact observable sur leur contrat d’API. Pour plus d’informations, consultez Assemblys de référence.

Les options ProduceOnlyReferenceAssembly et ProduceReferenceAssembly s’excluent mutuellement.