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

  • Article
  • 44 minutes de lecture

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 un travail en cours et ne répertorie pas toutes les propriétés MSBuild utiles pour le Kit de développement logiciel (SDK) .NET. Pour obtenir la liste des propriétés MSBuild courantes, consultez Propriétés MSBuild courantes.

Propriétés de l’infrastructure

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

TargetFramework

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

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

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

TargetFrameworks

Utilisez la TargetFrameworks propriété lorsque vous souhaitez que votre application cible plusieurs plateformes. Pour obtenir la liste des monikers d’infrastructure cible valides, consultez Infrastructures 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 Infrastructures cibles dans les projets de style SDK.

NetStandardImplicitPackageVersion

Notes

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

Utilisez la NetStandardImplicitPackageVersion propriété lorsque vous souhaitez spécifier une version du framework inférieure à la version du métapackage. 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 GenerateAssemblyInfo propriété contrôle AssemblyInfo la génération d’attributs 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é.

Lorsque la valeur est true, les GenerateAssemblyInfopropriétés de projet liées au package 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, par exemple :

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Propriété MSBuild Attribut d’assembly Propriété permettant de 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 par défaut à la valeur de $(Version) sans 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 $(SourceRevisionId) propriété 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 a la Debugvaleur par défaut , est partagé avec toutes les cibles MSBuild. Vous pouvez le définir via l’option --configuration de dotnet commandes, par exemple 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. Tu ne peux pas avoir les deux. Lorsque vous transférez votre code vers .NET 5 (ou .NET Core 3.1) ou une 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 GenerateAssemblyInfofalse sur dans votre fichier projet. Cela vous permet de conserver votre fichier AssemblyInfo .
  • Migrez les paramètres du AssemblyInfo fichier vers le fichier projet, puis supprimez le AssemblyInfo fichier.

GeneratedAssemblyInfoFile

