Fonctions de propriété

Les fonctions de propriété sont des appels aux méthodes .NET qui apparaissent dans les définitions de propriétés MSBuild. Vous les utilisez généralement pour construire des définitions de propriétés qui nécessitent une logique plus complexe.

Contrairement aux tâches, les fonctions de propriété peuvent être utilisées en dehors des cibles. Les fonctions de propriété sont évaluées chaque fois que les propriétés ou les éléments sont développés. Ainsi, pour les propriétés et les éléments en dehors de cibles, les fonctions de propriété sont évaluées avant l’exécution de toute cible. Pour les groupes de propriétés et les groupes d’éléments à l’intérieur des cibles, les fonctions de propriété sont évaluées lorsque la cible est exécutée.

Sans utiliser de tâches MSBuild, vous pouvez lire l’heure système, comparer les chaînes, faire correspondre les expressions régulières et effectuer d’autres actions dans votre script de génération. MSBuild tente de convertir la chaîne en nombre et nombre en chaîne, et effectue d’autres conversions selon les besoins.

Les valeurs de chaîne retournées à partir de fonctions de propriété ont des caractères spéciaux d’échappement. Si vous souhaitez que la valeur soit traitée comme si elle était placée directement dans le fichier projet, utilisez $([MSBuild]::Unescape()) pour déséchapper les caractères spéciaux.

Syntaxe de la fonction de propriété

Il existe trois types de fonctions de propriété ; chaque type a une syntaxe différente :

• Fonctions de propriété String (instance)
• Fonctions de propriété statique
• Fonctions de propriété MSBuild

Fonctions de propriété de chaîne

Toutes les valeurs de propriété de build sont uniquement des valeurs de chaîne. Vous pouvez utiliser des méthodes de chaîne (instance) pour fonctionner sur n’importe quelle valeur de propriété. Par exemple, vous pouvez extraire le nom du lecteur de disque (les trois premiers caractères) d’une propriété de construction qui représente un chemin d’accès complet à l’aide de ce code :

$(ProjectOutputFolder.Substring(0,3))

Fonctions de propriété statique

Dans votre script de génération, vous pouvez accéder aux propriétés statiques et aux méthodes de nombreuses classes système. Pour obtenir la valeur d’une propriété statique, utilisez la syntaxe suivante, où Class est le nom de la classe système et Property le nom de la propriété.

$([Class]::Property)

Par exemple, vous pouvez utiliser le code suivant pour définir une propriété de build sur la date et l’heure actuelles.

<Today>$([System.DateTime]::Now)</Today>

Pour appeler une méthode statique, utilisez la syntaxe suivante, où Class est le nom de la classe système, Method le nom de la méthode et (Parameters) la liste des paramètres de la méthode :

$([Class]::Method(Parameters))

Par exemple, pour définir une propriété de build sur un nouveau GUID, vous pouvez utiliser ce script :

<NewGuid>$([System.Guid]::NewGuid())</NewGuid>

Pour les méthodes surchargées, MSBuild tente de trouver une méthode avec des paramètres correspondants.

Dans MSBuild 17.14 et versions ultérieures, vous pouvez utiliser la syntaxe out _ des paramètres pour spécifier un out paramètre. Consultez les paramètres de référence. La valeur du out paramètre est ignorée. Par exemple:

<IsInteger>$([System.Int32]::TryParse("123", out _))</IsInteger>

La propriété IsInteger est true si l’entrée est correctement analysée en tant qu’entier, mais que la valeur analysée est ignorée.

Dans les fonctions de propriété statique, vous pouvez utiliser n’importe quelle méthode statique publique ou propriété définie dans .NET Standard 2.0 pour ces classes système :

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset (disponible dans MSBuild 17.3 et versions ultérieures)
• System.Decimal
• System.Double
• System.Enum
• System.Guid
• System.Int16
• System.Int32
• System.Int64
• System.IO.Path
• System.Math
• System.Runtime.InteropServices.OSPlatform
• System.Runtime.InteropServices.RuntimeInformation
• System.UInt16
• System.UInt32
• System.UInt64
• System.SByte
• System.Single
• System.String
• System.StringComparer
• System.TimeSpan
• System.Text.RegularExpressions.Regex
• System.UriBuilder
• System.Version
• Microsoft.Build.Utilities.ToolLocationHelper

