Propriétés MSBuild
Les propriétés sont des paires nom-valeur qui peuvent être utilisées pour configurer les builds. Elles sont utiles pour passer des valeurs aux tâches, évaluer des conditions et stocker des valeurs qui seront référencées dans tout le fichier projet.
Définition et référence de propriétés dans un fichier projet
Les propriétés sont déclarées en créant un élément portant le nom de la propriété comme enfant d'un élément PropertyGroup. Par exemple, le code XML suivant crée une propriété nommée BuildDir avec la valeur Build.
<PropertyGroup>
<BuildDir>Build</BuildDir>
</PropertyGroup>
Dans la totalité du fichier projet, les propriétés sont référencées à l'aide de la syntaxe $(PropertyName). Par exemple, dans l'exemple précédent, la propriété est référencée à l'aide de $(BuildDir).
Vous pouvez modifier les valeurs de propriété en redéfinissant la propriété. Une nouvelle valeur peut être attribuée à la propriété BuildDir à l'aide du code XML suivant :
<PropertyGroup>
<BuildDir>Alternate</BuildDir>
</PropertyGroup>
Les propriétés sont évaluées dans l'ordre dans lequel elles apparaissent dans le fichier projet. La nouvelle valeur de BuildDir doit être déclarée après que l'ancienne valeur a été assignée.
Propriétés réservées
MSBuild réserve certains noms de propriétés pour stocker des informations sur le fichier projet et les fichiers binaires MSBuild. Ces propriétés sont référencées avec la notation $, comme toute autre propriété. Par exemple, $(MSBuildProjectFile) retourne le nom de fichier complet du fichier projet, y compris l'extension de nom de fichier.
Pour plus d’informations, consultez Comment : référencer le nom ou l'emplacement du fichier projet et MSBuild, propriétés réservées et connues.
Propriétés d'environnement
Vous pouvez référencer les variables d'environnement des fichiers projet comme vous le feriez pour les propriétés réservées. Par exemple, pour utiliser la variable d'environnement PATH dans votre fichier projet, utilisez $(Path). Si le projet contient une définition de propriété qui a le même nom qu'une propriété d'environnement, la propriété du projet substitue la valeur de la variable d'environnement.
Chaque projet MSBuild a un bloc d'environnement isolé : il visualise seulement les lectures et écrits de ses propres bloc. MSBuild lit uniquement des variables d'environnement lorsqu'il initialise la collection de propriétés, avant que le fichier projet soit évalué ou généré. Ensuite, les propriétés d'environnement sont statiques. Autrement dit, chaque outil engendré commence avec les mêmes noms et les valeurs.
Pour obtenir la valeur actuelle des variables d'environnement depuis un outil engendré, utilisez Fonctions de propriété System.Environment.GetEnvironmentVariable. La méthode recommandée, toutefois, est d'utiliser le paramètre de tâche EnvironmentVariables. Les propriétés d'environnement dans ce tableau de chaînes peuvent être passées à l'outil engendré sans affecter les variables d'environnement du système.
Conseil
Toutes les variables d'environnement ne sont pas lues pour devenir des propriétés initiales.Toute variable d'environnement dont le nom n'est pas un nom de propriété MSBuild valide, tels que « 386 ", est ignorée.
Pour plus d'informations, consultez Comment : utiliser des variables d'environnement dans une génération.
Propriétés relatives au Registre
Vous pouvez lire les valeurs du Registre système à l'aide de la syntaxe suivante, où Hive est la ruche de Registre (par exemple, HKEY_LOCAL_MACHINE), Key le nom de la clé, SubKey le nom de la sous-clé et Value la valeur de la sous-clé.
$(registry:Hive\MyKey\MySubKey@Value)
Pour obtenir la valeur de la sous-clé par défaut, omettez Value.
$(registry:Hive\MyKey\MySubKey)
Cette valeur de Registre peut être utilisée pour initialiser une propriété de build. Par exemple, pour créer une propriété de build qui représente la page d'accueil de navigateur Web Visual Studio, utilisez le code suivant :
<PropertyGroup>
<VisualStudioWebBrowserHomePage>
$(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0\WebBrowser@HomePage)
</VisualStudioWebBrowserHomePage>
<PropertyGroup>
Propriétés globales
MSBuild vous permet de définir des propriétés sur les lignes de commandes en utilisant le commutateur /property ( ou /p ). Ces valeurs de propriété globales substituent les valeurs de propriété définies dans le fichier projet. Sont concernées les propriétés d'environnement, mais pas les propriétés réservées, qui ne peuvent pas être modifiées.
L'exemple suivant affecte à la propriété globale Configuration la valeur DEBUG.
msbuild.exe MyProj.proj /p:Configuration=DEBUG
Vous pouvez également définir ou modifier les propriétés globales pour les projets enfants dans une build à projets multiples en utilisant l'attribut Properties de la tâche MSBuild. Pour plus d'informations, consultez MSBuild, tâche.
Si vous spécifiez une propriété en utilisant l'attribut TreatAsLocalProperty dans une balise de projet, cette valeur de propriété globale n'outrepasse pas la valeur de propriété définie dans le fichier projet. Pour plus d’informations, consultez Project, élément (MSBuild) et Comment : générer les mêmes fichiers sources avec des options différentes.
Fonctions de propriété
À partir de .NET Framework version 4, vous pouvez utiliser des fonctions de propriété pour évaluer vos scripts MSBuild. Vous pouvez lire l'heure système, comparer des chaînes, rechercher des expressions régulières et exécuter de nombreuses autres actions dans votre script de compilation sans utiliser de tâches MSBuild.
Vous pouvez utiliser des méthodes (instances) de chaîne sur n'importe quelle valeur de propriété, et vous pouvez appeler les méthodes statiques de nombreuses classes de système. Par exemple, vous pouvez affecter la date du jour à une propriété de build comme suit :
<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>
Pour obtenir plus d'informations et la liste des fonctions de propriété, consultez Fonctions de propriété.
Création de propriétés pendant l'exécution
Des valeurs sont assignées aux propriétés positionnées en dehors des éléments Target pendant la phase d'évaluation d'une build. Pendant la phase d'exécution suivante, des propriétés peuvent être créées ou modifiées comme suit :
Une propriété peut être émise par n'importe quelle tâche. Pour émettre une propriété, l'élément Task doit avoir un élément enfant Output ayant un attribut PropertyName.
Une propriété peut être émise par la tâche CreateProperty. Cette utilisation est déconseillée.
À compter de .NET Framework 3.5, les éléments Target peuvent contenir des éléments PropertyGroup qui peuvent contenir des déclarations de propriété.
Stockage de XML dans les propriétés
Les propriétés peuvent contenir un code XML arbitraire, qui peut aider à passer des valeurs aux tâches ou à afficher des informations d'enregistrement. L'exemple suivant affiche la propriété ConfigTemplate avec une valeur contenant du code XML et d'autres références de propriété. MSBuild remplace les références de propriété par leurs valeurs de propriété respectives. Les valeurs de propriété sont assignées dans l'ordre dans lequel elles s'affichent. Par conséquent, dans cet exemple, $(MySupportedVersion), $(MyRequiredVersion) et $(MySafeMode) doivent avoir été déjà définis.
<PropertyGroup>
<ConfigTemplate>
<Configuration>
<Startup>
<SupportedRuntime
ImageVersion="$(MySupportedVersion)"
Version="$(MySupportedVersion)"/>
<RequiredRuntime
ImageVersion="$(MyRequiredVersion)
Version="$(MyRequiredVersion)"
SafeMode="$(MySafeMode)"/>
</Startup>
</Configuration>
</ConfigTemplate>
</PropertyGroup>
Voir aussi
Tâches
Comment : utiliser des variables d'environnement dans une génération
Comment : référencer le nom ou l'emplacement du fichier projet
Comment : générer les mêmes fichiers sources avec des options différentes
Référence
MSBuild, propriétés réservées et connues