Partager via

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 validation d’assembly

Ces propriétés et éléments sont passés à la tâche ValidateAssemblies. Pour obtenir plus d’informations sur la validation d’assembly, consultez Validation d’assembly.

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

Remarque

Ces propriétés ne font pas partie du Kit de développement logiciel (SDK) .NET (pour le moment). Pour les utiliser, vous devez également ajouter un PackageReference à Microsoft.DotNet.ApiCompat.Task.

En outre, les propriétés suivantes qui sont documentées dans les Propriétés de validation de package s’appliquent également à la validation d’assembly :

ApiCompatStrictMode

Lorsque la valeur est définie sur true, la propriété ApiCompatStrictMode spécifie que les vérifications de compatibilité de l’API doivent être effectuées en mode strict.

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

La propriété ApiCompatValidateAssemblies active une série de validations sur les assemblys spécifiés. Pour obtenir plus d’informations, consultez Validation de l’assembly.

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

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>net8.0</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>net8.0;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.

Pour plus d’informations sur la génération d’attributs d’assembly en utilisant un fichier projet, consultez Définir des attributs d’assembly dans un fichier projet.

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.

Propriétés de validation de package

Ces propriétés et éléments sont transmis à la tâche ValidatePackage. Pour obtenir plus d’informations sur la validation de package, consultez Vue d’ensemble de la validation de package.

Pour connaître les propriétés de la tâche ValidateAssemblies, consultez Propriétés de validation d’assembly.

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

ApiCompatEnableRuleAttributesMustMatch

Lorsqu’elle est définietrue, la propriété ApiCompatEnableRuleAttributesMustMatch active la règle de validation qui vérifie la correspondance des attributs. Par défaut, il s’agit de false.

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

Lorsqu’elle est définietrue, la propriété ApiCompatEnableRuleCannotChangeParameterName active la règle de validation qui vérifie si les noms de paramètres ont changé dans les méthodes publiques. Par défaut, il s’agit de false.

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

L’élément ApiCompatExcludeAttributesFile spécifie le chemin d’accès à un fichier qui contient des attributs à exclure dans le format DocId.

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

La propriété ApiCompatGenerateSuppressionFile spécifie s’il faut générer un fichier de suppression de compatibilité.

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

La propriété ApiCompatPermitUnnecessarySuppressions spécifie s’il faut autoriser les suppressions inutiles dans le fichier de suppression.

Par défaut, il s’agit de false.

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

La propriété ApiCompatPreserveUnnecessarySuppressions spécifie s’il faut conserver les suppressions inutiles lors de la régénération du fichier de suppressions. Lorsqu’un fichier de suppression existant est régénéré, son contenu est lu, désérialisé dans un ensemble de suppressions, puis stocké dans une liste. Il est possible que certaines des suppressions ne soient plus nécessaires si l’incompatibilité a été corrigée. Lorsque les suppressions sont resérialisées sur disque, vous pouvez choisir de conserver toutes les expressions (désérialisées) existantes en définissant cette propriété sur true.

Par défaut, il s’agit de false.

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

La propriété ApiCompatRespectInternals spécifie si la compatibilité des API internal doit être vérifiée en plus des API public.

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

L’élément ApiCompatSuppressionFile spécifie le chemin d’accès à un ou plusieurs fichiers de suppression à partir desquels effectuer la lecture. S’il n’est pas spécifié, le fichier de suppression <project-directory>/CompatibilitySuppressions.xml est lu (s’il existe).

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

La propriété ApiCompatSuppressionOutputFile spécifie le chemin d’accès à un fichier de suppression à partir duquel écrire quand <ApiCompatGenerateSuppressionFile> est true. S’il n’est pas spécifié, le premier élément ApiCompatSuppressionFile est utilisé.

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>

EnableStrictModeForBaselineValidation

Lorsqu’elle est définie sur true, la propriété EnableStrictModeForBaselineValidation active le mode strict pour les vérifications de référence de package. Par défaut, il s’agit de false.

EnableStrictModeForCompatibleFrameworksInPackage

Lorsqu’elle est définie sur true, la propriété EnableStrictModeForCompatibleFrameworksInPackage active le mode strict pour les assemblys compatibles en fonction de leur version cible de .Net Framework. Par défaut, il s’agit de false.

