Partager via

Propriétés MSBuild

Les propriétés sont des paires nom-valeur qui peuvent être utilisées pour configurer des builds. Les propriétés sont utiles pour transmettre des valeurs à des tâches, évaluer des conditions et stocker des valeurs qui seront référencées dans le fichier projet.

Définir et référencer des propriétés dans un fichier projet

Les propriétés sont déclarées en créant un élément qui a le nom de la propriété en tant qu’enfant d’un élément PropertyGroup. Par exemple, le code XML suivant crée une propriété nommée BuildDir qui a la valeur Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Les noms de propriétés valides commencent par une lettre ASCII majuscule ou minuscule ou un trait de soulignement (_) ; les caractères suivants valides incluent des caractères alphanumériques (lettres OU chiffres ASCII), un trait de soulignement et un trait d’union (-).

Dans le fichier projet, les propriétés sont référencées à l’aide de la syntaxe $(<PropertyName>). Par exemple, la propriété de l’exemple précédent est référencée à l’aide $(BuildDir)de .

Les valeurs de propriété peuvent être modifiées en redéfinissant la propriété. La BuildDir propriété peut recevoir une nouvelle valeur à l’aide de ce code XML :

<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 pour BuildDir laquelle doit être déclarée après l’attribution de l’ancienne valeur.

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 à l’aide de la notation $, comme n’importe quelle 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 Guide pratique pour référencer le nom ou l’emplacement du fichier projet et Propriétés réservées et connues de MSBuild.

Propriétés internes MSBuild

Les propriétés définies dans les fichiers d’importation standard commençant par un trait de soulignement (_) sont privées dans MSBuild et ne doivent pas être lues, réinitialisées ou remplacées dans le code utilisateur.

Propriétés de l’environnement

Vous pouvez référencer des variables d’environnement dans des fichiers projet tout comme vous référencez des propriétés réservées. Par exemple, pour utiliser la PATH variable d’environnement dans votre fichier projet, utilisez $(Path). Si le projet contient une définition de propriété portant le même nom qu’une propriété d’environnement, la propriété du projet remplace la valeur de la variable d’environnement.

Chaque projet MSBuild a un bloc d’environnement isolé : il voit uniquement les lectures et les écritures dans son propre bloc. MSBuild lit uniquement les variables d’environnement lorsqu’elle initialise la collection de propriétés, avant que le fichier projet soit évalué ou généré. Après cela, les propriétés d’environnement sont statiques, autrement dit, chaque outil généré commence par les mêmes noms et valeurs.

Pour obtenir la valeur actuelle des variables d’environnement à partir d’un outil généré, utilisez les fonctions de propriété System.Environment.GetEnvironmentVariable. Toutefois, la méthode préférée consiste à utiliser le paramètre EnvironmentVariablesde tâche. Les propriétés d’environnement définies dans ce tableau de chaînes peuvent être transmises à l’outil généré sans affecter les variables d’environnement système.

Conseil / Astuce

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, tel que « 386 », est ignorée.

Pour plus d’informations, consultez Comment utiliser des variables d'environnement dans une build.

Propriétés du Registre

Vous pouvez lire les valeurs du Registre système à l’aide de la syntaxe suivante, où Hive se trouve la ruche du Registre (par exemple, HKEY_LOCAL_MACHINE), MyKey est le nom de clé, MySubKey le nom de sous-clé et Value la valeur de la sous-clé.

$(registry:Hive\MyKey\MySubKey@Value)

Pour obtenir la valeur de sous-clé par défaut, omettez la Valuevaleur .

