Options du compilateur C# avancées

Article
07/24/2023

Les options suivantes prennent en charge les scénarios avancés. La nouvelle syntaxe MSBuild est affichée en gras. L’ancienne syntaxe csc.exe s’affiche dans code style.

MainEntryPoint, StartupObject / -main : spécifiez le type qui contient le point d’entrée.
PdbFile / -pdb : spécifiez le nom du fichier d’informations de débogage.
PathMap / -pathmap : spécifiez un mappage pour la sortie de noms de chemin d’accès source par le compilateur.
ApplicationConfiguration / -appconfig : spécifiez un fichier de configuration d'application contenant des paramètres de liaison d'assembly.
AdditionalLibPaths / -lib : spécifiez des répertoires supplémentaires dans lesquels rechercher les références.
GenerateFullPaths / -fullpath : le compilateur génère des chemins d’accès complets.
PreferredUILang / -preferreduilang : spécifiez le nom de la langue de sortie préférée.
BaseAddress / -baseaddress : spécifiez l'adresse de base de la bibliothèque à générer.
ChecksumAlgorithm / -checksumalgorithm : spécifiez l'algorithme de calcul de la somme de contrôle du fichier source stockée dans le fichier PDB.
CodePage / -codepage : spécifiez la page de codes à utiliser à l'ouverture des fichiers sources.
Utf8Output / -utf8output : messages du compilateur de sortie encodés en UTF-8.
FileAlignment / -filealign : spécifier l'alignement utilisé pour les sections du fichier de sortie.
ErrorEndLocation / -errorendlocation : ligne et colonne de sortie de l'emplacement de fin de chaque erreur.
NoStandardLib / -nostdlib : ne référencez pas la bibliothèque standard mscorlib.dll.
SubsystemVersion / -subsystemversion : spécifiez la version du sous-système de cet assembly.
ModuleAssemblyName / -moduleassemblyname : Nom de l’assembly dont ce module doit faire partie.
ReportIVTs / -reportivts : produire des informations supplémentaires sur System.Runtime.CompilerServices.InternalsVisibleToAttribute les informations.

Vous ajoutez l’une de ces options dans un <PropertyGroup> élément de votre *.csproj fichier :

<PropertyGroup>
    <StartupObject>...</StartupObject>
    ...
</PropertyGroup>

MainEntryPoint ou StartupObject

Cette option spécifie la classe qui contient le point d’entrée du programme dans le cas où plusieurs classes contiennent une méthode Main.

<StartupObject>MyNamespace.Program</StartupObject>

<MainEntryPoint>MyNamespace.Program</MainEntryPoint>

Où Program est le type qui contient la méthode Main. Le nom de classe fourni doit être complet, c’est-à-dire qu’il doit inclure l’espace de noms complet contenant la classe, suivi du nom de classe. Par exemple, si la méthode Main se trouve dans la classe Program dans l’espace de noms MyApplication.Core, l’option du compilateur doit être -main:MyApplication.Core.Program. Si votre compilation inclut plusieurs types avec une méthode Main, vous pouvez spécifier le type qui contient la méthode Main.

Notes

Cette option ne peut pas être utilisée pour un projet qui inclut des instructions de niveau supérieur, même si ce projet contient une ou plusieurs méthodes Main.

PdbFile

L’option de compilateur PdbFile spécifie le nom et l’emplacement du fichier de symboles de débogage. La valeur filename spécifie le nom et l’emplacement du fichier de symboles de débogage.

<PdbFile>filename</PdbFile>

Lorsque vous spécifiez DebugType, le compilateur crée un fichier .pdb dans le même répertoire dans lequel il crée le fichier de sortie (.exe ou .dll). Le fichier .pdb a le même nom de fichier de base que le nom du fichier de sortie. PdbFile vous permet de spécifier un nom de fichier et un emplacement personnalisés pour le fichier .pdb. Cette option du compilateur ne peut pas être définie dans l’environnement de développement Visual Studio, ni modifiée par programme.

PathMap

Remarque

La spécification de PathMap empêche les points d’arrêt de fonctionner dans les builds de débogage locales. Définissez PathMap seulement pour la production ou pour les builds d’intégration continue.

L’option de compilateur PathMap spécifie comment mapper des chemins physiques aux noms de chemin source générés en sortie par le compilateur. Cette option mappe chaque chemin physique de l’ordinateur sur lequel le compilateur s’exécute à un chemin correspondant qui doit être écrit dans les fichiers de sortie. Dans l’exemple suivant, path1 est le chemin d’accès complet aux fichiers sources dans l’environnement actuel et sourcePath1 est le chemin d’accès source remplacé par path1 dans tous les fichiers de sortie. Pour spécifier plusieurs chemins sources mappés, séparez-les par des virgules.

