vlastnosti nástroje MSBuild

  • Článek

Vlastnosti jsou páry název-hodnota, které lze použít ke konfiguraci sestavení. Vlastnosti jsou užitečné pro předávání hodnot úkolům, vyhodnocování podmínek a ukládání hodnot, na které bude odkazováno v celém souboru projektu.

Definování a odkaz na vlastnosti v souboru projektu

Vlastnosti jsou deklarovány vytvořením elementu, který má název vlastnosti jako podřízený element PropertyGroup . Například následující XML kód vytvoří vlastnost s názvem BuildDir, která má hodnotu Build.

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

Platné názvy vlastností začínají velkými nebo malými písmeny nebo podtržítkem (_); platné následující znaky obsahují alfanumerické znaky (písmena nebo číslice), podtržítko a pomlčku (-).

V celém souboru projektu jsou vlastnosti odkazovány pomocí syntaxe $(<PropertyName>). Například vlastnost v předchozím příkladu je odkazována pomocí .$(BuildDir)

Hodnoty vlastnosti lze změnit předefinováním vlastnosti. Vlastnost BuildDir může dostat novou hodnotu pomocí tohoto XML kódu:

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

Vlastnosti jsou vyhodnocovány v pořadí, v jakém jsou uvedeny v souboru projektu. Novou hodnotu pro vlastnost BuildDir je třeba deklarovat poté, co je původní hodnota přiřazena.

Rezervované vlastnosti

Nástroj MSBuild si vyhrazuje některé názvy vlastností pro ukládání informací o souboru projektu a binárních souborech NÁSTROJE MSBuild. Na tyto vlastnosti i jakékoli jiné vlastnosti je odkazováno pomocí zápisu $. Například syntaxe $(MSBuildProjectFile) vrátí celý název souboru projektu, včetně přípony názvu souboru.

Další informace naleznete v tématu Postupy: Odkazování na název nebo umístění souboru projektu a MSBuild rezervované a dobře známé vlastnosti.

Interní vlastnosti nástroje MSBuild

Vlastnosti definované ve standardních souborech importu, které začínají podtržítkem (_), jsou pro NÁSTROJ MSBuild soukromé a neměly by se číst, resetovat ani přepisovat v uživatelském kódu.

Vlastnosti prostředí

V souborech projektu je možné odkazovat na proměnné prostředí stejným způsobem jako na rezervované vlastnosti. Například pro použití proměnné prostředí PATH v souboru projektu je třeba použít příkaz $(Path). Obsahuje-li projekt definici vlastnosti stejného názvu jako vlastnost prostředí, přepíše vlastnost v projektu hodnotu proměnné prostředí.

Každý projekt MSBuild má blok izolovaného prostředí, a tedy vidí, čte a zapisuje pouze do svého vlastního bloku. Nástroj MSBuild načítá proměnné prostředí pouze při inicializaci kolekce vlastností a předtím, než je soubor projektu vyhodnocen nebo sestaven. Poté jsou vlastnosti prostředí statické, a tedy každý vytvořený nástroj je spuštěn se stejnými názvy a hodnotami.

Pokud chcete získat aktuální hodnotu proměnných prostředí z vytvářeného nástroje, použijte funkce vlastností System.Environment.GetEnvironmentVariable. Upřednostňovanou metodou je však použití parametru úkolu EnvironmentVariables. Vlastnosti prostředí nastavené v tomto poli řetězců mohou být předány vytvořenému nástroji bez ovlivnění systémových proměnných prostředí.

Tip

Ne všechny proměnné prostředí jsou čteny pro potřeby počátečních vlastností. Jakákoli proměnná prostředí, jejíž název není platným názvem vlastnosti NÁSTROJE MSBuild, například "386", se ignoruje.

Další informace najdete v tématu Postupy: Použití proměnných prostředí v sestavení.

Vlastnosti registru

Hodnoty systémového registru můžete číst pomocí následující syntaxe, kde Hive je podregistr registru (například HKEY_LOCAL_MACHINE), MyKey je název klíče, MySubKey je název podklíče a Value je hodnota podklíče.

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

Chcete-li získat výchozí hodnotu podklíče, je třeba vynechat Value.

$(registry:Hive\MyKey\MySubKey)

Tato hodnota registru může sloužit k inicializaci vlastnosti sestavení. Například pro vytvoření vlastnosti sestavení, která představuje domovskou stránku webového prohlížeče sady Visual Studio, je třeba použít tento kód:

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

Upozorňující

Ve verzi sady .NET SDK nástroje MSBuild (dotnet build) nejsou podporované vlastnosti registru.

Vytváření vlastností během provádění