EnableStrictModeForCompatibleTfms

Lorsqu’elle est définie sur true, la propriété EnableStrictModeForCompatibleTfms active le mode strict pour les assemblys de contrat et d’implémentation de toutes les versions cibles de .Net Framework compatibles. Par défaut, il s’agit de true.

NoWarn

La propriété NoWarn spécifie les ID de diagnostic à supprimer.

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

L’élément PackageValidationBaselineFrameworkToIgnore spécifie une version cible de .Net Framework à ignorer à partir du package de référence. La chaîne d’infrastructure doit correspondre exactement au nom du dossier dans le package de la ligne de base.

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

La propriété PackageValidationBaselineName spécifie le nom du package de référence pour valider le package actuel. Si elle n’est pas spécifiée, la valeur PackageId est utilisée.

PackageValidationBaselineVersion

La propriété PackageValidationBaselineVersion spécifie la version du package de référence pour valider le package actuel.

PackageValidationReferencePath

L’élément PackageValidationReferencePath spécifie le chemin d’accès au répertoire dans lequel l’assembly de référence est trouvé par TFM.

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

La propriété RoslynAssembliesPath spécifie le chemin d’accès au répertoire qui contient les assemblys Microsoft.CodeAnalysis que vous souhaitez utiliser. Vous devez uniquement définir cette propriété si vous souhaitez tester avec un compilateur plus récent que ce qui se trouve dans le Kit de développement logiciel (SDK).

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 RID de win-x64, le paramètre suivant modifie le chemin de sortie de bin\Debug\net5.0\win-x64 :bin\Debug\net5.0

<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é truesur , toutes les dépendances de package NuGet transitives 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>

La valeur par défaut de CopyLocalLockFileAssemblies peut varier en fonction du type de sortie. Par exemple, pour les bibliothèques de classes, la valeur par défaut est false, tandis que pour les applications console, la valeur par défaut est true. Vous pouvez spécifier cette propriété explicitement pour remplacer la valeur par défaut si nécessaire.

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.

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.

PublishSelfContained

La propriété PublishSelfContained informe dotnet publish de publier une application en tant qu’application autonome. Cette propriété est utile lorsque vous ne pouvez pas utiliser l’argument --self-contained de la commande dotnet publish, par exemple lorsque vous publiez au niveau de la solution. Dans ce cas, vous pouvez ajouter la propriété MSBuild PublishSelfContained à un projet ou à un fichier Directory.Build.Props.