<PathMap>path1=sourcePath1,path2=sourcePath2</PathMap>

Le compilateur écrit le chemin source dans sa sortie dans les cas suivants :

Le chemin source est remplacé par un argument quand CallerFilePathAttribute est appliqué à un paramètre facultatif.
Le chemin source est incorporé dans un fichier PDB.
Le chemin du fichier PDB est incorporé dans un fichier exécutable portable (PE).

ApplicationConfiguration

L’option du compilateur ApplicationConfiguration permet à une application C# d’indiquer l’emplacement du fichier de configuration de l’application (app.config) d’un assembly au CLR (Common Language Runtime) au moment de la liaison de l’assembly.

<ApplicationConfiguration>file</ApplicationConfiguration>

Où file est le fichier de configuration de l’application qui contient des paramètres de liaison de l’assembly. ApplicationConfiguration est notamment utilisé dans des scénarios avancés dans lesquels un assembly doit simultanément référencer à la fois la version du .NET Framework et la version du .NET Framework pour Silverlight d’un assembly de référence particulier. Par exemple, un concepteur XAML écrit dans WPF (Windows Presentation Foundation) devra peut-être référencer à la fois le bureau WPF pour l’interface utilisateur du concepteur et le sous-ensemble de WPF qui est fourni avec Silverlight. Le même assembly de concepteur doit accéder aux deux assemblys. Par défaut, les références séparées provoquent une erreur du compilateur parce que la liaison d’assembly considère les deux assemblys comme équivalents. L’option du compilateur ApplicationConfiguration vous permet de spécifier l’emplacement d’un fichier app.config qui désactive le comportement par défaut à l’aide d’une balise <supportPortability>, comme indiqué dans l’exemple suivant.

<supportPortability PKT="7cec85d7bea7798e" enable="false"/>

Le compilateur passe l’emplacement du fichier à la logique de liaison d’assembly du CLR.

Notes

Pour utiliser le fichier app.config qui est déjà défini dans le projet, ajoutez la balise de propriété <UseAppConfigForCompiler> au fichier .csproj et affectez-lui la valeur true. Pour spécifier un autre fichier app.config, ajoutez la balise de propriété <AppConfigForCompiler> et définissez sa valeur sur l’emplacement du fichier.

L’exemple suivant affiche un fichier app.config qui permet à une application d’avoir des références à la fois à l’implémentation .NET Framework et à l’implémentation .NET Framework pour Silverlight de tout assembly .NET Framework qui existe dans les deux implémentations. L’option du compilateur ApplicationConfiguration spécifie l’emplacement de ce fichier app.config.

<configuration>
  <runtime>
    <assemblyBinding>
      <supportPortability PKT="7cec85d7bea7798e" enable="false"/>
      <supportPortability PKT="31bf3856ad364e35" enable="false"/>
    </assemblyBinding>
  </runtime>
</configuration>

AdditionalLibPaths

L’option AdditionalLibPaths spécifie l’emplacement des assemblys référencés avec l’option Références.

<AdditionalLibPaths>dir1[,dir2]</AdditionalLibPaths>

Où dir1 est un répertoire dans lequel le compilateur doit effectuer la recherche si un assembly référencé ne se trouve pas dans le répertoire de travail actuel (le répertoire à partir duquel vous appelez le compilateur) ou dans le répertoire système du common language runtime. dir2 est un ou plusieurs répertoires supplémentaires où rechercher des références d’assembly. Séparez les noms des répertoires par une virgule, sans espace. Le compilateur recherche les références d’assembly qui ne sont pas complètes dans l’ordre suivant :

Répertoire de travail actuel.
Répertoire système du common language runtime.
Répertoires spécifiés par AdditionalLibPaths.
Répertoires spécifiés par la variable d’environnement LIB.

Utilisez Reference pour spécifier une référence d’assembly. AdditionalLibPaths est additif. Si vous le spécifiez plusieurs fois, il effectue un ajout aux valeurs précédentes. Comme le chemin de l’assembly dépendant n’est pas spécifié dans le manifeste de l’assembly, l’application recherche et utilise l’assembly dans le Global Assembly Cache. Le compilateur référençant l’assembly n’implique pas que le Common Language Runtime puisse chercher et charger l’assembly au moment de l’exécution. Consultez Méthode de localisation des assemblys par le runtime pour plus d’informations sur la façon dont le runtime recherche des assemblys référencés.

GenerateFullPaths