En outre, vous pouvez utiliser les méthodes et propriétés statiques suivantes :

• System.Environment ::CommandLine
• System.Environment::ExpandEnvironmentVariables
• System.Environment::GetEnvironmentVariable
• System.Environment::GetEnvironmentVariables
• System.Environment ::GetFolderPath
• System.Environment::GetLogicalDrives
• System.Environment::Is64BitOperatingSystem
• System.Environment::Is64BitProcess
• System.Environment ::MachineName
• System.Environment::NewLine
• System.Environment ::OSVersion
• System.Environment::ProcessorCount
• System.Environment ::StackTrace
• System.Environment::SystemDirectory
• System.Environment ::SystemPageSize
• System.Environment ::TickCount
• System.Environment ::UserDomainName
• System.Environment ::UserInteractive
• System.Environment ::UserName
• System.Environment::Version
• System.Environment::WorkingSet
• System.IO.Directory ::GetDirectories
• System.IO.Directory ::GetFiles
• System.IO.Directory ::GetLastAccessTime
• System.IO.Directory ::GetLastWriteTime
• System.IO.Directory::GetParent
• System.IO.File ::Exists
• System.IO.File ::GetAttributes
• System.IO.File ::GetCreationTime
• System.IO.File ::GetLastAccessTime
• System.IO.File ::GetLastWriteTime
• System.IO.File ::ReadAllText
• System.Globalization.CultureInfo ::GetCultureInfo
• System.Globalization.CultureInfo ::new
• System.Globalization.CultureInfo::CurrentUICulture

<IsWindows>$([System.OperatingSystem]::IsWindows())</IsWindows>

Appel de méthodes d’instance sur des propriétés statiques

Si vous accédez à une propriété statique qui retourne une instance d’objet, vous pouvez appeler les méthodes d’instance de cet objet. Pour appeler une méthode d’instance, utilisez la syntaxe suivante, où Class est le nom de la classe système, Property est le nom de la propriété, Method est le nom de la méthode et (Parameters) la liste des paramètres de la méthode :

$([Class]::Property.Method(Parameters))

Le nom de la classe doit être complet avec l’espace de noms.

Par exemple, vous pouvez utiliser le code suivant pour définir une propriété de build sur la date actuelle d'aujourd'hui.

<Today>$([System.DateTime]::Now.ToString('yyyy.MM.dd'))</Today>

Fonctions de propriété MSBuild

Vous pouvez accéder à plusieurs méthodes statiques dans votre build, qui prennent en charge des fonctions liées à l’arithmétique, à la logique au niveau du bit et aux caractères d’échappement. Vous accédez à ces méthodes à l’aide de la syntaxe suivante, où Method est le nom de la méthode et (Parameters) la liste des paramètres de la méthode.

$([MSBuild]::Method(Parameters))

Par exemple, pour ajouter deux propriétés qui ont des valeurs numériques, utilisez le code suivant.

$([MSBuild]::Add($(NumberOne), $(NumberTwo)))

Voici la liste des fonctions de propriété MSBuild :

Fonctions de propriété imbriquées

Vous pouvez combiner des fonctions de propriété pour former des fonctions plus complexes, comme l’illustre l’exemple suivant :

$([MSBuild]::BitwiseAnd(32, $([System.IO.File]::GetAttributes(tempFile))))

Cet exemple retourne la valeur du FileAttributes. Bit Archive (32 ou 0) du fichier donné par le chemin d’accès tempFile. Notez que les valeurs de données énumérées ne peuvent pas apparaître par nom dans certains contextes. Dans l’exemple précédent, la valeur numérique (32) doit être utilisée à la place. Dans d’autres cas, selon les attentes de la méthode appelée, la valeur des données d’énumération doit être utilisée. Dans l’exemple suivant, la valeur enum RegexOptions. ECMAScript doit être utilisé, car une valeur numérique ne peut pas être convertie comme l'attend cette méthode.

<PropertyGroup>
    <GitVersionHeightWithOffset>$([System.Text.RegularExpressions.Regex]::Replace("$(PrereleaseVersion)", "^.*?(\d+)$", "$1", "System.Text.RegularExpressions.RegexOptions.ECMAScript"))</GitVersionHeightWithOffset>
</PropertyGroup>

Les métadonnées peuvent également apparaître dans les fonctions de propriété imbriquées. Pour plus d’informations, consultez l’article Batching (Traitement par lot MSBuild).

