Propriétés MSBuild

Article
03/04/2013

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

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 voit uniquement des lectures et les écrit dans son propre bloc.MSBuild lit uniquement des variables d'environnement lorsqu'il initialise la collection de propriétés, avant que le fichier projet est évalué ou généré.Ensuite, les propriétés d'environnement sont statiques, c. autrement dit., démarre engendrés de chaque outil avec les mêmes noms et valeurs.

Pour obtenir la valeur actuelle des variables d'environnement d'un outil engendré, utilisez Fonctions de propriété System.Environment.GetEnvironmentVariable.La méthode recommandée, toutefois, est d'utiliser le paramètre EnvironmentVariablesde tâche.Les propriétés d'environnement définies dans cette table de chaînes peuvent être passées à l'outil engendré sans affecter les variables d'environnement système.

Conseil
Toutes les variables d'environnement sont lues dans pour devenir les propriétés initiales.Toute variable d'environnement dont le nom n'est pas les noms de propriété valides MSBuild, 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\11.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Propriétés globales

MSBuild vous permet de définir des propriétés sur la ligne de commande à l'aide du 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é à l'aide de l'attribut d' TreatAsLocalProperty dans une balise de projet, cette valeur de propriété globale ne substitue pas la valeur de propriété qui est 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é

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

Partager via