$(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 du navigateur web Visual Studio, utilisez ce code :

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Avertissement

Dans la version du Kit de développement logiciel (SDK) .NET de MSBuild (dotnet build), les propriétés du Registre ne sont pas prises en charge.

Créer des propriétés pendant l’exécution

Les propriétés placées en dehors Target des éléments sont affectées aux valeurs pendant la phase d’évaluation d’une build. Pendant la phase d’exécution suivante, les 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 Output enfant qui a un PropertyName attribut.

  • Une propriété peut être émise par la tâche CreateProperty . Cette utilisation est déconseillée.

  • Target les éléments peuvent contenir des PropertyGroup éléments qui peuvent contenir des déclarations de propriété.

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 remplacent les valeurs de propriété définies dans le fichier projet. Cela inclut les propriétés d’environnement, mais n’inclut pas les propriétés réservées, qui ne peuvent pas être modifiées.

L’exemple suivant définit la propriété globale Configuration sur DEBUG.

msbuild.exe MyProj.proj -p:Configuration=DEBUG

Les propriétés globales peuvent également être définies ou modifiées pour les projets enfants dans une build multi-projet à l’aide de l’attribut Properties de la tâche MSBuild. Les propriétés globales sont également transférées vers des projets enfants, sauf si l’attribut RemoveProperties de la tâche MSBuild est utilisé pour spécifier la liste des propriétés à transférer. Pour plus d’informations, consultez la tâche MSBuild.

Propriétés locales

Les propriétés locales peuvent être réinitialisées dans un projet. Les propriétés globales ne peuvent pas. Lorsqu’une propriété locale est définie à partir de la ligne de commande avec l’option -p , le paramètre du fichier projet est prioritaire sur la ligne de commande.

Vous spécifiez une propriété locale à l’aide de l’attribut TreatAsLocalProperty dans une balise de projet.

Le code suivant spécifie que deux propriétés sont locales :

<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">

Les propriétés locales ne sont pas transférées aux projets enfants dans une build multi-projet. Si vous fournissez une valeur sur la ligne de commande avec l’option -p , les projets enfants reçoivent la valeur de la propriété globale au lieu de la valeur locale modifiée dans le projet parent, mais le projet enfant (ou l’une de ses importations) peut également le modifier avec son propre TreatAsLocalPropertyprojet.

Exemple avec des propriétés locales

L’exemple de code suivant illustre l’effet de TreatAsLocalProperty:

<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
    </Target>

    <Target Name="Go2" BeforeTargets="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <Target Name="Go2">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

Supposons que vous générez la ligne de commande test1.proj et donnez TreatedAsLocalProperty la valeur GlobalOverrideValueglobale :

dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue

La sortie est la suivante :

test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue

Le projet enfant hérite de la valeur globale, mais le projet parent utilise la propriété set localement.

Propriétés et importations locales

Lorsque TreatAsLocalProperty l’attribut est utilisé sur le projet importé, l’ordre est important lors de la prise en compte de la valeur que la propriété obtient.

L’exemple de code suivant montre l’effet d’un TreatAsLocalProperty projet importé :

<!-- importer.proj -->
<Project>
    <PropertyGroup>
        <TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Import Project="import.props" />

    <PropertyGroup>
        <TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- import.props -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>

Supposons que vous générez importer.proj et définissez une valeur globale comme TreatedAsLocalProp suit :

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue

La sortie est la suivante :

importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): ImportOverrideValue

Supposons maintenant que vous générez avec la propriété TrySecondOverride pour true:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true

La sortie est la suivante :

importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue

L’exemple montre que la propriété est traitée comme locale après le projet importé où l’attribut TreatAsLocalProperty a été utilisé, pas seulement dans le fichier importé. La valeur de la propriété est affectée par la valeur de remplacement globale, mais uniquement avant le projet importé où TreatAsLocalProperty il est utilisé.

Pour plus d’informations, consultez l’élément Project (MSBuild) et How to : Build the same source files with different options.

Fonctions de propriété

À compter 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 les chaînes, faire correspondre les expressions régulières et effectuer de nombreuses autres actions dans votre script de génération sans utiliser de tâches MSBuild.

Vous pouvez utiliser des méthodes de chaîne (instance) pour fonctionner sur n’importe quelle valeur de propriété, et vous pouvez appeler les méthodes statiques de nombreuses classes système. Par exemple, vous pouvez définir une propriété de build sur la date d’aujourd’hui comme suit.

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

Pour plus d’informations et une liste de fonctions de propriété, consultez Fonctions de propriété.

Stocker du code XML dans les propriétés

Les propriétés peuvent contenir du code XML arbitraire, qui peut aider à transmettre des valeurs à des tâches ou à afficher des informations de journalisation. L’exemple suivant montre la ConfigTemplate propriété, qui a une valeur qui contient des références XML et d’autres propriétés. MSBuild remplace les références de propriété à l’aide de leurs valeurs de propriété respectives. Les valeurs de propriété sont affectées dans l’ordre dans lequel elles apparaissent. Par conséquent, dans cet exemple, $(MySupportedVersion), $(MyRequiredVersion)et $(MySafeMode) doit déjà avoir été défini.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)"
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

Contenu connexe

  • Last updated on