Vlastnostem umístěným mimo prvky Target jsou přiřazeny hodnoty během fáze vyhodnocení sestavení. Během následující fáze vykonávání mohou být vlastnosti vytvořeny nebo upraveny následujícím způsobem:

  • Vlastnost může být generována libovolným úkolem. Chcete-li vygenerovat vlastnost, element Task musí mít podřízený výstupní prvek, který má PropertyName atribut.

  • Vlastnost může být generována úlohou CreateProperty . Tento způsob využití je zastaralý.

  • Target elementy mohou obsahovat prvky, které mohou obsahovat PropertyGroup deklarace vlastností.

Globální vlastnosti

Nástroj MSBuild umožňuje nastavit vlastnosti na příkazovém řádku pomocí přepínače -property (nebo -p). Tyto hodnoty globálních vlastností přepisují hodnoty vlastností, které jsou nastaveny v souboru projektu. To zahrnuje vlastnosti prostředí, ale nezahrnuje rezervované vlastnosti, které nelze změnit.

Následující příklad nastavuje globální vlastnost Configuration na DEBUG.

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

Globální vlastnosti je také možné nastavit nebo upravit pro podřízené projekty v sestaveních s více projekty pomocí atributu Properties úkolu MSBuild. Globální vlastnosti se také předávají podřízeným projektům, pokud RemoveProperties se atribut úlohy MSBuild nepoužívá k určení seznamu vlastností, které se nemají předávat. Další informace naleznete v tématu MSBuild úloha.

Místní vlastnosti

Místní vlastnosti je možné resetovat v projektu. Globální vlastnosti nelze. Pokud je z příkazového řádku nastavena místní vlastnost s -p možností, má nastavení v souboru projektu přednost před příkazovým řádkem.

Místní vlastnost zadáte pomocí atributu TreatAsLocalProperty ve značce projektu.

Následující kód určuje, že dvě vlastnosti jsou místní:

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

Místní vlastnosti nejsou předány podřízeným projektům v sestavení s více projekty. Pokud zadáte hodnotu na příkazovém řádku s -p možností, podřízeným projektům se místo místní hodnoty změněné v nadřazeným projektu udělí hodnota globální vlastnosti, ale podřízený projekt (nebo kterýkoli z jeho importů) ho může také změnit vlastním TreatAsLocalProperty.

Příklad s místními vlastnostmi

Následující příklad kódu ukazuje účinek 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>

Předpokládejme, že sestavíte příkazový řádek test1.proj a dáte TreatedAsLocalProperty globální hodnotu GlobalOverrideValue:

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

Výstup je následující:

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

Podřízený projekt dědí globální hodnotu, ale nadřazený projekt používá místně nastavenou vlastnost.

Místní vlastnosti a importy

Při TreatAsLocalProperty použití atributu v importovaném projektu je pořadí důležité při zvažování hodnoty, kterou vlastnost získá.

Následující příklad kódu ukazuje účinek TreatAsLocalProperty na importovaný projekt:

<!-- 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.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

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

Předpokládejme, že sestavíte importer.proj a nastavíte globální hodnotu TreatedAsLocalProp následujícím způsobem:

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

Výstup je:

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

Teď předpokládejme, že sestavíte s vlastností TrySecondOverride true:

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

Výstup je:

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

Příklad ukazuje, že vlastnost je považována za místní po importovaném projektu, ve kterém TreatAsLocalProperty byl atribut použit, nikoli pouze v rámci importovaného souboru. Hodnota vlastnosti je ovlivněna hodnotou globálního přepsání, ale pouze před importovaným projektem, kde TreatAsLocalProperty se používá.

Další informace naleznete v tématu Element projektu (MSBuild) a Postupy: Sestavení stejných zdrojových souborů s různými možnostmi.

Funkce vlastností

Počínaje rozhraním .NET Framework verze 4 je možné použít funkce vlastností k vyhodnocení skriptů nástroje MSBuild. Ve skriptu sestavení je možné přečíst systémový čas, porovnat řetězce, porovnat regulární výrazy a provádět mnoho dalších akcí bez použití úkolů nástroje MSBuild.

Je možné použít metody řetězců (instance) na jakoukoli hodnotu vlastnosti a je možné volat statické metody mnoha systémových tříd. Například je takto možné nastavit vlastnost sestavení na dnešní datum.

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

Další informace a seznam funkcí vlastností naleznete v tématu Funkce vlastností.

Uložení XML ve vlastnostech

Vlastnosti mohou obsahovat libovolný XML kód, který může pomoci při předávání hodnot úkolům nebo zobrazení informací o protokolování. Následující příklad ukazuje vlastnost ConfigTemplate, která má hodnotu obsahující XML kód a další odkazy na vlastnosti. NÁSTROJ MSBuild nahrazuje odkazy na vlastnosti pomocí příslušných hodnot vlastností. Hodnoty vlastností jsou přiřazeny v pořadí, v jakém jsou uvedeny. Proto by v tomto příkladu již měly být hodnoty $(MySupportedVersion), $(MyRequiredVersion) a $(MySafeMode) definovány.

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

Související obsah