Cette propriété a été introduite dans .NET 7. Elle est similaire à la propriété SelfContained, sauf qu’elle est spécifique au verbe publish. Il est recommandé d'utiliser PublishSelfContained plutôt que SelfContained.

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

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>linux-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>win-x64;osx-x64;linux-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"""

SelfContained

La propriété SelfContained informe dotnet build et dotnet publish de publier une application en tant qu’application autonome. Cette propriété est utile lorsque vous ne pouvez pas utiliser l’argument --self-contained avec la commande dotnet, par exemple lorsque vous publiez au niveau de la solution. Dans ce cas, vous pouvez ajouter la propriété MSBuild SelfContained à un projet ou à un fichier Directory.Build.Props.

Cette propriété est similaire à la propriété PublishSelfContained. Il est recommandé d'utiliser PublishSelfContained plutôt que SelfContained si possible.

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

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. Un exécutable dépendant de l’infrastructure 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 n’est pas capable de trouver les fichiers sources locaux si leurs chemins d’accès sont normalisés.

Remarque

La définition de cette propriété sur true ne fonctionne actuellement que si vous ajoutez une référence spécifique du package de fournisseur SourceLink ou un élément <SourceRoot Include="$(MyDirectory)" />. Pour plus d’informations, consultez Problème dotnet/roslyn 55860.

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.0 cela implique une prise en charge pour 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. Si MyNamespace.Form1 est le premier type défini dans Form1.cs, le nom de fichier généré est MyNamespace.Form1.resources.

Remarque

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.

Dans un nouveau projet .NET qui cible .NET Core 3.0 ou une version ultérieure, cette propriété est définie par défaut 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>

DisableRuntimeMarshalling

La propriété DisableRuntimeMarshalling vous permet de spécifier que vous souhaitez désactiver la prise en charge du marshaling du runtime pour votre projet. Si cette propriété est définie sur true, alors DisableRuntimeMarshallingAttribute est ajoutée à l’assembly et toute interopérabilité en fonction du délégué ou P/Invokes suit les règles pour le marshaling du runtime désactivé.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</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 8, 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 7.

<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>

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.
8.0 L’ensemble de règles qui était disponible pour la version .NET 8 est utilisé, même si des règles plus récentes sont disponibles.
8.0-<mode> L’ensemble de règles qui était disponible pour la version .NET 8 est utilisé, même si des règles plus récentes sont disponibles. La valeur <mode> détermine quelles règles sont activées.
8 L’ensemble de règles qui était disponible pour la version .NET 8 est utilisé, même si des règles plus récentes sont disponibles.
8-<mode> L’ensemble de règles qui était disponible pour la version .NET 8 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.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.

Remarque

  • À compter de .NET 6, si vous définissez EnforceCodeStyleInBuild sur true, cette propriété affecte également les règles de style de code (IDEXXXX) (en plus des règles de qualité de code).
  • 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>

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

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 indique les valeurs d’option disponibles. Elles sont répertoriées dans l’ordre croissant du nombre de règles qu’elles activent.

Valeur Description
None Toutes les règles sont désactivées. Vous pouvez accepter de manière sélective des règles individuelles pour les activer.
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 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 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 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.

* Les règles suivantes ne sont pas activées en définissant AnalysisMode sur All ou en définissant AnalysisLevel sur latest-all : CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 et les règles de l’analyseur de métriques de code (CA1501, CA1502, CA1505, CA1506 et CA1509). Ces règles héritées pourraient être dépréciées dans une version ultérieure. Toutefois, vous pouvez toujours les activer individuellement à l’aide d’une entrée dotnet_diagnostic.CAxxxx.severity = <severity>.

Remarque

  • À compter de .NET 6, si vous définissez EnforceCodeStyleInBuild sur true, cette propriété affecte également les règles de style de code (IDEXXXX) (en plus des règles de qualité de code).
  • Si vous utilisez une valeur composée pour AnalysisLevel, telle que <AnalysisLevel>8-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.
  • 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>

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.

_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 d’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 d’exécution, consultez Paramètres de configuration d’exécution.

AutoreleasePoolSupport

La propriété AutoreleasePoolSupport indique si chaque thread managé reçoit un NSAutoreleasePool implicite quand il s’exécute sur une plateforme macOS prise en charge. Pour plus d'informations, consultez AutoreleasePool pour les threads gérés.

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

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>

TieredPGO

La propriété TieredPGO indique si l’optimisation guidée par profil (PGO) dynamique ou hiérarchisée est activée. Définissez la valeur sur true pour activer la PGO hiérarchisée. Pour plus d’informations, consultez Optimisation guidée par profil.

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

Pour Windows seulement, la propriété UseWindowsThreadPool configure si la gestion des threads de pool de threads est déléguée au pool de threads Windows. La valeur par défaut est false, auquel cas le pool de threads .NET est utilisé. Pour plus d’informations, consultez Pool de threads Windows.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</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 RunArguments propriété définit les arguments passés à 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>

Tester les propriétés liées au projet

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

IsTestProject

La IsTestProject propriété signifie qu’un projet est un projet de test. Lorsque cette propriété est définie truesur , validation pour vérifier si le projet fait référence à un exécutable autonome est désactivé. Cela est dû au fait que les projets de test ont une OutputType Exe API d’un fichier exécutable référencé plutôt que d’essayer d’exécuter. En outre, si un projet fait référence à trueun projet sur lequel IsTestProject il est défini, le projet de test n’est pas validé en tant que référence exécutable.

Cette propriété est principalement nécessaire pour le dotnet test scénario et n’a aucun impact lors de l’utilisation de vstest.console.exe.

Remarque

Si votre projet spécifie le Kit de développement logiciel (SDK) MSTest, vous n’avez pas besoin de définir cette propriété. Elle est définie automatiquement. De même, cette propriété est définie automatiquement pour les projets qui référencent le package NuGet Microsoft.NET.Test.Sdk lié à VSTest.

IsTestingPlatformApplication

Lorsque votre projet fait référence au package Microsoft.Testing.Platform.MSBuild , le paramètre IsTestingPlatformApplication sur true (qui est également la valeur par défaut s’il n’est pas spécifié) effectue les opérations suivantes :

  • Génère le point d’entrée du projet de test.
  • Génère le fichier de configuration.
  • Détecte les extensions.

Définition de la propriété pour false désactiver la dépendance transitive sur le package. Une dépendance transitive est lorsqu’un projet qui fait référence à un autre projet qui fait référence à un package donné se comporte comme s’il référence le package. Vous devez généralement définir cette propriété false dans un projet non test qui fait référence à un projet de test. Pour plus d’informations, consultez l’erreur CS8892.

Si votre projet de test fait référence à MSTest, NUnit ou xUnit, cette propriété est définie sur la même valeur que EnableMSTestRunner, EnableNUnitRunner ou UseMicrosoftTestingPlatformRunner (pour xUnit).

Enable[NugetPackageNameWithoutDots]

Utilisez une propriété avec le modèle Enable[NugetPackageNameWithoutDots] pour activer ou désactiver les extensions Microsoft.Testing.Platform.

Par exemple, pour activer l’extension de vidage sur incident (package NuGet Microsoft.Testing.Extensions.CrashDump), définissez la EnableMicrosoftTestingExtensionsCrashDump truevaleur .

Pour plus d’informations, consultez Activer ou désactiver des extensions.

EnableAspireTesting

Lorsque vous utilisez le Kit de développement logiciel (SDK) du projet MSTest, vous pouvez utiliser la EnableAspireTesting propriété pour importer toutes les dépendances et directives par défaut using dont vous avez besoin pour les tests avec Aspire et MSTest. Cette propriété est disponible dans MSTest 3.4 et versions ultérieures.

Pour plus d’informations, consultez Test avec .NET Aspire.

EnablePlaywright

Lorsque vous utilisez le Kit de développement logiciel (SDK) du projet MSTest, vous pouvez utiliser la EnablePlaywright propriété pour importer toutes les dépendances et directives par défaut using dont vous avez besoin pour les tests avec Playwright et MSTest. Cette propriété est disponible dans MSTest 3.4 et versions ultérieures.

Pour plus d’informations, consultez Playwright.

EnableMSTestRunner

La EnableMSTestRunner propriété active ou désactive l’utilisation de l’exécuteur MSTest. L’exécuteur MSTest est une alternative légère et portable à VSTest. Cette propriété est disponible dans MSTest 3.2 et versions ultérieures.

Remarque

Si votre projet spécifie le Kit de développement logiciel (SDK) MSTest, vous n’avez pas besoin de définir cette propriété. Elle est définie automatiquement.

EnableNUnitRunner

La EnableNUnitRunner propriété active ou désactive l’utilisation de l’exécuteur NUnit. L’exécuteur NUnit est une alternative légère et portable à VSTest. Cette propriété est disponible dans NUnit3TestAdapter dans la version 5.0 et versions ultérieures.

GenerateTestingPlatformEntryPoint

Définition de la GenerateTestingPlatformEntryPoint propriété pour false désactiver la génération automatique du point d’entrée du programme dans un projet de test MSTest, NUnit ou xUnit. Vous souhaiterez peut-être définir cette propriété false quand vous définissez manuellement un point d’entrée, ou lorsque vous référencez un projet de test à partir d’un exécutable qui a également un point d’entrée.

Pour plus d’informations, consultez l’erreur CS8892.

Pour contrôler la génération du point d’entrée dans un projet VSTest, utilisez la GenerateProgramFile propriété.

TestingPlatformCaptureOutput

La TestingPlatformCaptureOutput propriété contrôle si toutes les sorties de console qu’un exécutable de test écrit sont capturées et masquées par l’utilisateur lorsque vous utilisez dotnet test pour exécuter Microsoft.Testing.Platform des tests. Par défaut, la sortie de la console est masquée. Cette sortie inclut la bannière, les informations de version et les informations de test mises en forme. Définissez cette propriété pour false afficher ces informations avec la sortie MSBuild.

Pour plus d’informations, consultez Afficher la sortie complète de la plateforme.

TestingPlatformCommandLineArguments

La TestingPlatformCaptureOutput propriété vous permet de spécifier des arguments de ligne de commande à l’application de test lorsque vous utilisez dotnet test pour exécuter Microsoft.Testing.Platform des tests. L’extrait de code de fichier projet suivant montre un exemple.

<PropertyGroup>
  ...
  <TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>

TestingPlatformDotnetTestSupport

La TestingPlatformDotnetTestSupport propriété vous permet de spécifier si VSTest est utilisé lorsque vous utilisez dotnet test pour exécuter des tests. Si vous définissez cette propriété truesur , VSTest est désactivé et tous les Microsoft.Testing.Platform tests sont exécutés directement.

Si vous avez une solution qui contient des projets de test VSTest ainsi que des projets MSTest, NUnit ou XUnit, vous devez effectuer un appel par mode (autrement dit, dotnet test n’exécutera pas de tests à partir de VSTest et des plateformes plus récentes dans un seul appel).

TestingPlatformShowTestsFailure

La TestingPlatformShowTestsFailure propriété vous permet de contrôler si une seule défaillance ou toutes les erreurs d’un test ayant échoué sont signalées lorsque vous utilisez dotnet test pour exécuter des tests. Par défaut, les échecs des tests sont résumés dans un fichier .log, et un seul échec par projet de test est signalé à MSBuild. Pour afficher les erreurs par test ayant échoué, définissez cette propriété true sur dans votre fichier projet.

TestingExtensionsProfile

Lorsque vous utilisez le Kit de développement logiciel (SDK) du projet MSTest, la TestingExtensionsProfile propriété vous permet de sélectionner un profil à utiliser. Le tableau suivant présente les valeurs autorisées.

Valeur Description
Default Active les extensions recommandées pour cette version de MSTest.SDK.
None Aucune extension n’est activée.
AllMicrosoft Activez toutes les extensions fournies par Microsoft (y compris les extensions avec une licence restrictive).

Pour plus d’informations, consultez le profil msTest runner.

UseVSTest

Définissez la UseVSTest propriété pour true passer de l’exécuteur MSTest à l’exécuteur VSTest lors de l’utilisation du KIT DE DÉVELOPPEMENT logiciel (SDK) du projet MSTest.

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

AppHostDotNetSearch

La AppHostDotNetSearch propriété configure la façon dont l’exécutable natif produit pour une application recherche une installation .NET. Cette propriété affecte uniquement l’exécutable généré lors de la publication, et non de la build.

<PropertyGroup>
  <AppHostDotNetSearch>Global</AppHostDotNetSearch>
</PropertyGroup>

Le tableau suivant répertorie les valeurs valides. Vous pouvez spécifier plusieurs valeurs, séparées par des points-virgules.

Valeur Signification
AppLocal Dossier de l’exécutable de l’application
AppRelative Chemin relatif à l’exécutable de l’application, tel que spécifié par AppHostRelativeDotNet
EnvironmentVariables Valeur des variables d’environnement DOTNET_ROOT[_<arch>]
Global Emplacements d’installation globaux inscrits et par défaut

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

AppHostRelativeDotNet

La AppHostRelativeDotNet propriété permet de spécifier un chemin relatif pour l’exécutable de l’application pour rechercher l’installation de .NET lorsqu’elle est configurée pour le faire. La définition de la AppHostRelativeDotNet propriété implique que AppHostDotNetSearch c’est AppRelative. Cette propriété affecte uniquement l’exécutable généré lors de la publication, et non de la build.

<PropertyGroup>
  <AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
</PropertyGroup>

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

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.

FrameworkReference

L’élément FrameworkReference définit une référence à une infrastructure partagée .NET.

L’attribut Include spécifie l’ID de l’infrastructure.

L’extrait de code de fichier projet dans l’exemple suivant référence l’infrastructure partagée Microsoft.AspNetCore.App.

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

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