Fonction MSBuild DoesTaskHostExist

La DoesTaskHostExist fonction de propriété dans MSBuild retourne si un hôte de tâche est actuellement installé pour les valeurs d’architecture et d’exécution spécifiées.

Cette fonction de propriété a la syntaxe suivante :

$([MSBuild]::DoesTaskHostExist(string theRuntime, string theArchitecture))

MSBuild EnsureTrailingSlash

La fonction de propriété EnsureTrailingSlash dans MSBuild ajoute une barre oblique de fin s’il n’en existe pas déjà une.

Cette fonction de propriété a la syntaxe suivante :

$([MSBuild]::EnsureTrailingSlash('$(PathProperty)'))

Fonction MSBuild GetDirectoryNameOfFileAbove

La fonction de propriété MSBuild GetDirectoryNameOfFileAbove recherche vers le haut un répertoire contenant le fichier spécifié, en commençant par (et y compris) le répertoire spécifié. Elle retourne le chemin d’accès complet du répertoire le plus proche contenant le fichier s’il est trouvé, sinon une chaîne vide.

Cette fonction de propriété a la syntaxe suivante :

$([MSBuild]::GetDirectoryNameOfFileAbove(string startingDirectory, string fileName))

Cet exemple montre comment importer le fichier EnlistmentInfo.props le plus proche dans ou au-dessus du dossier actif, uniquement si une correspondance est trouvée :

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), EnlistmentInfo.props))\EnlistmentInfo.props" Condition=" '$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), EnlistmentInfo.props))' != '' " />

Ce même exemple peut être écrit plus succinctement en utilisant la fonction GetPathOfFileAbove :

<Import Project="$([MSBuild]::GetPathOfFileAbove(EnlistmentInfo.props))" Condition=" '$([MSBuild]::GetPathOfFileAbove(EnlistmentInfo.props))' != '' " />

MSBuild GetPathOfFileAbove

La fonction de propriété MSBuild GetPathOfFileAbove recherche vers le haut un répertoire contenant le fichier spécifié, en commençant par (et y compris) le répertoire spécifié. Elle retourne le chemin complet du fichier correspondant le plus proche s’il est trouvé, sinon une chaîne vide.

Cette fonction de propriété a la syntaxe suivante :

$([MSBuild]::GetPathOfFileAbove(string file, [string startingDirectory]))

où file est le nom du fichier à rechercher et startingDirectory est un répertoire facultatif dans lequel démarrer la recherche. Par défaut, la recherche démarre dans le répertoire du fichier actif.

Cet exemple montre comment importer un fichier nommé dir.props dans ou au-dessus du répertoire actif, uniquement si une correspondance est trouvée :

<Import Project="$([MSBuild]::GetPathOfFileAbove(dir.props))" Condition=" '$([MSBuild]::GetPathOfFileAbove(dir.props))' != '' " />

qui est fonctionnellement équivalente à

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))\dir.props" Condition=" '$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))' != '' " />

Toutefois, vous devez parfois démarrer la recherche dans le répertoire parent pour éviter de faire correspondre le fichier actuel. Cet exemple montre comment un fichier Directory.Build.props peut importer le fichier Directory.Build.props le plus proche dans un niveau strictement supérieur de l’arborescence, sans importer de manière récursive elle-même :

<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

qui est fonctionnellement équivalente à

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove('$(MSBuildThisFileDirectory)../', 'Directory.Build.props'))/Directory.Build.props" />

Fonction MSBuild GetRegistryValue

La fonction de propriété MSBuild GetRegistryValue retourne la valeur d’une clé de Registre. Cette fonction prend deux arguments, le nom de clé et le nom de la valeur, puis retourne la valeur du Registre. Si vous ne spécifiez pas de nom de valeur, la valeur par défaut est retournée.

Les exemples suivants montrent comment cette fonction est utilisée :

$([MSBuild]::GetRegistryValue(`HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\Debugger`, ``))                                  // default value
$([MSBuild]::GetRegistryValue(`HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\Debugger`, `SymbolCacheDir`))
$([MSBuild]::GetRegistryValue(`HKEY_LOCAL_MACHINE\SOFTWARE\(SampleName)`, `(SampleValue)`))             // parens in name and value

Fonction MSBuild GetRegistryValueFromView