Si vous utilisez l’option GenerateFullPaths, le compilateur spécifie le chemin complet du fichier quand il répertorie les erreurs de compilation et les avertissements.

<GenerateFullPaths>true</GenerateFullPaths>

Par défaut, les erreurs et les avertissements générés par la compilation spécifient le nom du fichier dans lequel une erreur a été trouvée. Si vous utilisez l’option GenerateFullPaths, le compilateur spécifie le chemin complet du fichier. Cette option du compilateur n'est pas disponible dans Visual Studio et ne peut pas être modifiée par programme.

PreferredUILang

L’option de compilateur PreferredUILang vous permet de spécifier la langue dans laquelle le compilateur C# affiche la sortie, comme les messages d’erreur.

<PreferredUILang>language</PreferredUILang>

Où languageest le nom de la langue à utiliser pour la sortie du compilateur. Vous pouvez utiliser l’option de compilateur PreferredUILang pour spécifier la langue que le compilateur C# doit utiliser pour les messages d’erreur et d’autres types de sortie de ligne de commande. Si le module linguistique de la langue n’est pas installé, le paramètre de langue du système d’exploitation est utilisé.

BaseAddress

L’option BaseAddress vous permet de spécifier l’adresse de base préférée à laquelle doit être chargée une DLL. Pour plus d’informations sur le moment et la raison de l’utilisation de cette option, consultez Larry Osterman’s WebLog.

<BaseAddress>address</BaseAddress>

Où address est l’adresse de base de la DLL. Cette adresse peut être spécifiée sous forme d’un nombre décimal, hexadécimal ou octal. L’adresse de base par défaut d’une DLL est définie par le common language runtime .NET. Le dernier chiffre de cette adresse sera arrondi. Par exemple, si vous spécifiez 0x11110001, il est arrondi à 0x11110000. Pour terminer le processus de signature d’une DLL, utilisez SN.EXE avec l’option -R.

ChecksumAlgorithm

Cette option contrôle l’algorithme checksum que nous utilisons pour encoder les fichiers sources dans le fichier PDB.

<ChecksumAlgorithm>algorithm</ChecksumAlgorithm>

algorithm doit être SHA1 (par défaut) ou SHA256.

CodePage

Cette option spécifie la page de codes à utiliser pendant la compilation si la page exigée n’est pas la page de codes par défaut actuelle du système.

<CodePage>id</CodePage>

Où id est l'ID de la page de codes à utiliser pour tous les fichiers de code source de la compilation. Le compilateur tente d'abord d'interpréter tous les fichiers sources au format UTF-8. Si vos fichiers de code source sont encodés dans un format autre que UTF-8 et s’ils utilisent des caractères autres que des caractères ASCII 7 bits, utilisez l’option CodePage pour spécifier la page de codes à utiliser. CodePage s’applique à tous les fichiers de code source inclus dans votre compilation. Pour plus d’informations sur la façon de savoir quelles pages de codes sont prises en charge sur votre système, consultez GetCPInfo.

Utf8Output

L’option Utf8Output affiche la sortie du compilateur en utilisant un encodage UTF-8.

<Utf8Output>true</Utf8Output>

Dans certaines configurations internationales, la sortie du compilateur ne peut pas être affichée correctement dans la console. Utilisez Utf8Output et redirigez la sortie du compilateur vers un fichier.

FileAlignment

L’option FileAlignment permet de spécifier la taille des sections de votre fichier de sortie. Les valeurs valides sont 512, 1024, 2048, 4096 et 8192. Ces valeurs sont exprimées en octets.

<FileAlignment>number</FileAlignment>

Vous définissez l’option FileAlignment à partir de la page Avancé des propriétés Build de votre projet dans Visual Studio. Chaque section est alignée sur une limite qui est un multiple de la valeur FileAlignment. Il n’existe aucune valeur fixe par défaut. Si la valeur FileAlignment n’est pas spécifiée, le Common Language Runtime choisit une valeur par défaut au moment de la compilation. En spécifiant la taille de la section, vous affectez la taille du fichier de sortie. La modification de la taille des sections peut être utile pour les programmes exécutés sur des appareils plus petits. Utilisez DUMPBIN pour afficher des informations sur les sections de votre fichier de sortie.

ErrorEndLocation

Indique au compilateur de sortir la ligne et la colonne de l’emplacement de fin de chaque erreur.

<ErrorEndLocation>true</ErrorEndLocation>

Par défaut, le compilateur écrit l’emplacement de départ dans la source pour toutes les erreurs et tous les avertissements. Lorsque cette option est définie sur true, le compilateur écrit à la fois l’emplacement de début et de fin pour chaque erreur et chaque avertissement.

