Référence MSBuild pour les projets du SDK .NET

  • Article

Cette page est une référence pour les propriétés et les éléments MSBuild que vous pouvez utiliser pour configurer des projets .NET.

Notes

Cette page est en cours d’élaboration et ne répertorie pas toutes les propriétés MSBuild utiles pour le kit SDK .NET. Pour obtenir la liste des propriétés MSBuild courantes, consultez Propriétés MSBuild courantes.

Propriétés de framework

Les propriétés MSBuild suivantes sont documentées dans cette section :

TargetFramework

La propriété TargetFramework spécifie la version du framework cible pour l’application. Pour obtenir la liste des monikers de framework cible valides, consultez Frameworks cibles dans les projets de style SDK.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

Pour plus d’informations, consultez Frameworks cibles dans les projets de style SDK.

TargetFrameworks

Utilisez la propriété TargetFrameworks quand vous souhaitez que votre application cible plusieurs plateformes. Pour obtenir la liste des monikers de framework cible valides, consultez Frameworks cibles dans les projets de style SDK.

Notes

Cette propriété est ignorée si TargetFramework (singulier) est spécifié.

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

Pour plus d’informations, consultez Frameworks cibles dans les projets de style SDK.

NetStandardImplicitPackageVersion

Notes

Cette propriété s’applique uniquement aux projets qui utilisent netstandard1.x. Elle ne s’applique pas aux projets qui utilisent netstandard2.x.

Utilisez la propriété NetStandardImplicitPackageVersion quand vous souhaitez spécifier une version de framework inférieure à la version du métapaquet. Le fichier projet de l’exemple suivant cible netstandard1.3, mais utilise la version 1.6.0 de NETStandard.Library.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Propriétés d’attribut d’assembly

GenerateAssemblyInfo

La propriété GenerateAssemblyInfo contrôle la génération d’attributs AssemblyInfo pour le projet. La valeur par défaut est true. Utilisez false pour désactiver la génération du fichier :

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Le paramètre GeneratedAssemblyInfoFile contrôle le nom du fichier généré.

Quand la valeur GenerateAssemblyInfo est true, les propriétés de projet liées aux packages sont transformées en attributs d’assembly. Le tableau suivant répertorie les propriétés de projet qui génèrent les attributs. Il répertorie également les propriétés que vous pouvez utiliser pour désactiver cette génération par attribut, telles que :

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Propriété MSBuild Attribut d’assembly Propriété pour désactiver la génération d’attributs
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Remarques sur ces paramètres :

  • AssemblyVersion et FileVersion correspondent par défaut à la valeur de $(Version) sans le suffixe. Par exemple, si $(Version) est 1.2.3-beta.4, alors la valeur serait 1.2.3.
  • InformationalVersion utilise par défaut la valeur de $(Version).
  • Si la propriété $(SourceRevisionId) est présente, elle est ajoutée à InformationalVersion. Vous pouvez désactiver ce comportement à l’aide de IncludeSourceRevisionInInformationalVersion.
  • Les propriétés Copyright et Description sont également utilisées pour les métadonnées NuGet.
  • Configuration, qui correspond par défaut à Debug, est partagé avec toutes les cibles MSBuild. Vous pouvez le définir via l’option --configuration des commandes dotnet, telle que dotnet pack.
  • Certaines des propriétés sont utilisées lors de la création d’un package NuGet. Pour plus d’informations, consultez Propriétés du package.

Migration à partir de .NET Framework

Les modèles de projet .NET Framework créent un fichier de code avec ces attributs d’informations d’assembly définis. Le fichier se trouve généralement dans .\Properties\AssemblyInfo.cs ou .\Properties\AssemblyInfo.vb. Les projets de style SDK génèrent ce fichier pour vous en fonction des paramètres du projet. Vous ne pouvez pas avoir les deux. Lorsque vous transférez votre code vers .NET 5 (ou .NET Core 3.1) ou version ultérieure, effectuez l’une des opérations suivantes :

  • Désactivez la génération du fichier de code temporaire qui contient les attributs d’informations d’assembly en définissant GenerateAssemblyInfo sur false dans votre fichier projet. Cela vous permet de conserver votre fichier AssemblyInfo.
  • Migrez les paramètres du fichier AssemblyInfo vers le fichier projet, puis supprimez le fichier AssemblyInfo.

GeneratedAssemblyInfoFile

La propriété GeneratedAssemblyInfoFile définit le chemin relatif ou absolu du fichier d’informations d’assembly généré. Il correspond par défaut à un fichier nommé [project-name].AssemblyInfo.[cs|vb] dans le répertoire $(IntermediateOutputPath) (généralement obj).

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

Propriétés du package

Propriétés descriptives

Vous pouvez spécifier des propriétés telles que PackageId, PackageVersion, PackageIcon, Title et Description pour décrire le package qui est créé à partir de votre projet. Pour obtenir des informations sur ces propriétés et d’autres, consultez cible pack.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

La propriété PackRelease est similaire à la propriété PublishRelease, si ce n’est qu’elle modifie le comportement par défaut de dotnet pack. Cette propriété a été introduite dans .NET 7.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

Notes

  • À partir du kit SDK .NET 8, PackRelease correspond par défaut à true. Pour plus d’informations, consultez « dotnet pack » utilise la configuration Release.
  • Kit SDK .NET 7 uniquement : pour utiliser PackRelease dans un projet qui fait partie d’une solution Visual Studio, vous devez définir la variable d’environnement DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS sur true (ou toute autre valeur). Pour les solutions qui ont de nombreux projets, la définition de cette variable augmente le temps nécessaire au pack.

Les propriétés MSBuild suivantes sont documentées dans cette section :

AppendTargetFrameworkToOutputPath

La propriété AppendTargetFrameworkToOutputPath contrôle si le moniker de framework cible (TFM) est ajouté au chemin de sortie (qui est défini par OutputPath). Le kit SDK .NET ajoute automatiquement le framework cible et, s’il est présent, l’identificateur de runtime au chemin de sortie. La définition de AppendTargetFrameworkToOutputPath sur false empêche l’ajout du moniker de framework cible au chemin de sortie. Toutefois, sans le moniker de framework cible dans le chemin de sortie, plusieurs artefacts de build peuvent se remplacer les uns les autres.

Par exemple, pour une application .NET 5, le chemin de sortie passe de bin\Debug\net5.0 à bin\Debug avec le paramètre suivant :

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

La propriété AppendRuntimeIdentifierToOutputPath contrôle si l’identificateur de runtime (RID) est ajouté au chemin de sortie. Le kit SDK .NET ajoute automatiquement le framework cible et, s’il est présent, l’identificateur de runtime au chemin de sortie. La définition de AppendRuntimeIdentifierToOutputPath sur false empêche l’ajout de l’identificateur de runtime au chemin de sortie.

Par exemple, pour une application .NET 5 et un identificateur de runtime win10-x64, le chemin de sortie passe de bin\Debug\net5.0\win10-x64 à bin\Debug\net5.0 avec le paramètre suivant :

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

La propriété CopyLocalLockFileAssemblies est utile pour les projets de plug-in qui ont des dépendances sur d’autres bibliothèques. Si vous définissez cette propriété sur true, toutes les dépendances de package NuGet sont copiées dans le répertoire de sortie. Cela signifie que vous pouvez utiliser la sortie de dotnet build pour exécuter votre plug-in sur n’importe quelle machine.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

Conseil