La fonction de propriété MSBuild GetRegistryValueFromView obtient les données du Registre système en fonction de la clé de Registre, de la valeur et d’une ou plusieurs vues de Registre ordonnées. La clé et la valeur sont recherchées dans chaque vue du Registre dans l’ordre, jusqu’à ce qu’elles soient trouvées.

La syntaxe de cette fonction de propriété est la suivante :

[MSBuild]::GetRegistryValueFromView(string keyName, string valueName, object defaultValue, params object[] views)

Le système d’exploitation Windows 64 bits gère une clé de Registre HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node qui présente une vue de Registre HKEY_LOCAL_MACHINE\SOFTWARE pour les applications 32 bits.

Par défaut, une application 32 bits s’exécutant sur WOW64 accède à la vue de Registre 32 bits et une application 64 bits accède à la vue de Registre 64 bits.

Les vues de Registre suivantes sont disponibles :

Voici un exemple.

$([MSBuild]::GetRegistryValueFromView('HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SDKs\Silverlight\v3.0\ReferenceAssemblies', 'SLRuntimeInstallPath', null, RegistryView.Registry64, RegistryView.Registry32))

Le code précédent obtient les données SLRuntimeInstallPath de la clé ReferenceAssemblies, en recherchant d'abord dans la vue d'enregistrement 64 bits, puis dans celle 32 bits.

Fonction MSBuild MakeRelative

La fonction de propriété MSBuild MakeRelative retourne le chemin relatif du deuxième chemin par rapport au chemin d’accès initial. Chaque chemin d’accès peut être un fichier ou un dossier.

Cette fonction de propriété a la syntaxe suivante :

$([MSBuild]::MakeRelative($(FileOrFolderPath1), $(FileOrFolderPath2)))

Le code suivant est un exemple de cette syntaxe.

<PropertyGroup>
    <Path1>c:\users\</Path1>
    <Path2>c:\users\username\</Path2>
</PropertyGroup>

<Target Name = "Go">
    <Message Text ="$([MSBuild]::MakeRelative($(Path1), $(Path2)))" />
    <Message Text ="$([MSBuild]::MakeRelative($(Path2), $(Path1)))" />
</Target>

<!--
Output:
   username\
   ..\
-->

MSBuild StableStringHash

La fonction de propriété MSBuild StableStringHash accepte un argument de chaîne et retourne un code de hachage garanti stable, ce qui signifie que le même code est toujours retourné pour la même entrée de chaîne. Le hachage retourné est le même, que MSBuild ou dotnet build soit utilisé, et il est stable quelle que soit l'architecture de la plateforme, contrairement à la méthode GetHashCode. Il n’est pas garanti qu’il soit stable entre différentes versions de MSBuild.

Cette fonction est disponible dans MSBuild 16.9.0 ou version ultérieure.

L’exemple suivant montre comment cette fonction est utilisée.

<Project>
   <PropertyGroup>
      <MyHash>$([MSBuild]::StableStringHash("test1"))</MyHash>
   </PropertyGroup>

   <Target Name="WriteHash" AfterTargets="Build">
      <Message Text="Hash: $(MyHash)"/>
   </Target>
</Project>

Avec MSBuild version 17.10 et ultérieures, cette fonction accepte le deuxième argument facultatif demandant l’utilisation de l’algorithme de hachage :

<Project>
   <PropertyGroup>
      <MyHash>$([MSBuild]::StableStringHash("test1", "Sha256"))</MyHash>
   </PropertyGroup>

   <Target Name="WriteHash" AfterTargets="Build">
      <Message Text="Hash: $(MyHash)"/>
   </Target>
</Project>

Le deuxième argument est insensible à la casse et supporte actuellement les valeurs suivantes :

• Legacy – conserve le même comportement qu’en appelant la fonction sans le second argument. Retourne un entier signé 32 bits avec des propriétés similaires à string.GetHashCode.
• Fnv1a32bit : renvoie un entier signé 32 bits représentant un hachage Fowler-Noll-Vo de la version « 1a » de la chaîne donnée.
• Fnv1a64bit - Renvoie un entier signé de 64 bits représentant un hachage Fowler–Noll–Vo hash of version ’1a’ de la chaîne donnée.
• Sha256 : retourne une chaîne hexadécimal non prédéfinie représentant un hachage SHA256 de la chaîne donnée.

