Vlastnosti nástroje MSBuild

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é se budou odkazovat v celém souboru projektu.

Definování a odkaz na vlastnosti v souboru projektu

Vlastnosti se deklarují vytvořením elementu, jehož název odpovídá vlastnosti a který je podřízeným prvkem elementu PropertyGroup. Například následující XML 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 ASCII nebo podtržítkem (_); platné následující znaky obsahují alfanumerické znaky (písmena ASCII 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 vlastností lze změnit opětovným definicí vlastnosti. Vlastnost BuildDir může být udělena nová hodnota pomocí tohoto XML:

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

Vlastnosti se vyhodnocují v pořadí, ve kterém se zobrazují v souboru projektu. Nová hodnota BuildDir musí být deklarována po přiřazení staré hodnoty.

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 MSBuild. Na tyto vlastnosti se odkazuje pomocí zápisu $ stejně jako na jakoukoli jinou vlastnost. Například $(MSBuildProjectFile) vrátí úplný název souboru projektu, včetně přípony názvu souboru.

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

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í

Proměnné prostředí můžete odkazovat v souborech projektu stejně jako odkazovat na rezervované vlastnosti. Pokud chcete například použít proměnnou PATH prostředí v souboru projektu, použijte $(Path). Pokud projekt obsahuje definici vlastnosti, která má stejný název jako vlastnost prostředí, vlastnost v projektu přepíše hodnotu proměnné prostředí.

Každý projekt MSBuild má izolovaný blok prostředí: vidí jen čtení a zápisy do vlastního bloku. Nástroj MSBuild čte proměnné prostředí pouze při inicializaci kolekce vlastností před vyhodnocením nebo sestavením souboru projektu. Potom jsou vlastnosti prostředí statické, to znamená, že každý vytvořený nástroj začíná 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 EnvironmentVariablesúkolu . Vlastnosti prostředí nastavené v tomto řetězcovém poli se dají předat do nástroje, který se vytvoří, aniž by to ovlivnilo proměnné systémového prostředí.

Tip

Ne všechny proměnné prostředí se čtou, aby se staly počátečními vlastnostmi. 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 Návod: 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)

Pokud chcete získat výchozí hodnotu podklíče, vynecháte Valuehodnotu .

$(registry:Hive\MyKey\MySubKey)

Tuto hodnotu registru lze použít k inicializaci vlastnosti sestavení. Pokud chcete například vytvořit vlastnost sestavení, která představuje domovskou stránku webového prohlížeče sady Visual Studio, použijte tento kód:

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

Výstraha

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

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

Vlastnosti umístěné mimo Target prvky jsou přiřazeny hodnoty během zkušební fáze sestavení. Během následující fáze provádění lze vlastnosti vytvořit nebo upravit 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 . Toto použ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 globální hodnoty vlastností přepíší hodnoty vlastností, které jsou nastavené v souboru projektu. To zahrnuje vlastnosti prostředí, ale nezahrnuje rezervované vlastnosti, které nelze změnit.

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

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

Globální vlastnosti lze také nastavit nebo upravit pro podřízené projekty v sestavení s více projekty pomocí Properties atributu úlohy 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.props -->
<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): ImportOverrideValue

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

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 můžete použít funkce vlastností k vyhodnocení skriptů MSBuild. Můžete číst systémový čas, porovnávat řetězce, odpovídat regulárním výrazům a provádět mnoho dalších akcí v rámci skriptu sestavení bez použití úloh NÁSTROJE MSBuild.

Pomocí metod string (instance) můžete pracovat s libovolnou hodnotou vlastnosti a můžete volat statické metody mnoha systémových tříd. Vlastnost sestavení můžete například nastavit na dnešní datum následujícím způsobem.

<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 můžou obsahovat libovolný kód XML, který může pomoct s předáváním hodnot úkolům nebo zobrazením informací o protokolování. Následující příklad ukazuje ConfigTemplate vlastnost, která má hodnotu, která obsahuje XML 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í, ve kterém se zobrazují. Proto v tomto příkladu , $(MySupportedVersion), $(MyRequiredVersion)a $(MySafeMode) by již měly být 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

• koncepty nástroje MSBuild
• MSBuild
• Postupy: Použití proměnných prostředí v sestavení
• Postupy: Odkazování na název nebo umístění souboru projektu
• Postupy: Sestavení stejných zdrojových souborů s různými možnostmi
• rezervovaných a známých vlastností nástroje MSBuild
• Property – element (MSBuild)