Vous pouvez également utiliser dotnet publish pour publier la bibliothèque de classes. Pour plus d’informations, consultez dotnet publish.

ErrorOnDuplicatePublishOutputFiles

La propriété ErrorOnDuplicatePublishOutputFiles indique si le kit SDK génère l’erreur NETSDK1148 lorsque MSBuild détecte les fichiers en double dans la sortie de publication, mais ne peut pas déterminer les fichiers à supprimer. Définissez la propriété ErrorOnDuplicatePublishOutputFiles sur false si vous ne souhaitez pas générer l’erreur.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

Cette propriété a été introduite dans .NET 6.

EnablePackageValidation

La propriété EnablePackageValidation active une série de validations sur le package après la tâche pack. Pour plus d’informations, consultez package validation.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

Cette propriété a été introduite dans .NET 6.

GenerateRuntimeConfigDevFile

À compter du kit SDK .NET 6, le fichier [Appname].runtimesettings.dev.jsonn’est plus généré par défaut au moment de la compilation. Si vous souhaitez que ce fichier soit toujours généré, définissez la propriété GenerateRuntimeConfigDevFile sur true.

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

La propriété GenerateRuntimeConfigurationFiles contrôle si les options de configuration du runtime sont copiées à partir du fichier runtimeconfig.template.json vers le fichier [appname].runtimeconfig.json. Pour les applications qui nécessitent un fichier runtimeconfig.json, c’est-à-dire celles dont OutputType a pour valeur Exe, cette propriété a la valeur true par défaut.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

La propriété GenerateSatelliteAssembliesForCore contrôle si les assemblys satellites sont générés à l’aide de csc.exe ou de Al.exe (Assembly Linker) dans les projets .NET Framework. (Les projets .NET Core et .NET 5+ utilisent toujours csc.exe pour générer des assemblys satellites.) Pour les projets .NET Framework, les assemblys satellites sont créés par al.exe, par défaut. En définissant la propriété GenerateSatelliteAssembliesForCore sur true, les assemblys satellites sont créés par csc.exe à la place. L’utilisation de csc.exe peut être avantageuse dans les situations suivantes :

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

La propriété IsPublishable permet à la cible Publish de s’exécuter. Cette propriété affecte uniquement les processus qui utilisent des fichiers .*proj et la cible Publish, comme la commande dotnet publish. Cela n’affecte pas la publication dans Visual Studio, qui utilise la cible PublishOnly. La valeur par défaut est true.

Cette propriété est utile si vous exécutez dotnet publish sur un fichier solution, car elle permet la sélection automatique des projets qui doivent être publiés.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

La propriété PreserveCompilationContext permet à une application générée ou publiée de compiler plus de code au moment de l’exécution à l’aide des mêmes paramètres que ceux utilisés au moment du build. Les assemblys référencés au moment du build sont copiés dans le sous-répertoire ref du répertoire de sortie. Les noms des assemblys de référence sont stockés dans le fichier .deps.json de l’application, avec les options passées au compilateur. Vous pouvez récupérer ces informations à l’aide des propriétés DependencyContext.CompileLibraries et DependencyContext.CompilationOptions.

Cette fonctionnalité est principalement utilisée en interne par ASP.NET Core MVC et les pages Razor pour prendre en charge la compilation au moment de l’exécution des fichiers Razor.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

La propriété PreserveCompilationReferences est similaire à la propriété PreserveCompilationContext, si ce n’est qu’elle copie uniquement les assemblys référencés dans le répertoire de publication, et non pas le fichier .deps.json.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

Pour plus d’informations, consultez Propriétés du kit SDK Razor.

ProduceReferenceAssemblyInOutDir

Dans .NET 5 et versions antérieures, les assemblys de référence sont toujours écrits dans le répertoire OutDir. Dans .NET 6 et versions ultérieures, vous pouvez utiliser la propriété ProduceReferenceAssemblyInOutDir pour contrôler si les assemblys de référence sont écrits dans le répertoire OutDir. La valeur par défaut est false et les assemblys de référence sont écrits uniquement dans le répertoire IntermediateOutputPath. Définissez la valeur sur true pour écrire les assemblys de référence dans le répertoire OutDir.

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

Pour plus d’informations, consultez Écrire les assemblys de référence dans une sortie intermédiaire.

PublishDocumentationFile

Quand cette propriété a la valeur true, le fichier de documentation XML du projet, si un tel fichier est généré, est inclus dans la sortie de publication du projet. Cette propriété a la valeur par défaut true.

Conseil

Définissez GenerateDocumentationFile sur true pour générer un fichier de documentation XML au moment de la compilation.

PublishDocumentationFiles

Cette propriété est un indicateur d’activation pour plusieurs autres propriétés qui contrôlent si différents types de fichiers de documentation XML sont copiés dans le répertoire de publication par défaut, à savoir PublishDocumentationFile et PublishReferencesDocumentationFiles. Si ces propriétés ne sont pas définies et que cette propriété est définie, ces propriétés auront par défaut la valeur true. Cette propriété a la valeur par défaut true.

PublishReferencesDocumentationFiles

Quand cette propriété a la valeur true, les fichiers de documentation XML pour les références du projet sont copiés dans le répertoire de publication, à la place des simples ressources d’exécution telles que les fichiers DLL. Cette propriété a la valeur par défaut true.

PublishRelease

La propriété PublishRelease informe dotnet publish d’utiliser par défaut la configuration Release à la place de la configuration Debug. Cette propriété a été introduite dans .NET 7.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

Notes

  • À compter du kit SDK .NET 8, PublishRelease correspond par défaut à true pour les projets qui ciblent .NET 8 ou version ultérieure. Pour plus d’informations, consultez « dotnet publish » utilise la configuration Release.
  • Cette propriété n’affecte pas le comportement de dotnet build /t:Publish et cela modifie la configuration seulement lors d’une publication via l’interface CLI .NET.
  • Kit SDK .NET 7 uniquement : pour utiliser PublishRelease dans un projet qui fait partie d’une solution Visual Studio, vous devez définir la variable d’environnement DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS sur true (ou toute autre valeur). Lors de la publication d’une solution avec cette variable activée, la valeur PublishRelease du projet exécutable est prioritaire et transmet la nouvelle configuration par défaut est à tous les autres projets de la solution. Si une solution contient plusieurs projets exécutables ou de niveau supérieur avec des valeurs différentes de PublishRelease, la solution ne publiera pas correctement. Pour les solutions incluant de nombreux projets, l’utilisation de ce paramètre augmente le temps nécessaire à la publication.

RollForward

La propriété RollForward contrôle la façon dont l’application choisit un runtime lorsque plusieurs versions de runtime sont disponibles. Cette valeur est générée dans .runtimeconfig.json en tant que paramètre rollForward.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Définissez RollForward sur l’une des valeurs suivantes :

Valeur Description
Minor Par défaut si non spécifiée.
Restauration par progression vers la version mineure supérieure la plus basse, si la version mineure demandée est manquante. Si la version mineure demandée est présente, la stratégie LatestPatch est utilisée.
Major Restauration par progression vers la version majeure supérieure suivante disponible, et la version mineure la plus basse, si la version majeure demandée est manquante. Si la version majeure demandée est présente, la stratégie Minor est utilisée.
LatestPatch Restauration par progression vers la version de correctif la plus élevée. Cette valeur désactive la restauration par progression d’une version mineure.
LatestMinor Restauration par progression vers la version mineure la plus élevée, si la version mineure demandée est présente.
LatestMajor Restauration par progression vers la version majeure la plus élevée et la version mineure la plus élevée, si la version majeure demandée est présente.
Disable N’effectuez pas de restauration par progression, mais uniquement à la version spécifiée. Cette stratégie n’est pas recommandée pour une utilisation générale, car elle désactive la possibilité d’effectuer une restauration par progression vers les derniers correctifs. Cette valeur est recommandée uniquement à des fins de test.