Fonction MSBuild ValueOrDefault

La fonction de propriété MSBuild ValueOrDefault retourne le premier argument, sauf s’il est null ou vide. Si le premier argument est null ou vide, la fonction retourne le deuxième argument.

L’exemple suivant montre comment cette fonction est utilisée.

<Project>

    <PropertyGroup>
        <Value1>$([MSBuild]::ValueOrDefault('$(UndefinedValue)', 'a'))</Value1>
        <Value2>$([MSBuild]::ValueOrDefault('b', '$(Value1)'))</Value2>
    </PropertyGroup>

    <Target Name="MyTarget">
        <Message Text="Value1 = $(Value1)" />
        <Message Text="Value2 = $(Value2)" />
    </Target>
</Project>

<!--
Output:
  Value1 = a
  Value2 = b
-->

Fonctions MSBuild TargetFramework et TargetPlatform

MSBuild 16.7 et versions ultérieures définissent plusieurs fonctions pour la gestion des propriétés TargetFramework et TargetPlatform.

Le paramètre versionPartCount de GetTargetFrameworkVersion et GetTargetPlatformVersion a une valeur par défaut de 2.

L’exemple suivant montre comment ces fonctions sont utilisées.

<Project>

    <PropertyGroup>
        <Value1>$([MSBuild]::GetTargetFrameworkIdentifier('net5.0-windows7.0'))</Value1>
        <Value2>$([MSBuild]::GetTargetFrameworkVersion('net5.0-windows7.0'))</Value2>
        <Value3>$([MSBuild]::GetTargetPlatformIdentifier('net5.0-windows7.0'))</Value3>
        <Value4>$([MSBuild]::GetTargetPlatformVersion('net5.0-windows7.0'))</Value4>
        <Value5>$([MSBuild]::IsTargetFrameworkCompatible('net5.0-windows', 'net5.0'))</Value5>
        <Value6>$([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net6.0'))</Value6>
        <Value7>$([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net8.0'))</Value7>
        <Value8>$([MSBuild]::IsTargetFrameworkCompatible('net8.0', 'net6.0'))</Value8>
    </PropertyGroup>

    <Target Name="MyTarget">
        <Message Text="Value1 = $(Value1)" />
        <Message Text="Value2 = $(Value2)" />
        <Message Text="Value3 = $(Value3)" />
        <Message Text="Value4 = $(Value4)" />
        <Message Text="Value5 = $(Value5)" />
        <Message Text="Value6 = $(Value6)" />
        <Message Text="Value7 = $(Value7)" />
        <Message Text="Value8 = $(Value8)" />
    </Target>
</Project>

Value1 = .NETCoreApp
Value2 = 5.0
Value3 = windows
Value4 = 7.0
Value5 = True
Value6 = False
Value7 = False
Value8 = True

Fonctions de comparaison de versions MSBuild

MSBuild 16.5 et versions ultérieures définissent plusieurs fonctions pour comparer des chaînes qui représentent des versions.

Dans ces méthodes, les versions sont analysées comme System.Version, avec les exceptions suivantes :

• Le début v ou V est ignoré, ce qui permet la comparaison avec $(TargetFrameworkVersion).

• Tout ce qui se passe du premier « - » ou « + » à la fin de la chaîne de version est ignoré. Cela permet de passer des versions sémantiques (SemVer), bien que l’ordre ne soit pas le même que SemVer. Au lieu de cela, les spécificateurs de préversion et les métadonnées de build n’ont aucune pondération de tri. Cela peut être utile, par exemple, pour activer une fonctionnalité pour >= x.y et qu'elle s'enclenche sur x.y.z-pre.

• Les parties non spécifiées sont identiques aux parties de valeur zéro. (x == x.0 == x.0.0 == x.0.0.0).

• L’espace blanc n’est pas autorisé dans les composants entiers.

• La version principale est valide uniquement (3 est égale à 3.0.0.0)

• + n’est pas autorisé en tant que signe positif dans les composants entiers (il est traité comme métadonnées semver et ignoré)

Fonctions de condition MSBuild

Les fonctions Exists et HasTrailingSlash ne sont pas des fonctions de propriété. Ils sont disponibles pour une utilisation avec l’attribut Condition . Consultez Conditions MSBuild.

Contenu connexe

• Propriétés de MSBuild

• Vue d’ensemble de MSBuild