La GeneratedAssemblyInfoFile propriété définit le chemin d’accès relatif ou absolu du fichier d’informations d’assembly généré. Par défaut, un fichier nommé [nom du projet]. AssemblyInfo. [cs|vb] dans le $(IntermediateOutputPath) répertoire (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, Titleet Description pour décrire le package créé à partir de votre projet. Pour plus d’informations sur ces propriétés et d’autres, consultez pack target.

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

PackRelease

La PackRelease propriété est similaire à la propriété PublishRelease , sauf qu’elle modifie le comportement par défaut de dotnet pack.

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

Notes

Pour utiliser PackRelease dans un projet faisant partie d’une solution Visual Studio, vous devez définir la variable DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS d’environnement sur true (ou toute autre valeur). La définition de cette variable augmente le temps nécessaire pour emballer les solutions qui ont de nombreux projets.

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

AppendTargetFrameworkToOutputPath

La AppendTargetFrameworkToOutputPath propriété contrôle si le moniker du framework cible (TFM) est ajouté au chemin de sortie (qui est défini par OutputPath). Le Kit de développement logiciel (SDK) .NET ajoute automatiquement l’infrastructure cible et, le cas échéant, l’identificateur du runtime au chemin de sortie. La définition AppendTargetFrameworkToOutputPath de sur false empêche l’ajout du TFM au chemin de sortie. Toutefois, sans le TFM 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 AppendRuntimeIdentifierToOutputPath propriété contrôle si l’identificateur d’exécution (RID) est ajouté au chemin de sortie. Le Kit de développement logiciel (SDK) .NET ajoute automatiquement l’infrastructure cible et, le cas échéant, l’identificateur du runtime au chemin de sortie. La définition AppendRuntimeIdentifierToOutputPath de sur false empêche l’ajout du RID au chemin de sortie.

Par exemple, pour une application .NET 5 et un RID de 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 CopyLocalLockFileAssemblies propriété 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 quel ordinateur.

<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 ErrorOnDuplicatePublishOutputFiles propriété indique si le Kit de développement logiciel (SDK) génère l’erreur NETSDK1148 lorsque MSBuild détecte des fichiers en double dans la sortie de publication, mais ne peut pas déterminer les fichiers à supprimer. Définissez la ErrorOnDuplicatePublishOutputFiles propriété false sur si vous ne souhaitez pas que l’erreur soit générée.

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

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

EnablePackageValidation

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

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

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

GenerateRuntimeConfigDevFile

À compter du Kit de développement logiciel (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 toujours que ce fichier soit généré, définissez la propriété sur GenerateRuntimeConfigDevFiletrue.

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

GenerateRuntimeConfigurationFiles

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

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

GenerateSatelliteAssembliesForCore

La GenerateSatelliteAssembliesForCore propriété contrôle si les assemblys satellites sont générés à l’aide decsc.exe ou deAl.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 GenerateSatelliteAssembliesForCore propriété sur true, les assemblys satellites sont créés par csc.exe à la place. L’utilisation decsc.exe peut être avantageuse dans les situations suivantes :

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

IsPublishable

La IsPublishable propriété permet à la Publish cible de s’exécuter. Cette propriété affecte uniquement les processus qui utilisent les fichiers .*proj et la Publish cible, comme la commande dotnet publish . Cela n’affecte pas la publication dans Visual Studio, qui utilise la PublishOnly cible. 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 PreserveCompilationContext propriété 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 celui utilisé au moment de la génération. Les assemblys référencés au moment de la génération 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, ainsi que les options transmises au compilateur. Vous pouvez récupérer ces informations à l’aide des DependencyContext.CompileLibraries propriétés et DependencyContext.CompilationOptions .

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

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

PreserveCompilationReferences

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

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

Pour plus d’informations, consultez Propriétés du Kit de développement logiciel (SDK) Razor.

ProduceReferenceAssemblyInOutDir

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

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

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

PublishDocumentationFile

Lorsque cette propriété est true, le fichier de documentation XML du projet, le cas échéant, est inclus dans la sortie de publication du projet. Cette propriété a la valeur par défaut true.

Conseil

Définissez GenerateDocumentationFile surtrue 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 la valeur par défaut true. Cette propriété a la valeur par défaut true.

PublishReferencesDocumentationFiles

Lorsque cette propriété est true, les fichiers de documentation XML pour les références du projet sont copiés dans le répertoire de publication, au lieu de simplement utiliser des ressources au moment de l’exécution, comme des fichiers DLL. Cette propriété a la valeur par défaut true.

PublishRelease

La PublishRelease propriété indique dotnet publish d’utiliser la Release configuration par défaut au lieu de la Debug configuration.

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

Notes

  • Cette propriété n’affecte pas le comportement de et modifie la configuration uniquement lors de dotnet build /t:Publish la publication via l’interface CLI .NET.
  • Pour utiliser PublishRelease dans un projet faisant partie d’une solution Visual Studio, vous devez définir la variable DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS d’environnement sur true (ou toute autre valeur). Cela augmentera le temps nécessaire à la publication des solutions qui ont de nombreux projets. Lors de la publication d’une solution avec cette variable activée, la valeur du PublishRelease projet exécutable est prioritaire et la nouvelle configuration par défaut est transmise à 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 sera pas publiée avec succès.

RollForward

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

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

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

Valeur Description
Minor Valeur par défaut si elle n’est pas spécifiée.
Effectuez un roll-forward 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 LatestPatch stratégie est utilisée.
Major Effectuez un roll-forward vers la version majeure supérieure disponible suivante et la version mineure la plus basse, si la version principale demandée est manquante. Si la version principale demandée est présente, la Minor stratégie est utilisée.
LatestPatch Effectuez un roll-forward vers la version de correctif la plus élevée. Cette valeur désactive la restauration de version mineure.
LatestMinor Transférer vers la version mineure la plus élevée, même si la version mineure demandée est présente.
LatestMajor Effectuez un roll-forward vers la version majeure la plus élevée et la version mineure la plus élevée, même si la version majeure demandée est présente.
Disable Ne effectuez pas de restauration, 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é de restaurer 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.

RuntimeFrameworkVersion

La RuntimeFrameworkVersion propriété 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 RuntimeIdentifier propriété vous permet de spécifier un identificateur d’exécution unique (RID) pour le projet. Le RID permet de publier un déploiement autonome.

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

RuntimeIdentifiers

La RuntimeIdentifiers propriété vous permet de spécifier une liste délimitée par des points-virgules d’identificateurs d’exécution (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 requis.

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

SatelliteResourceLanguages

La SatelliteResourceLanguages propriété vous permet de spécifier les langues pour lesquelles vous souhaitez conserver les assemblys de ressources satellites pendant la génération et la publication. De nombreux packages NuGet incluent des assemblys satellites de ressources localisés 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 augmenter inutilement la taille de sortie de build et de publication. En ajoutant la SatelliteResourceLanguages propriété à votre fichier projet, seuls les assemblys localisés pour les langues que vous spécifiez seront inclus dans la sortie de génération et de publication. Par exemple, dans le fichier projet suivant, seuls les assemblys satellites de ressources anglais (États-Unis) 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 fait référence au package NuGet avec des assemblys satellites de ressources localisés.

  • Pour spécifier plusieurs langues comme argument de 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 UseAppHost propriété 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é sur UseAppHostfalse 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 supprime 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 granularité 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 seul avertissement par assembly est affiché ou tous les avertissements.
TrimmerRemoveSymbols true ou false Contrôle si tous les symboles sont supprimés d’une application supprimé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 ContinuousIntegrationBuild propriété indique si une build s’exécute sur un serveur d’intégration continue (CI). Lorsqu’elle trueest définie sur , cette propriété active les paramètres qui s’appliquent uniquement aux builds officielles par opposition aux builds locales sur un ordinateur de développement. Par exemple, les chemins d’accès aux fichiers stockés sont normalisés pour les builds officielles. Toutefois, sur un ordinateur de développement local, 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 la ContinuousIntegrationBuild propriété de manière conditionnelle. 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

Lorsque cette propriété a la truevaleur , tous les fichiers de symboles (également appelés fichiers PDB) des PackageReference éléments du projet sont copiés dans la sortie de build. Ces fichiers peuvent fournir des traces de pile plus informatives 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 SDK .NET 7.0.100, bien qu’elle ne soit pas spécifiée par défaut.

CopyDocumentationFilesFromPackages

Lorsque cette propriété a la truevaleur , tous les fichiers de documentation XML générés à partir d’é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 SDK .NET 7.0.100, bien qu’elle ne soit pas spécifiée par défaut.

DisableImplicitFrameworkDefines

La DisableImplicitFrameworkDefines propriété contrôle si le Kit de développement logiciel (SDK) génère ou non des symboles de préprocesseur pour l’infrastructure et la plateforme cibles pour le projet .NET. Lorsque cette propriété a la false valeur ou n’est pas définie (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 une 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 une infrastructure 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 d’infrastructure cible spécifiques au système d’exploitation, consultez Les modules de gestion des systèmes d’exploitation spécifiques au système d’exploitation.

Enfin, si votre infrastructure cible implique la prise en charge des infrastructures cibles plus anciennes, des symboles de préprocesseur pour ces infrastructures plus anciennes 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 framework avec le symbole de limite minimale de version est défini.

DocumentationFile

La DocumentationFile propriété 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 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 correspond par défaut au 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 EmbeddedResourceUseDependentUponConvention propriété définit si les noms de fichiers manifeste de ressources sont générés à partir des informations de type 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 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 LogicalName, ManifestResourceNameou DependentUpon métadonnées est spécifié pour un EmbeddedResource élément, 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 la valeur falseest définie sur , et qu’aucune métadonnées , ManifestResourceNameou DependentUpon n’est LogicalNamespécifiée pour l’élément EmbeddedResource dans le fichier projet, le nom du fichier manifeste de ressource est basé sur l’espace de noms racine du projet et le chemin d’accès au fichier .resx relatif. Pour plus d’informations, consultez Comment les fichiers de manifeste de ressources sont nommés.

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

EnablePreviewFeatures

La EnablePreviewFeatures propriété 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 comme étant en préversion pour la version du Kit de développement logiciel (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 d’aperçu, définissez la propriété sur True.

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

Lorsqu’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èque qui ont l’intention d’envoyer des assemblys en préversion doivent définir cette propriété sur True. Si un assembly doit être livré avec un mélange d’API de préversion et d’API non préversion, consultez la section GenerateRequiresPreviewFeaturesAttribute ci-dessous.

ActiverWindowsTargeting

Définissez la EnableWindowsTargeting propriété true sur 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 téléchargés automatiquement sur les plateformes qui ne sont pas prises en charge. En définissant cette propriété, ces packs sont téléchargés lors du ciblage croisé.

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

GenerateDocumentationFile

La GenerateDocumentationFile propriété 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 GenerateRequiresPreviewFeaturesAttribute propriété est étroitement liée à la propriété EnablePreviewFeatures . Si votre bibliothèque utilise des fonctionnalités d’aperçu, mais que vous ne souhaitez pas que l’assembly entier soit marqué avec l’attribut RequiresPreviewFeaturesAttribute , ce qui obligerait tous les consommateurs à activer les fonctionnalités d’aperçu, définissez cette propriété sur False.

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

Important

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

OptimizeImplicitlyTriggeredBuild

Pour accélérer le temps de génération, les builds qui sont implicitement déclenchées par Visual Studio ignorent l’analyse du code, y compris l’analyse nullable. Visual Studio déclenche une build implicite lorsque vous exécutez des tests, par exemple. Toutefois, les builds implicites sont optimisées uniquement lorsque TreatWarningsAsErrors n’est pas true. Si vous avez TreatWarningsAsErrors défini sur true mais que vous souhaitez toujours optimiser les builds déclenchées implicitement, vous pouvez définir sur TrueOptimizeImplicitlyTriggeredBuild . Pour désactiver l’optimisation de build pour les builds implicitement déclenchées, définissez sur OptimizeImplicitlyTriggeredBuildFalse.

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

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

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

Pour plus d’informations, consultez Inclusions et exclusions par défaut.

DefaultItemExcludes

Utilisez la DefaultItemExcludes propriété 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 DefaultItemExcludesInProjectFolder propriété pour définir des modèles glob pour les fichiers et dossiers du 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 DefaultItemExcludes propriété, sauf qu’elle ne tient compte que des fichiers et dossiers dans le dossier du projet. Lorsqu’un modèle glob correspond involontairement à des éléments situés en dehors du dossier de projet avec un chemin relatif, utilisez la propriété à la DefaultItemExcludesInProjectFolder place de la DefaultItemExcludes propriété .

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

EnableDefaultItems

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

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

EnableDefaultCompileItems

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

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

EnableDefaultNoneItems

La EnableDefaultNoneItems propriété contrôle si None les éléments (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é sur EnableDefaultNoneItemsfalse pour désactiver l’inclusion implicite d’é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 AnalysisLevel propriété vous permet de spécifier un ensemble d’analyseurs de code à exécuter en fonction d’une version .NET. Chaque version de .NET, à partir de .NET 5, a un ensemble de règles d’analyse du code. De cet ensemble, les règles activées par défaut pour cette version analysent 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 de règles d’analyse du code change, définissez sur AnalysisLevel6.

<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 l’intensité d’activation des règles. Les valeurs composées prennent la forme <version>-<mode>, où la <mode> valeur 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 AnalysisLevel5-<mode> sur ou 5.0-<mode> , puis installez le KIT de développement logiciel (SDK) .NET 6 et recompilez votre projet, vous pouvez voir des avertissements de nouvelle génération 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 montre 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 <mode> valeur détermine les règles 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 c’est le cas, AnalysisLevel est prioritaire sur AnalysisMode.
  • Cette propriété n’a aucun effet sur l’analyse du code dans les projets qui ne font pas référence à un kit SDK de projet, par exemple, les projets .NET Framework hérités qui font référence au package NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Catégorie AnalysisLevel<>

Introduite dans .NET 6, cette propriété est identique à AnalysisLevel, sauf qu’elle s’applique uniquement à une catégorie spécifique de règles d’analyse du code. 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 d’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 code (IDEXXXX)
<AnalysisLevelUsage> Règles d’utilisation

AnalysisMode

À compter de .NET 5, le Kit de développement logiciel (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 de .NET. La AnalysisMode propriété vous permet de personnaliser l’ensemble de règles activées par défaut. Vous pouvez basculer vers un mode d’analyse plus agressif où vous pouvez refuser des règles individuellement, ou 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 choisir de manière sélective des règles individuelles pour les activer.
Default Default Mode par défaut, où 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 le reste est désactivé.
Minimum N/A Mode plus agressif que Default mode. Certaines suggestions fortement recommandées pour l’application de la 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 Minimum mode, où davantage de règles sont activées comme avertissements de build. Pour voir quelles règles cela inclut, examinez 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 désactiver 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, par exemple, <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 a la AllEnabledByDefault valeur et AnalysisLevel a la 5 valeur ou 5.0, puis que vous installez le Kit de développement logiciel (SDK) .NET 6 et recompilez votre projet, vous pouvez voir des avertissements de nouvelle génération 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 font pas référence à un kit SDK de projet, par exemple, les projets .NET Framework hérités qui font référence au package NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Catégorie AnalysisMode<>

Introduite dans .NET 6, cette propriété est identique à AnalysisMode, sauf qu’elle s’applique uniquement à une catégorie spécifique de règles d’analyse du code. 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 d’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 code (IDEXXXX)
<AnalysisModeUsage> Règles d’utilisation

CodeAnalysisTreatWarningsAsErrors

La CodeAnalysisTreatWarningsAsErrors propriété vous permet de configurer si les avertissements d’analyse de la qualité du code (CAxxxx) doivent être traités comme des avertissements et interrompre la génération. Si vous utilisez l’indicateur -warnaserror lorsque 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 CodeAnalysisTreatWarningsAsErrors propriété MSBuild 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 de développement logiciel (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 EnableNETAnalyzers propriété sur true. Pour désactiver l’analyse du code dans n’importe quel projet, 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 de développement logiciel (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, sur la build pour tous les projets .NET. Vous pouvez activer l’analyse du style de code pour les projets .NET en définissant la EnforceCodeStyleInBuild propriété sur true.

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

Toutes les règles de style de code configurées pour être des avertissements ou des erreurs s’exécutent lors de la génération et des violations 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, vous pouvez voir de nouveaux avertissements CS8032 si la propriété est EnforceCodeStyleInBuild définie sur true. Pour résoudre les avertissements, vous pouvez spécifier la version du Kit de développement logiciel (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 _SkipUpgradeNetAnalyzersNuGetWarning propriété 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 du dernier sdk .NET. L’avertissement ressemble à ce qui suit :

Le SDK .NET a des analyseurs plus récents avec la version « 6.0.0 » que celle de la version « 5.0.3 » du package « Microsoft.CodeAnalysis.NetAnalyzers ». 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 _SkipUpgradeNetAnalyzersNuGetWarningtrue sur dans votre fichier projet.

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

Propriétés de configuration du runtime

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

ConcurrentGarbageCollection

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

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

InvariantGlobalization

La InvariantGlobalization propriété configure si l’application s’exécute en mode globalisation-invariant , 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>

PrédéfiniCulturesOnly

Dans .NET 6 et versions ultérieures, la PredefinedCulturesOnly propriété configure si les applications peuvent créer des cultures autres que la culture invariante lorsque le mode de globalisation-invariant 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 cas en mode invariant de globalisation.

RetainVMGarbageCollection

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

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

ServerGarbageCollection

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

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

ThreadPoolMaxThreads

La ThreadPoolMaxThreads propriété 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 ThreadPoolMinThreads propriété configure le nombre minimal de threads pour le pool de threads de travail. Pour plus d’informations, consultez Threads minimum.

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

TieredCompilation

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

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

TieredCompilationQuickJit

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

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

TieredCompilationQuickJitForLoops

La TieredCompilationQuickJitForLoops propriété configure si le compilateur JIT utilise le JIT rapide sur les méthodes qui contiennent des boucles. Définissez la valeur sur 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 AssetTargetFallback propriété vous permet de spécifier des versions d’infrastructure 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 PackageReferenceTargetFrameworkde mais que ce package ne contient pas de ressources compatibles avec les projets , la AssetTargetFallback propriété entre en jeu. La compatibilité du package référencé est vérifiée à l’aide de chaque infrastructure cible spécifiée dans AssetTargetFallback. Cette propriété remplace la propriété PackageTargetFallbackdépréciée .

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

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

DisableImplicitFrameworkReferences

La DisableImplicitFrameworkReferences propriété contrôle les éléments implicites FrameworkReference lors du ciblage de .NET Core 3.0 et versions ultérieures. Lors du ciblage de .NET Core 2.1 ou .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 l’infrastructure qui se compose uniquement de dépendances sur 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 implicites FrameworkReference ou PackageReference . Si vous définissez cette propriété sur true, vous pouvez ajouter des références explicites uniquement aux frameworks ou aux packages dont vous avez besoin.

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

DisableTransitiveFrameworkReferenceDownloads

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

Lorsque cette propriété a truela valeur , elle a un effet similaire à celui de la définition PrivateAssets="All" sur toutes les dépendances du projet dépendant.

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

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

ManagePackageVersionsCentrally

La ManagePackageVersionsCentrally propriété a été introduite dans .NET 7. En lui true affectant la valeur 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. Ajoutez des versions pour les dépendances de package courantes à l’aide PackageVersiond’éléments dans le fichier Directory.Packages.props . Ensuite, dans les fichiers projet individuels, vous pouvez omettre Version des attributs de tous PackageReference les éléments qui font référence à 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é true sur UseMauiEssentials 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 tire la référence d’infrastructure connue correcte pour MAUI Essentials. Si votre projet fait référence à un projet qui utilise MAUI Essentials mais que vous ne définissez pas cette propriété sur true, vous pouvez rencontrer un avertissement NETSDK1186de build .

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

ValidateExecutableReferencesMatchSelfContained

La ValidateExecutableReferencesMatchSelfContained propriété 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 fait référence à un projet exécutable dépendant du framework, ou vice versa, il génère des erreurs NETSDK1150 et NETSDK1151, respectivement. Pour éviter ces erreurs lorsque la référence est intentionnelle, définissez la propriété sur ValidateExecutableReferencesMatchSelfContainedfalse.

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

WindowsSdkPackageVersion

La WindowsSdkPackageVersion propriété peut être utilisée pour remplacer la version du package de ciblage du 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 de remplacer la version du Kit de développement logiciel (SDK) Windows, car les packages de ciblage du SDK Windows sont inclus avec le SDK .NET 5+ . Au lieu de cela, pour référencer le dernier package du SDK Windows, mettez à jour votre version du 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 dotnet run commande :

RunArguments

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

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

Conseil

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

RunWorkingDirectory

La RunWorkingDirectory propriété 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 d’accès 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 EnableComHosting propriété indique qu’un assembly fournit un serveur COM. La définition de sur implique également que EnableDynamicLoading a la EnableComHostingtrue valeur true.

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

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

EnableDynamicLoading

La EnableDynamicLoading propriété 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 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 de fichier générées

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

DisableImplicitNamespaceImports

La DisableImplicitNamespaceImports propriété 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 ImplicitUsings propriété peut être utilisée pour activer et désactiver les directives implicites global using dans les projets C# qui ciblent .NET 6 ou une version ultérieure et C# 10 ou une version ultérieure. Lorsque la fonctionnalité est activée, le Kit de développement logiciel (SDK) .NET ajoute global using des directives pour un ensemble d’espaces de noms par défaut en fonction du type de KIT de développement logiciel (SDK) de projet. Définissez cette propriété sur true ou enable pour activer les directives implicites global using . Pour désactiver les directives implicites global using , 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 enable sur par défaut.

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

Éléments

Les éléments MSBuild sont des entrées dans le système de build. 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éments courants. Les types d’éléments supplémentaires suivants sont mis à disposition par le Kit de développement logiciel (SDK) .NET :

Vous pouvez utiliser l’un des attributs d’élément standard, par exemple et IncludeUpdate, sur ces éléments. Utilisez Include pour ajouter un nouvel élément et pour Update modifier un élément existant. Par exemple, Update est souvent utilisé pour modifier un élément qui a été implicitement ajouté par le Kit de développement logiciel (SDK) .NET.

AssemblyMetadata

L’élément AssemblyMetadata spécifie un attribut d’assembly de paire AssemblyMetadataAttribute clé-valeur. Les Include métadonnées deviennent la clé et les Value métadonnées 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 facultatives Key pour spécifier sa clé publique complète. Si vous ne spécifiez Key pas de métadonnées 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 fait référence au 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 des fichiers projet.

TrimmerRootAssembly

L’élément TrimmerRootAssembly vous permet d’exclure un assembly de la suppression. La suppression est le processus de suppression des parties inutilisées du runtime d’une application empaquetée. Dans certains cas, la suppression peut supprimer incorrectement les références requises.

Le code XML suivant exclut l’assembly System.Security de la suppression.

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

Pour plus d’informations, consultez Options de suppression.

Utilisation

L’élément Using vous permet d’inclure globalement un espace de noms dans votre projet C#, de sorte que vous n’avez pas à ajouter de using directive 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 globales using <alias> et using static <type> .

<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 et using static <type> directivesavec using alias.

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 de développement logiciel (SDK) .NET :

CopyToPublishDirectory

Les CopyToPublishDirectory métadonnées 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, est préférable, PreserveNewest car elle 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. Linkdé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 de 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 d’accès Link .

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

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

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

Voir aussi