Pour plus d’informations, consultez Contrôler le comportement de la restauration par progression.

RuntimeFrameworkVersion

La propriété RuntimeFrameworkVersion spécifie la version du runtime à utiliser lors de la publication. Spécifiez une version du runtime :

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Lors de la publication d’une application dépendante du framework, cette valeur spécifie la version minimale requise. Lors de la publication d’une application autonome, cette valeur spécifie la version exacte requise.

RuntimeIdentifier

La propriété RuntimeIdentifier vous permet de spécifier un identificateur d’exécution (RID) unique pour le projet. Le RID permet de publier un déploiement autonome.

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

La propriété RuntimeIdentifiers vous permet de spécifier une liste délimitée par des points-virgules d’identificateurs de runtime (RID) pour le projet. Utilisez cette propriété si vous devez publier pour plusieurs runtimes. RuntimeIdentifiers est utilisé au moment de la restauration pour s’assurer que les ressources appropriées se trouvent dans le graphique.

Conseil

RuntimeIdentifier (singulier) peut fournir des builds plus rapides quand un seul runtime est nécessaire.

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

La propriété SatelliteResourceLanguages vous permet de spécifier les langues pour lesquelles vous souhaitez conserver les assemblys de ressources satellites pendant le build et la publication. De nombreux packages NuGet incluent des assemblys satellites de ressources localisées dans le package principal. Pour les projets qui référencent ces packages NuGet qui ne nécessitent pas de ressources localisées, les assemblys localisés peuvent gonfler inutilement la taille de sortie du build et de la publication. En ajoutant la propriété SatelliteResourceLanguages à votre fichier projet, seuls les assemblys localisés pour les langues que vous spécifiez seront inclus dans la sortie de build et de publication. Par exemple, dans le fichier projet suivant, seuls les assemblys satellites de ressources Anglais (US) et Allemand (Allemagne) seront conservés.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

Notes

  • Vous devez spécifier cette propriété dans le projet qui référence le package NuGet avec des assemblys satellites de ressources localisées.

  • Pour spécifier plusieurs langues comme argument pour dotnet publish, vous devez ajouter trois paires de guillemets autour des identificateurs de langue. Par exemple :

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

UseAppHost

La propriété UseAppHost contrôle si un exécutable natif est créé ou non pour un déploiement. Un exécutable natif est requis pour les déploiements autonomes.

Dans .NET Core 3.0 et versions ultérieures, un exécutable dépendant du framework est créé par défaut. Définissez la propriété UseAppHost sur false pour désactiver la génération de l’exécutable.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

Pour plus d’informations sur le déploiement, consultez Déploiement d’applications .NET.

De nombreuses propriétés MSBuild sont disponibles pour affiner le découpage, qui est une fonctionnalité qui découpe le code inutilisé des déploiements autonomes. Ces options sont décrites en détail dans Options de découpage. Le tableau suivant fournit une référence rapide.

Propriété Valeurs Description
PublishTrimmed true ou false Contrôle si le découpage est activé pendant la publication.
TrimMode full ou partial La valeur par défaut est full. Contrôle la précision du découpage.
SuppressTrimAnalysisWarnings true ou false Contrôle si des avertissements d’analyse de découpage sont générés.
EnableTrimAnalyzer true ou false Contrôle si un sous-ensemble d’avertissements d’analyse de découpage est généré. Vous pouvez activer l’analyse même si PublishTrimmed est défini sur false.
ILLinkTreatWarningsAsErrors true ou false Contrôle si les avertissements de découpage sont traités comme des erreurs. Par exemple, vous pouvez définir cette propriété sur false quand TreatWarningsAsErrors est défini sur true.
TrimmerSingleWarn true ou false Contrôle si un avertissement unique par assembly est affiché ou tous les avertissements.
TrimmerRemoveSymbols true ou false Contrôle si tous les symboles sont supprimés d’une application découpée.

Les propriétés MSBuild suivantes sont documentées dans cette section :

Les options du compilateur C#, telles que LangVersion et Nullable, peuvent également être spécifiées en tant que propriétés MSBuild dans votre fichier projet. Pour plus d’informations, consultez Options du compilateur C#.

ContinuousIntegrationBuild

La propriété ContinuousIntegrationBuild indique si une build s’exécute sur un serveur d’intégration continue (CI). Lorsqu’elle a pour valeur true, cette propriété active des paramètres qui s’appliquent uniquement aux builds officielles par opposition aux builds locales sur une machine de développement. Par exemple, les chemins de fichiers stockés sont normalisés pour les builds officielles. Toutefois, sur une machine de développement locale, le débogueur ne peut pas trouver les fichiers sources locaux si les chemins d’accès aux fichiers sont normalisés.

Vous pouvez utiliser la variable de votre système CI pour définir de manière conditionnelle la propriété ContinuousIntegrationBuild. Par exemple, le nom de la variable pour Azure Pipelines est TF_BUILD :

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

Pour GitHub Actions, le nom de la variable est GITHUB_ACTIONS :

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

Quand cette propriété a pour valeur true, tous les fichiers de symboles (également appelés fichiers PDB) issus des éléments PackageReference du projet sont copiés dans la sortie de build. Ces fichiers peuvent fournir des rapports d’appels de procédure plus informatifs pour les exceptions et faciliter la compréhension des vidages mémoire et des traces de l’application en cours d’exécution. Toutefois, l’inclusion de ces fichiers entraîne une augmentation de la taille de l’offre groupée de déploiement.

Cette propriété a été introduite dans le kit SDK .NET 7.0.100, même si, par défaut, elle n’est pas spécifiée.

CopyDocumentationFilesFromPackages

Quand cette propriété a pour valeur true, tous les fichiers de documentation XML générés à partir des éléments PackageReference du projet sont copiés dans la sortie de build. Notez que l’activation de cette fonctionnalité entraîne une augmentation de la taille de l’offre groupée de déploiement.

Cette propriété a été introduite dans le kit SDK .NET 7.0.100, même si, par défaut, elle n’est pas spécifiée.

DisableImplicitFrameworkDefines