NoStandardLib

NoStandardLib empêche l’importation du fichier mscorlib.dll, qui définit l’espace de noms System tout entier.

<NoStandardLib>true</NoStandardLib>

Utilisez cette option si vous souhaitez définir ou créer vos propres objets et espace de noms System. Si vous ne spécifiez pas NoStandardLib, mscorlib.dll est importé dans votre programme (ce qui équivaut à spécifier <NoStandardLib>false</NoStandardLib>).

SubsystemVersion

Spécifie la version minimale du sous-système sur lequel le fichier exécutable s’exécute. En règle générale, cette option garantit que le fichier exécutable peut utiliser des fonctionnalités de sécurité particulières qui ne sont pas disponibles avec des versions antérieures de Windows.

Notes

Pour spécifier le sous-système lui-même, utilisez l’option du compilateur TargetType.

<SubsystemVersion>major.minor</SubsystemVersion>

major.minor spécifie la version minimale requise du sous-système, telle qu’elle est exprimée dans une notation par points pour les versions majeure et mineure. Par exemple, vous pouvez spécifier qu’une application ne peut pas s’exécuter sur un système d’exploitation antérieur à Windows 7. Définissez la valeur de cette option sur 6.01, comme décrit plus loi dans le tableau de cet article. Spécifiez les valeurs pour major et minor en tant qu’entiers. Les zéros à gauche du numéro de version minor ne modifient pas la version, contrairement aux zéros de droite. Par exemple, 6.1 et 6.01 font référence à la même version, mais 6.10 fait référence à une version différente. Nous vous recommandons d’exprimer la version mineure avec deux chiffres pour éviter toute confusion.

Le tableau suivant répertorie les versions courantes de sous-système de Windows.

Version de Windows	Version de sous-système
Windows Server 2003	5.02
Windows Vista	6,00
Windows 7	6.01
Windows Server 2008	6.01
Windows 8	6.02

La valeur par défaut de l’option du compilateur SubsystemVersion dépend des conditions répertoriées dans la liste suivante :

La valeur par défaut est 6.02 si l’une quelconque des options du compilateur de la liste suivante est définie :
La valeur par défaut est 6.00 si vous utilisez MSBuild, si vous ciblez .NET Framework 4.5 et si vous n’avez défini aucune des options du compilateur spécifiées plus haut dans cette liste.
La valeur par défaut est 4.00 si aucune des conditions précédentes n’est vraie.

ModuleAssemblyName

Spécifie le nom d’un assembly dont un .netmodule peut accéder aux types non publics.

<ModuleAssemblyName>assembly_name</ModuleAssemblyName>

ModuleAssemblyName doit être utilisée au moment de créer un fichier .netmoduleet quand les conditions suivantes sont réunies :

Le .netmodule doit accéder aux types non publics dans un assembly existant.
Vous connaissez le nom de l’assembly dans lequel le fichier .netmodule sera généré.
L’assembly existant a accordé un accès d’assembly friend à l’assembly dans lequel le fichier netmodule sera généré.

Pour plus d’informations sur la création d’un fichier .netmodule, consultez l’option du moduleTargetType. Pour plus d’informations sur les assemblys friend, consultez Assemblys friend.

ReportIVTs

Activez ou désactivez les informations de diagnostic supplémentaires trouvées System.Runtime.CompilerServices.InternalsVisibleToAttribute pendant la compilation :

<ReportIVTs>true</ReportIVTs>

Les diagnostics sont activés si le contenu de l’élément est true, désactivé si false, ou non présent.

ReportIVTs signale les informations suivantes lorsqu’il est activé :

Tout membre inaccessible diagnostics inclure son assembly source, s’il est différent de l’assembly actuel.
Le compilateur imprime l’identité d’assembly du projet en cours de compilation, son nom d’assembly et sa clé publique.
Pour chaque référence passée au compilateur, elle s’imprime ;
1. Identité d’assembly de la référence
2. Si la référence accorde le projet actuel InternalsVisibleTo
3. Nom et toutes les clés publiques de tous les assemblys accordés InternalsVisibleTo à partir de cet assembly

Options du compilateur C# avancées

MainEntryPoint ou StartupObject

PdbFile

PathMap

ApplicationConfiguration

AdditionalLibPaths

GenerateFullPaths

PreferredUILang

BaseAddress

ChecksumAlgorithm

CodePage

Utf8Output

FileAlignment

ErrorEndLocation

NoStandardLib

SubsystemVersion

ModuleAssemblyName

ReportIVTs

Commentaires

Ressources supplémentaires