La propriété DisableImplicitFrameworkDefines contrôle si le kit SDK génère ou non des symboles de préprocesseur pour la plateforme et le framework cible du projet .NET. Quand cette propriété a pour valeur false ou n’est pas définie (ce qui est la valeur par défaut), les symboles de préprocesseur sont générés pour :

  • Framework sans version (NETFRAMEWORK, NETSTANDARD, NET)
  • Framework avec version (NET48, NETSTANDARD2_0, NET6_0)
  • Framework avec limite de version minimale (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Pour plus d’informations sur les monikers de framework cible et ces symboles de préprocesseur implicites, consultez Frameworks cibles.

En outre, si vous spécifiez un framework cible spécifique au système d’exploitation dans le projet (par exemple net6.0-android), les symboles de préprocesseur suivants sont générés :

  • Plateforme sans version (ANDROID, IOS, WINDOWS)
  • Plateforme avec version (IOS15_1)
  • Plateforme avec limite de version minimale (IOS15_1_OR_GREATER)

Pour plus d’informations sur les monikers de framework cible spécifiques au système d’exploitation, consultez Monikers de framework cible spécifiques au système d’exploitation.

Enfin, si votre framework cible implique la prise en charge de frameworks cibles plus anciens, des symboles de préprocesseur pour ces frameworks plus anciens sont émis. Par exemple, net6.0implique la prise en charge de net5.0 et ainsi de suite jusqu’à .netcoreapp1.0. Ainsi, pour chacun de ces frameworks cibles, le symbole Framework avec limite de version minimale est défini.

DocumentationFile

La propriété DocumentationFile vous permet de spécifier un nom de fichier pour le fichier XML qui contient la documentation de votre bibliothèque. Pour qu’IntelliSense fonctionne correctement avec votre documentation, le nom de fichier doit être identique au nom de l’assembly et doit se trouver dans le même répertoire que l’assembly. Si vous ne spécifiez pas cette propriété, mais que vous définissez GenerateDocumentationFile sur true, le nom du fichier de documentation est défini par défaut sur le nom de votre assembly, mais avec une extension de fichier .xml. Pour cette raison, il est souvent plus facile d’omettre cette propriété et d’utiliser la propriété GenerateDocumentationFile à la place.

Si vous spécifiez cette propriété, mais que vous définissez GenerateDocumentationFile sur false, le compilateur ne génère pas de fichier de documentation. Si vous spécifiez cette propriété et omettez la propriété GenerateDocumentationFile, le compilateur génère un fichier de documentation.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

La propriété EmbeddedResourceUseDependentUponConvention définit si les noms de fichiers manifeste de ressources sont générés à partir d’informations de type figurant dans les fichiers sources qui sont colocalisés avec les fichiers de ressources. Par exemple, si Form1.resx se trouve dans le même dossier que Form1.cs et que EmbeddedResourceUseDependentUponConvention a la valeur true, le fichier .resources généré prend son nom du premier type défini dans Form1.cs. Par exemple, si MyNamespace.Form1 est le premier type défini dans Form1.cs, le nom de fichier généré est MyNamespace.Form1.resources.

Notes

Si les métadonnées LogicalName, ManifestResourceName ou DependentUpon sont spécifiées pour un élément EmbeddedResource, le nom de fichier manifeste généré pour ce fichier de ressources est basé sur ces métadonnées à la place.

Par défaut, dans un nouveau projet .NET, cette propriété est définie sur true. Si elle est définie sur false et qu’aucunes métadonnées LogicalName, ManifestResourceName ni DependentUpon se sont spécifiées pour l’élément EmbeddedResource dans le fichier projet, le nom de fichier manifeste de ressource est basé sur l’espace de noms racine du projet et le chemin de fichier relatif sur le fichier .resx. Pour plus d’informations, consultez Comment les fichiers manifeste de ressources sont nommés.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

La propriété EnablePreviewFeatures définit si votre projet dépend d’API ou d’assemblys décorés avec l’attribut RequiresPreviewFeaturesAttribute. Cet attribut est utilisé pour indiquer qu’une API ou un assembly utilise des fonctionnalités considérées en préversion pour la version du kit SDK que vous utilisez. Les fonctionnalités en préversion ne sont pas prises en charge et peuvent être supprimées dans une version ultérieure. Pour activer l’utilisation des fonctionnalités en préversion, définissez la propriété sur True.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

Quand un projet contient cette propriété définie sur True, l’attribut de niveau assembly suivant est ajouté au fichier AssemblyInfo.cs :

[assembly: RequiresPreviewFeatures]

Un analyseur avertit si cet attribut est présent sur les dépendances pour les projets où EnablePreviewFeatures n’est pas défini sur True.

Les auteurs de bibliothèques qui ont l’intention d’envoyer des assemblys en préversion doivent définir cette propriété sur True. Si un assembly doit être fourni avec des API qui sont en préversion et d’autres qui ne le sont pas, consultez la section GenerateRequiresPreviewFeaturesAttribute ci-dessous.

EnableWindowsTargeting

Définissez la propriété EnableWindowsTargeting sur true pour générer des applications Windows (par exemple, des applications Windows Forms ou Windows Presentation Foundation) sur une plateforme non-Windows. Si vous ne définissez pas cette propriété sur true, vous recevrez l’avertissement de build NETSDK1100. Cette erreur se produit car les packs de ciblage et d’exécution ne sont pas automatiquement téléchargés sur les plateformes qui ne sont pas prises en charge. En définissant cette propriété, ces packs sont téléchargés lors d’un ciblage croisé.

Notes

Cette propriété est recommandée pour autoriser le développement sur les plateformes non-Windows. Toutefois, quand l’application est prête à être publiée, elle doit être générée sur Windows. Lors de la génération sur une plateforme non-Windows, la sortie peut ne pas être la même que lors de la génération sur Windows. En particulier, l’exécutable n’est pas marqué en tant qu’application Windows (ce qui signifie qu’il lance toujours une fenêtre de console) et n’a pas d’icône incorporée.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

La propriété GenerateDocumentationFile contrôle si le compilateur génère un fichier de documentation XML pour votre bibliothèque. Si vous définissez cette propriété sur true et que vous ne spécifiez pas de nom de fichier via la propriété DocumentationFile, le fichier XML généré est placé dans le même répertoire de sortie que votre assembly et a le même nom de fichier (mais avec une extension .xml).

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Pour plus d’informations sur la génération de documentation à partir de commentaires de code, consultez Commentaires de documentation XML (C#), Documenter votre code avec XML (Visual Basic) ou Documenter votre code avec XML (F#).

GenerateRequiresPreviewFeaturesAttribute

La propriété GenerateRequiresPreviewFeaturesAttribute est étroitement liée à la propriété EnablePreviewFeatures. Si votre bibliothèque utilise des fonctionnalités en préversion, mais que vous ne souhaitez pas que l’assembly entier soit marqué avec l’attribut RequiresPreviewFeaturesAttribute, ce qui obligerait les consommateurs à activer les fonctionnalités d’évaluation, définissez cette propriété sur False.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Important

Si vous définissez la propriété GenerateRequiresPreviewFeaturesAttribute sur False, vous devez être certain de décorer toutes les API publiques qui s’appuient sur des fonctionnalités d’évaluation avec RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Pour réduire la durée de build, les builds qui sont implicitement déclenchés par Visual Studio ignorent l’analyse du code, y compris l’analyse nullable. Visual Studio déclenche un build implicite lorsque vous exécutez des tests, par exemple. Toutefois, les builds implicites sont optimisés uniquement quand TreatWarningsAsErrors n’est pas true. Si TreatWarningsAsErrors est défini sur true, mais que vous souhaitez toujours optimiser les builds déclenchés implicitement, vous pouvez définir OptimizeImplicitlyTriggeredBuild sur True. Pour désactiver l’optimisation de build pour les builds déclenchés implicitement, définissez OptimizeImplicitlyTriggeredBuild sur False.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

Propriétés d’inclusion d’éléments par défaut

Les propriétés MSBuild suivantes sont documentées dans cette section :

Pour plus d’informations, consultez Inclut et exclut par défaut.

DefaultItemExcludes

Utilisez la propriété DefaultItemExcludes pour définir des modèles Glob pour les fichiers et dossiers qui doivent être exclus des globs include, exclude et remove. Par défaut, les dossiers ./bin et ./obj sont exclus des modèles Glob.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

Utilisez la propriété DefaultItemExcludesInProjectFolder pour définir des modèles Glob pour les fichiers et dossiers dans le dossier de projet qui doivent être exclus des globs include, exclude et remove. Par défaut, les dossiers qui commencent par un point (.), tels que .git et .vs, sont exclus des modèles Glob.

Cette propriété est très similaire à la propriété DefaultItemExcludes, si ce n’est qu’elle prend en compte uniquement les fichiers et les dossiers dans le dossier du projet. Lorsqu’un modèle Glob correspond involontairement à des éléments situés en dehors du dossier du projet avec un chemin relatif, utilisez la propriété DefaultItemExcludesInProjectFolder à la place de la propriété DefaultItemExcludes.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

La propriété EnableDefaultItems contrôle si les éléments de compilation, les éléments de ressources incorporés et les éléments None sont implicitement inclus dans le projet. La valeur par défaut est true. Définissez la propriété EnableDefaultItems sur false pour désactiver toute inclusion de fichier implicite.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

La propriété EnableDefaultCompileItems contrôle si les éléments de compilation sont implicitement inclus dans le projet. La valeur par défaut est true. Définissez la propriété EnableDefaultCompileItems sur false pour désactiver l’inclusion implicite de *.cs et d’autres fichiers d’extension de langage.

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

La propriété EnableDefaultEmbeddedResourceItems contrôle si les éléments de ressources incorporés sont implicitement inclus dans le projet. La valeur par défaut est true. Définissez la propriété EnableDefaultEmbeddedResourceItems sur false pour désactiver l’inclusion implicite des fichiers de ressources incorporés.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

La propriété EnableDefaultNoneItems contrôle si les éléments None (fichiers qui n’ont aucun rôle dans le processus de génération) sont implicitement inclus dans le projet. La valeur par défaut est true. Définissez la propriété EnableDefaultNoneItems sur false pour désactiver l’inclusion implicite des éléments None.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

Propriétés d’analyse du code

Les propriétés MSBuild suivantes sont documentées dans cette section :

AnalysisLevel

La propriété AnalysisLevel vous permet de spécifier un ensemble d’analyseurs de code à exécuter en fonction d’une version .NET. Chaque version .NET, à compter de .NET 5, possède un ensemble de règles d’analyse du code. De cet ensemble, les règles activées par défaut pour cette version analyseront votre code. Par exemple, si vous effectuez une mise à niveau vers .NET 7, mais que vous ne souhaitez pas que l’ensemble par défaut des règles d’analyse du code soit modifié, définissez AnalysisLevel sur 6.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

Si vous le souhaitez, à partir de .NET 6, vous pouvez spécifier une valeur composée pour cette propriété, qui spécifie également avec quelle intensité activer les règles. Les valeurs composées prennent la forme <version>-<mode>, où la valeur <mode> est l’une des valeurs AnalysisMode. L’exemple suivant utilise la préversion des analyseurs de code et active l’ensemble de règles recommandé.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

Notes

Si vous définissez AnalysisLevel sur 5-<mode> ou 5.0-<mode>, puis installez le kit SDK .NET 6 et recompilez votre projet, vous pouvez voir de nouveaux avertissements de build inattendus. Pour plus d’informations, consultez dotnet/roslyn-analyzers#5679.

Valeur par défaut :

  • Si votre projet cible .NET 5 ou version ultérieure, ou si vous avez ajouté la propriété AnalysisMode, la valeur par défaut est latest.
  • Sinon, cette propriété est omise, sauf si vous l’ajoutez explicitement au fichier projet.

Le tableau suivant présente les valeurs que vous pouvez spécifier.

Valeur Signification
latest Les derniers analyseurs de code publiés sont utilisés. Il s’agit de la valeur par défaut.
latest-<mode> Les derniers analyseurs de code publiés sont utilisés. La valeur <mode> détermine quelles règles sont activées.
preview Les derniers analyseurs de code sont utilisés, même s’ils sont en préversion.
preview-<mode> Les derniers analyseurs de code sont utilisés, même s’ils sont en préversion. La valeur <mode> détermine quelles règles sont activées.
7.0 L’ensemble de règles qui était disponible pour la version .NET 7 est utilisé, même si des règles plus récentes sont disponibles.
7.0-<mode> L’ensemble de règles qui était disponible pour la version .NET 7 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
7 L’ensemble de règles qui était disponible pour la version .NET 7 est utilisé, même si des règles plus récentes sont disponibles.
7-<mode> L’ensemble de règles qui était disponible pour la version .NET 7 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
6.0 L’ensemble de règles qui était disponible pour la version .NET 6 est utilisé, même si des règles plus récentes sont disponibles.
6.0-<mode> L’ensemble de règles qui était disponible pour la version .NET 6 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
6 L’ensemble de règles qui était disponible pour la version .NET 6 est utilisé, même si des règles plus récentes sont disponibles.
6-<mode> L’ensemble de règles qui était disponible pour la version .NET 6 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
5.0 L’ensemble de règles qui était disponible pour la version .NET 5 est utilisé, même si des règles plus récentes sont disponibles.
5.0-<mode> L’ensemble de règles qui était disponible pour la version .NET 5 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
5 L’ensemble de règles qui était disponible pour la version .NET 5 est utilisé, même si des règles plus récentes sont disponibles.
5-<mode> L’ensemble de règles qui était disponible pour la version .NET 5 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.

Notes

  • Dans .NET 5 et les versions antérieures, cette propriété affecte uniquement les règles de qualité du code (CAXXXX). À compter de .NET 6, si vous définissez EnforceCodeStyleInBuild sur true, cette propriété affecte également les règles de style de code (IDEXXXX).
  • Si vous définissez une valeur composée pour AnalysisLevel, vous n’avez pas besoin de spécifier un AnalysisMode. Toutefois, si vous le faites, AnalysisLevel est prioritaire sur AnalysisMode.
  • Cette propriété n’a aucun effet sur l’analyse du code dans les projets qui ne référencent pas un kit SDK de projet, par exemple, les projets .NET Framework hérités qui référencent le package NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<Catégorie>

Introduite dans .NET 6, cette propriété est identique à AnalysisLevel, si ce n’est qu’elle s’applique uniquement à une catégorie de règles d’analyse du code spécifique. Cette propriété vous permet d’utiliser une autre version des analyseurs de code pour une catégorie spécifique, ou d’activer ou de désactiver des règles à un niveau différent des autres catégories de règles. Si vous omettez cette propriété pour une catégorie particulière de règles, elle utilise par défaut la valeur AnalysisLevel. Les valeurs disponibles sont les mêmes que celles pour AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

Le tableau suivant répertorie le nom de la propriété pour chaque catégorie de règle.

Nom de la propriété Catégorie de règle
<AnalysisLevelDesign> Règles de conception
<AnalysisLevelDocumentation> Règles de documentation
<AnalysisLevelGlobalization> Règles de globalisation
<AnalysisLevelInteroperability> Règles de portabilité et d’interopérabilité
<AnalysisLevelMaintainability> Règles de maintenabilité
<AnalysisLevelNaming> Règles d’affectation des noms
<AnalysisLevelPerformance> Règles de performances
<AnalysisLevelSingleFile> Règles d’application à fichier unique
<AnalysisLevelReliability> Règles de fiabilité
<AnalysisLevelSecurity> Règles de sécurité
<AnalysisLevelStyle> Règles de style de code (IDEXXXX)
<AnalysisLevelUsage> Règles d’utilisation

AnalysisMode

À compter de .NET 5, le kit SDK .NET est fourni avec toutes les règles de qualité du code « CA ». Par défaut, seules certaines règles sont activées en tant qu’avertissements de build dans chaque version .NET. La propriété AnalysisMode vous permet de personnaliser l’ensemble de règles activé par défaut. Vous pouvez basculer vers un mode d’analyse plus agressif où vous pouvez refuser individuellement des règles, ou vers un mode d’analyse plus conservateur où vous pouvez accepter des règles spécifiques. Par exemple, si vous souhaitez activer toutes les règles en tant qu’avertissements de build, définissez la valeur sur All.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

Le tableau suivant montre les valeurs d’option disponibles dans .NET 5 et versions ultérieures. Elles sont répertoriées dans l’ordre croissant du nombre de règles qu’elles activent.

Valeur .NET 6+ Valeur .NET 5 Signification
None AllDisabledByDefault Toutes les règles sont désactivées. Vous pouvez accepter de manière sélective des règles individuelles pour les activer.
Default Default Mode par défaut, dans lequel certaines règles sont activées en tant qu’avertissements de build, certaines règles sont activées en tant que suggestions d’IDE Visual Studio, et les autres sont désactivées.
Minimum N/A Mode plus agressif que le mode Default. Certaines suggestions fortement recommandées pour l’application de build sont activées en tant qu’avertissements de build. Pour voir quelles règles cela inclut, inspectez le fichier %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended N/A Mode plus agressif que le mode Minimum, dans lequel plus de règles sont activées en tant qu’avertissements de build. Pour voir quelles règles cela inclut, inspectez le fichier %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All AllEnabledByDefault Toutes les règles sont activées en tant qu’avertissements de build. Vous pouvez refuser de manière sélective des règles individuelles pour les désactiver.

Notes

  • Dans .NET 5, cette propriété affecte uniquement les règles de qualité du code (CAXXXX). À compter de .NET 6, si vous définissez EnforceCodeStyleInBuild sur true, cette propriété affecte également les règles de style de code (IDEXXXX).
  • Si vous utilisez une valeur composée pour AnalysisLevel, telle que <AnalysisLevel>5-recommended</AnalysisLevel>, vous pouvez omettre entièrement cette propriété. Toutefois, si vous spécifiez les deux propriétés, AnalysisLevel est prioritaire sur AnalysisMode.
  • Si AnalysisMode est défini sur AllEnabledByDefault et que AnalysisLevel est défini sur 5 ou 5.0, puis que vous installez le kit SDK .NET 6 et recompilez votre projet, vous pouvez voir de nouveaux avertissements de build inattendus. Pour plus d’informations, consultez dotnet/roslyn-analyzers#5679.
  • Cette propriété n’a aucun effet sur l’analyse du code dans les projets qui ne référencent pas un kit SDK de projet, par exemple, les projets .NET Framework hérités qui référencent le package NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisMode<Catégorie>

Introduite dans .NET 6, cette propriété est identique à AnalysisMode, si ce n’est qu’elle s’applique uniquement à une catégorie de règles d’analyse du code spécifique. Cette propriété vous permet d’activer ou de désactiver des règles à un niveau différent des autres catégories de règles. Si vous omettez cette propriété pour une catégorie particulière de règles, elle utilise par défaut la valeur AnalysisMode. Les valeurs disponibles sont les mêmes que celles pour AnalysisMode.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

Le tableau suivant répertorie le nom de la propriété pour chaque catégorie de règle.

Nom de la propriété Catégorie de règle
<AnalysisModeDesign> Règles de conception
<AnalysisModeDocumentation> Règles de documentation
<AnalysisModeGlobalization> Règles de globalisation
<AnalysisModeInteroperability> Règles de portabilité et d’interopérabilité
<AnalysisModeMaintainability> Règles de maintenabilité
<AnalysisModeNaming> Règles d’affectation des noms
<AnalysisModePerformance> Règles de performances
<AnalysisModeSingleFile> Règles d’application à fichier unique
<AnalysisModeReliability> Règles de fiabilité
<AnalysisModeSecurity> Règles de sécurité
<AnalysisModeStyle> Règles de style de code (IDEXXXX)
<AnalysisModeUsage> Règles d’utilisation

CodeAnalysisTreatWarningsAsErrors

La propriété CodeAnalysisTreatWarningsAsErrors vous permet de configurer si les avertissements d’analyse de la qualité du code (CAxxxx) doivent être traités comme des avertissements et interrompre le build. Si vous utilisez l’indicateur -warnaserror quand vous générez vos projets, les avertissements d’analyse de la qualité du code .NET sont également traités comme des erreurs. Si vous ne souhaitez pas que les avertissements d’analyse de la qualité du code soient traités comme des erreurs, vous pouvez définir la propriété MSBuild CodeAnalysisTreatWarningsAsErrors sur false dans votre fichier projet.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

L’analyse de la qualité du code .NET est activée, par défaut, pour les projets qui ciblent .NET 5 ou une version ultérieure. Si vous développez à l’aide du kit SDK .NET 5+, vous pouvez activer l’analyse du code .NET pour les projets de style SDK qui ciblent des versions antérieures de .NET en définissant la propriété EnableNETAnalyzers sur true. Pour désactiver l’analyse du code dans un projet quelconque, définissez cette propriété sur false.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Notes

Cette propriété s’applique spécifiquement aux analyseurs intégrés dans le kit SDK .NET 5+. Il ne doit pas être utilisé lorsque vous installez un package d’analyse du code NuGet.

EnforceCodeStyleInBuild

L’analyse du style de code .NET est désactivée, par défaut, lors du build pour tous les projets .NET. Vous pouvez activer l’analyse du style de code pour les projets .NET en définissant la propriété EnforceCodeStyleInBuild sur true.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

Toutes les règles de style de code configurées comme en tant qu’avertissements ou erreurs s’exécutent en cas de violations de build et de rapport.

Notes

Si vous installez .NET 6 (ou Visual Studio 2022, qui inclut .NET 6), mais que vous souhaitez générer votre projet à l’aide de Visual Studio 2019, de nouveaux avertissements CS8032 peuvent s’afficher si la propriété EnforceCodeStyleInBuild a la valeur true. Pour résoudre les avertissements, vous pouvez spécifier la version du kit SDK .NET avec lequel générer votre projet (dans ce cas, quelque chose comme 5.0.404) en ajoutant une entrée global.json.

_SkipUpgradeNetAnalyzersNuGetWarning

La propriété _SkipUpgradeNetAnalyzersNuGetWarning vous permet de configurer si vous recevez un avertissement si vous utilisez des analyseurs de code à partir d’un package NuGet obsolète par rapport aux analyseurs de code dans le dernier kit SDK .NET. L’avertissement ressemble à :

Le kit SDK .NET a des analyseurs plus récents avec la version « 6.0.0 » que ce que la version « 5.0.3 » du package « Microsoft.CodeAnalysis.NetAnalyzers » fournit. Mettez à jour ou supprimez cette référence de package.

Pour supprimer cet avertissement et continuer à utiliser la version des analyseurs de code dans le package NuGet, définissez _SkipUpgradeNetAnalyzersNuGetWarning sur true dans votre fichier projet.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

Propriétés de configuration du runtime

Vous pouvez configurer certains comportements au moment de l’exécution en spécifiant les propriétés MSBuild dans le fichier projet de l’application. Pour obtenir des informations sur d’autres façons de configurer le comportement au moment de l’exécution, consultez Paramètres de configuration du runtime.

ConcurrentGarbageCollection

La propriété ConcurrentGarbageCollection configure si le garbage collection en arrière-plan (simultané) est activé. Définissez la valeur false pour désactiver le garbage collection en arrière-plan. Pour plus d’informations, consultez GC en arrière-plan.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

La propriété InvariantGlobalization configure si l’application s’exécute en mode invariant de globalisation, ce qui signifie qu’elle n’a pas accès aux données propres à la culture. Définissez la valeur sur true pour qu’elle s’exécute en mode invariant de globalisation. Pour plus d’informations, consultez Mode invariant.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

Dans .NET 6 et versions ultérieures, la propriété PredefinedCulturesOnly configure si les applications peuvent créer des cultures autres que la culture invariante quand le mode invariant de globalisation est activé. Par défaut, il s’agit de true. Définissez la valeur sur false pour permettre la création de toute nouvelle culture en mode invariant de globalisation.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

Pour plus d’informations, consultez Création de culture et mappage de casse en mode invariant de globalisation.

RetainVMGarbageCollection

La propriété RetainVMGarbageCollection configure le récupérateur de mémoire pour placer les segments de mémoire supprimés sur une liste d’attente en vue d’une utilisation ultérieure, ou pour les libérer. La définition de la valeur true indique au récupérateur de mémoire de placer les segments sur une liste d’attente. Pour plus d’informations, consultez Conserver la machine virtuelle.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

La propriété ServerGarbageCollection configure si l’application utilise le garbage collection de station de travail ou le garbage collection de serveur. Définissez la valeur true pour utiliser le garbage collection de serveur. Pour plus d’informations, consultez Station de travail ou serveur.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

La propriété ThreadPoolMaxThreads configure le nombre maximal de threads pour le pool de threads de travail. Pour plus d’informations, consultez Nombre maximal de threads.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

La propriété ThreadPoolMinThreads configure le nombre minimal de threads pour le pool de threads de travail. Pour plus d’informations, consultez Nombre minimal de threads.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

La propriété TieredCompilation configure si le compilateur juste-à-temps (JIT) utilise la compilation hiérarchisée. Définissez la valeur false pour désactiver la compilation hiérarchisée. Pour plus d’informations, consultez Compilation hiérarchisée.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

La propriété TieredCompilationQuickJit configure si le compilateur JIT utilise le JIT rapide. Définissez la valeur false pour désactiver le JIT rapide. Pour plus d’informations, consultez JIT rapide.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

La propriété TieredCompilationQuickJitForLoops configure si le compilateur JIT utilise le JIT rapide sur les méthodes qui contiennent des boucles. Définissez la valeur true pour activer le JIT rapide sur les méthodes qui contiennent des boucles. Pour plus d’informations, consultez JIT rapide pour les boucles.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

Les propriétés MSBuild suivantes sont documentées dans cette section :

AssetTargetFallback

La propriété AssetTargetFallback vous permet de spécifier des versions de framework compatibles supplémentaires pour les références de projet et les packages NuGet. Par exemple, si vous spécifiez une dépendance de package à l’aide de PackageReference, mais que ce package ne contient pas de ressources compatibles avec le TargetFramework de votre projet, la propriété AssetTargetFallback entre en jeu. La compatibilité du package référencé est vérifiée à nouveau à l’aide de chaque framework cible spécifié dans AssetTargetFallback. Cette propriété remplace la propriété PackageTargetFallback déconseillée.

Vous pouvez définir la propriété AssetTargetFallback sur une ou plusieurs versions du framework cible.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

La propriété DisableImplicitFrameworkReferences contrôle les éléments FrameworkReference implicites lors du ciblage de .NET Core 3.0 et des versions ultérieures. Lors du ciblage de .NET Core 2.1 ou de .NET Standard 2.0 et versions antérieures, il contrôle les éléments PackageReference implicites sur les packages dans un métapackage. (Un métapackage est un package basé sur le framework qui se compose uniquement de dépendances à d’autres packages.) Cette propriété contrôle également les références implicites telles que System et System.Core lors du ciblage du .NET Framework.

Définissez cette propriété sur true pour désactiver les éléments FrameworkReference ou PackageReference implicites. Si vous définissez cette propriété sur true, vous pouvez ajouter des références explicites uniquement aux seuls frameworks et packages dont vous avez besoin.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

Définissez la propriété DisableTransitiveFrameworkReferenceDownloads sur true pour éviter de télécharger des packs d’exécution et de ciblage supplémentaires qui ne sont pas directement référencés par votre projet.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

La propriété DisableTransitiveProjectReferences contrôle les références de projet implicites. Définissez cette propriété sur true pour désactiver les éléments ProjectReference implicites. La désactivation des références de projet implicites entraîne un comportement non transitif similaire au système de projet hérité.

Quand cette propriété est true, elle a un effet similaire au fait de définir PrivateAssets="All" sur toutes les dépendances du projet.

Si vous définissez cette propriété sur true, vous pouvez ajouter des références explicites aux seuls projets dont vous avez besoin.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

ManagePackageVersionsCentrally

La propriété ManagePackageVersionsCentrally a été introduite dans .NET 7. En lui affectant la valeur true dans un fichier Directory.Packages.props à la racine de votre dépôt, vous pouvez gérer les dépendances courantes dans vos projets à partir d’un emplacement individuel. Ajoutez des versions pour les dépendances de package courantes à l’aide d’éléments PackageVersion dans le fichier Directory.Packages.props. Ensuite, dans chacun des fichiers projet, vous pouvez omettre les attributs Version de tous les éléments PackageReference qui référencent des packages gérés de manière centralisée.

Exemple de fichier Directory.Packages.props :

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

Fichier projet individuel :

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

Pour plus d’informations, consultez Gestion centralisée des packages (CPM).

La restauration d’un package référencé installe toutes ses dépendances directes et toutes les dépendances de ces dépendances. Vous pouvez personnaliser la restauration de package en spécifiant des propriétés telles que RestorePackagesPath et RestoreIgnoreFailedSources. Pour plus d’informations sur ces propriétés et d’autres propriétés, consultez cible de restauration.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

Définissez la propriété UseMauiEssentials sur true pour déclarer une référence explicite à un projet ou un package qui dépend de MAUI Essentials. Ce paramètre garantit que votre projet incorpore la référence de framework connue correcte pour MAUI Essentials. Si votre projet référence un projet qui utilise MAUI Essentials, mais que vous ne définissez pas cette propriété sur true, vous pouvez rencontrer l’avertissement de build NETSDK1186.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

La propriété ValidateExecutableReferencesMatchSelfContained peut être utilisée pour désactiver les erreurs liées aux références de projet exécutables. Si .NET détecte qu’un projet exécutable autonome référence un projet exécutable dépendant du framework, ou vice versa, il génère l’erreur NETSDK1150 ou NETSDK1151, respectivement. Pour éviter ces erreurs quand la référence est intentionnelle, définissez la propriété ValidateExecutableReferencesMatchSelfContained sur false.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

La propriété WindowsSdkPackageVersion peut être utilisée pour remplacer la version du package de ciblage du kit SDK Windows. Cette propriété a été introduite dans .NET 5 et remplace l’utilisation de l’élément FrameworkReference à cet effet.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

Notes

Nous vous déconseillons d’écraser la version du kit SDK Windows, car les packages de ciblage du kit SDK Windows sont inclus avec le kit SDK .NET 5+. Pour faire référence au dernier package du kit SDK Windows, mettez plutôt à jour votre version du kit SDK .NET. Cette propriété ne doit être utilisée que dans de rares cas, tels que l’utilisation de packages en préversion ou la nécessité de remplacer la version de C#/WinRT.

Les propriétés suivantes sont utilisées pour lancer une application avec la commande dotnet run :

RunArguments

La propriété RunArguments définit les arguments qui sont transmis à l’application lors de son exécution.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

Conseil

Vous pouvez spécifier des arguments supplémentaires à transmettre à l’application à l’aide de l’option -- pour dotnet run.

RunWorkingDirectory

La propriété RunWorkingDirectory définit le répertoire de travail dans lequel le processus d’application doit être démarré. Il peut s’agir d’un chemin absolu ou d’un chemin relatif au répertoire du projet. Si vous ne spécifiez pas de répertoire, OutDir est utilisé comme répertoire de travail.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

Les propriétés MSBuild suivantes sont documentées dans cette section :

EnableComHosting

La propriété EnableComHosting indique qu’un assembly fournit un serveur COM. La définition de EnableComHosting sur true implique également que EnableDynamicLoading a la valeur true.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

Pour plus d’informations, consultez Exposer les composants .NET à COM.

EnableDynamicLoading

La propriété EnableDynamicLoading indique qu’un assembly est un composant chargé dynamiquement. Le composant peut être une bibliothèque COM ou une bibliothèque non-COM qui peut être utilisée à partir d’un hôte natif ou utilisée en tant que plug-in. La définition de cette propriété sur true a les effets suivants :

  • Un fichier .runtimeconfig.json est généré.
  • RollForward est défini sur LatestMinor.
  • Les références NuGet sont copiées localement.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Propriétés des fichiers générés

Les propriétés suivantes concernent le code dans les fichiers générés :

DisableImplicitNamespaceImports

La propriété DisableImplicitNamespaceImports peut être utilisée pour désactiver les importations d’espaces de noms implicites dans les projets Visual Basic qui ciblent .NET 6 ou une version ultérieure. Les espaces de noms implicites sont les espaces de noms par défaut qui sont importés globalement dans un projet Visual Basic. Définissez cette propriété sur true pour désactiver les importations d’espaces de noms implicites.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

La propriété ImplicitUsings peut être utilisée pour activer et désactiver les directives global using implicites dans les projets C# qui ciblent .NET 6 ou une version ultérieure et C# 10 ou une version ultérieure. Quand la fonctionnalité est activée, le kit SDK .NET ajoute des directives global using pour un ensemble d’espaces de noms par défaut en fonction du type de kit SDK de projet. Définissez cette propriété sur true ou enable pour activer des directives implicites global using. Pour désactiver les directives global using implicites, supprimez la propriété ou définissez-la sur false ou disable.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

Notes

Les modèles pour les nouveaux projets C# qui ciblent .NET 6 ou version ultérieure ont ImplicitUsings défini sur enable par défaut.

Pour définir une directive global using explicite, ajoutez un élément Using.

Éléments

Les éléments MSBuild sont des entrées dans le système de génération. Les éléments sont spécifiés en fonction de leur type, qui est le nom de l’élément. Par exemple, Compile et Reference sont deux types d’élément courants. Les types d’élément supplémentaires suivants sont mis à disposition par le kit SDK .NET :

Vous pouvez utiliser l’un des attributs d’élément standard, tel que Include et Update, sur ces éléments. Utilisez Include pour ajouter un nouvel élément et utilisez Update pour modifier un élément existant. Par exemple, Update est souvent utilisé pour modifier un élément qui a été implicitement ajouté par le kit SDK .NET.

AssemblyMetadata

L’élément AssemblyMetadata spécifie un attribut d’assembly AssemblyMetadataAttribute de paire clé-valeur. Les métadonnées Include deviennent la clé et les métadonnées Value deviennent la valeur.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

L’élément InternalsVisibleTo génère un attribut d’assembly InternalsVisibleToAttribute pour l’assembly friend spécifié.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

Si l’assembly friend est signé, vous pouvez spécifier des métadonnées Key facultatives pour spécifier sa clé publique complète. Si vous ne spécifiez pas de métadonnées Key et qu’un $(PublicKey) est disponible, cette clé est utilisée. Sinon, aucune clé publique n’est ajoutée à l’attribut.

PackageReference

L’élément PackageReference définit une référence à un package NuGet.

L’attribut Include spécifie l’ID du package. L’attribut Version spécifie la version ou la plage de versions. Pour plus d’informations sur la façon de spécifier une version minimale, une version maximale, une plage ou une correspondance exacte, consultez Plages de versions.

L’extrait de code de fichier projet dans l’exemple suivant référence le package System.Runtime.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

Vous pouvez également contrôler les ressources de dépendance à l’aide de métadonnées telles que PrivateAssets.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Pour plus d’informations, consultez Références de package dans les fichiers projet.

TrimmerRootAssembly

L’élément TrimmerRootAssembly vous permet d’exclure un assembly du découpage. Le découpage est le processus consistant à supprimer les parties inutilisées du runtime d’une application empaquetée. Dans certains cas, le découpage peut supprimer de façon incorrecte les références requises.

Le code XML suivant exclut l’assembly System.Security du découpage.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

Pour plus d’informations, consultez Options de découpage.

Utilisation

L’élément Using vous permet d’inclure globalement un espace de noms dans votre projet C#, de manière à ce que vous n’ayez pas à ajouter de directive using pour l’espace de noms en haut de vos fichiers sources. Cet élément est similaire à l’élément Import qui peut être utilisé dans le même but dans les projets Visual Basic. Cette propriété est disponible à partir de .NET 6.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

Vous pouvez également utiliser l’élément Using pour définir des directives using <alias> et using static <type> globales.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

Par exemple :

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> émet global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> émet global using static global::Microsoft.AspNetCore.Http.Results;

Pour plus d’informations, consultez directives using avec alias et directives using static <type>.

Métadonnées d’élément

En plus des attributs d’élément MSBuild standard, les balises de métadonnées d’élément suivantes sont mises à disposition par le kit SDK .NET :

CopyToPublishDirectory

Les métadonnées CopyToPublishDirectory d’un élément MSBuild contrôlent le moment où l’élément est copié dans le répertoire de publication. Les valeurs autorisées sont PreserveNewest, qui copie uniquement l’élément s’il a changé, Always, qui copie toujours l’élément et Never, qui ne copie jamais l’élément. Du point de vue des performances, PreserveNewest est préférable, car cela permet une génération incrémentielle.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

Pour un élément qui se trouve en dehors du répertoire du projet et de ses sous-répertoires, la cible de publication utilise les métadonnées de lien de l’élément pour déterminer où copier l’élément. Link détermine également comment les éléments en dehors de l’arborescence du projet sont affichés dans la fenêtre Explorateur de solutions de Visual Studio.

Si Link n’est pas spécifié pour un élément qui se trouve en dehors du cône du projet, la valeur par défaut est %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase vous permet de spécifier un dossier de base sensible pour les éléments en dehors du cône du projet. La hiérarchie de dossiers sous le dossier de base est conservée via RecursiveDir. Si LinkBase n’est pas spécifié, il est omis du chemin Link.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

L’image suivante montre comment un fichier inclus via le glob Include de l’élément précédent s’affiche dans l’Explorateur de solutions.

Explorateur de solutions montrant l’élément avec des métadonnées LinkBase.

Voir aussi