Sdílet prostřednictvím

Položky nástroje MSBuild

  • Článek

Položky NÁSTROJE MSBuild jsou vstupy do systému sestavení a obvykle představují soubory (soubory jsou zadané v atributu Include ). Položky jsou seskupené do typů položek na základě jejich názvů prvků. Typy položek jsou pojmenované seznamy položek, které lze použít jako parametry pro úkoly. Úkoly používají hodnoty položek k provedení kroků procesu sestavení.

Vzhledem k tomu, že položky jsou pojmenovány podle typu položky, do které patří, lze zaměnitelně termíny "item" a "item value".

Vytvoření položek v souboru projektu

Položky v souboru projektu deklarujete jako podřízené prvky elementu ItemGroup . Platné názvy položek 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 (-). Název podřízeného prvku je typ položky. Atribut Include elementu určuje položky (soubory), které mají být zahrnuty do tohoto typu položky. Například následující XML vytvoří typ položky s názvem Compile, který obsahuje dva soubory.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Položka file2.cs nenahrazuje položku file1.cs; místo toho se název souboru připojí k seznamu hodnot pro Compile typ položky.

Následující xml vytvoří stejný typ položky deklarací obou souborů v jednom Include atributu. Všimněte si, že názvy souborů jsou oddělené středníkem.

<ItemGroup>
    <Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>

Atribut Include je cesta, která je interpretována vzhledem ke složce souboru projektu, i když je položka v importovaném souboru, $(MSBuildProjectPath)jako .targets je soubor.

Vytváření položek během provádění

Položky, které jsou mimo cílové prvky, jsou přiřazeny hodnoty během fáze vyhodnocení sestavení. Během následující fáze provádění lze položky vytvořit nebo upravit následujícími způsoby:

  • Každý úkol může vygenerovat položku. Chcete-li vygenerovat položku, element Task musí mít podřízený výstupní prvek, který má ItemName atribut.

  • Úloha CreateItem může vygenerovat položku. Tento způsob využití je zastaralý.

  • Targetelementy mohou obsahovat elementy ItemGroup, které mohou obsahovat prvky položky.

Odkazy na položky v souboru projektu

Pokud chcete odkazovat na typy položek v celém souboru projektu, použijte syntaxi @(ItemType). Můžete například odkazovat na typ položky v předchozím příkladu pomocí .@(Compile) Pomocí této syntaxe můžete předat položky úkolům zadáním typu položky jako parametru úkolu. Další informace naleznete v tématu Postupy: Výběr souborů, které se mají sestavit.

Ve výchozím nastavení jsou položky typu položky oddělené středníky (;) při rozbalení. Pomocí syntaxe @(ItemType, 'separator') můžete zadat jiný oddělovač než výchozí. Další informace naleznete v tématu Postupy: Zobrazení seznamu položek oddělených čárkami.

Určení položek pomocí zástupných znaků

Pomocí znaků , *a ? zástupných znaků můžete **určit skupinu souborů jako vstupy pro sestavení místo výpisu jednotlivých souborů samostatně.

  • ? Zástupný znak odpovídá jednomu znaku.
  • * Zástupný znak odpovídá nule nebo více znaků.
  • Sekvence ** zástupných znaků odpovídá částečné cestě.

Můžete například zadat všechny .cs soubory v adresáři, který obsahuje soubor projektu pomocí následujícího prvku v souboru projektu.

<CSFile Include="*.cs"/>

Následující prvek vybere všechny .vb soubory na D: jednotce:

<VBFile Include="D:/**/*.vb"/>

Pokud chcete do položky zahrnout literál * nebo ? znaky bez rozšíření zástupných znaků, je nutné utéct zástupnými znaky.

Další informace o zástupných znaménách najdete v tématu Postupy: Výběr souborů, které chcete sestavit.

Použití atributu Exclude

Prvky položky mohou obsahovat Exclude atribut, který vylučuje konkrétní položky (soubory) z typu položky. Atribut Exclude se obvykle používá společně se zástupnými znaky. Například následující XML přidá každý .cs soubor v adresáři k CSFile typu položky s výjimkou DoNotBuild.cs souboru.

<ItemGroup>
    <CSFile  Include="*.cs"  Exclude="DoNotBuild.cs"/>
</ItemGroup>

Atribut Exclude má vliv pouze na položky, které jsou přidány atributem Include v elementu item, který je obsahuje oba. Následující příklad nevyloučí soubor Form1.cs, který byl přidán v předchozím prvku položky.

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

Další informace naleznete v tématu Postupy: Vyloučení souborů z sestavení.

Metadata položek

Položky mohou obsahovat metadata kromě informací v atributechInclude.Exclude Tato metadata můžou používat úkoly, které vyžadují další informace o položkách nebo dávkových úkolech a cílech. Další informace najdete v tématu Dávkování.

Metadata jsou kolekce párů klíč-hodnota, které jsou deklarovány v souboru projektu jako podřízené prvky elementu položky. Název podřízeného elementu je název metadat a hodnota podřízeného prvku je hodnota metadat.

Metadata jsou přidružena k prvku položky, který ho obsahuje. Následující xml například přidá Culture metadata, která mají hodnotu Fr do one.cs i two.cs položek CSFile typu položky.

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Položka může mít nulové nebo více hodnot metadat. Hodnoty metadat můžete kdykoli změnit. Pokud nastavíte metadata na prázdnou hodnotu, efektivně je z sestavení odeberete.

Metadata referenčních položek v souboru projektu

Metadata položek můžete odkazovat v celém souboru projektu pomocí syntaxe %(ItemMetadataName). Pokud existuje nejednoznačnost, můžete kvalifikovat odkaz pomocí názvu typu položky. Můžete například zadat %(ItemType.ItemMetaDataName). Následující příklad používá Display metadata k dávce Message úkolu. Další informace o tom, jak používat metadata položek pro dávkování, naleznete v tématu Metadata položky v dávkování úkolů.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <Stuff Include="One.cs" >
            <Display>false</Display>
        </Stuff>
        <Stuff Include="Two.cs">
            <Display>true</Display>
        </Stuff>
    </ItemGroup>
    <Target Name="Batching">
        <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
    </Target>
</Project>

Známá metadata položek

Když se položka přidá do typu položky, přiřadí se jí některá dobře známá metadata. Například všechny položky mají dobře známá metadata %(Filename), jejichž hodnota je název souboru položky (bez přípony). Další informace najdete v tématu Metadata známých položek.

Transformace typů položek pomocí metadat

Seznamy položek můžete transformovat na nové seznamy položek pomocí metadat. Můžete například transformovat typ CppFiles položky, který obsahuje položky představující .cpp soubory do odpovídajícího .obj seznamu souborů pomocí výrazu @(CppFiles -> '%(Filename).obj').

Následující kód vytvoří CultureResource typ položky, který obsahuje kopie všech EmbeddedResource položek s Culture metadaty. Hodnota Culture metadat se stane hodnotou nových metadat CultureResource.TargetDirectory.

<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
            Condition="'%(EmbeddedResource.Culture)' != ''">
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

Další operace s položkami naleznete v tématu MSBuild item functions and Transforms.

Definice položek

Výchozí metadata můžete přidat do libovolného typu položky pomocí elementu ItemDefinitionGroup. Stejně jako dobře známá metadata jsou výchozí metadata přidružená ke všem položkám zadaného typu položky. Výchozí metadata v definici položky můžete explicitně přepsat. Například následující XML poskytuje Compile položky one.cs a three.cs metadata BuildDay s hodnotou "Pondělí". Kód dává položce two.cs metadata BuildDay s hodnotou "Úterý".

<ItemDefinitionGroup>
    <Compile>
        <BuildDay>Monday</BuildDay>
    </Compile>
</ItemDefinitionGroup>
<ItemGroup>
    <Compile Include="one.cs;three.cs" />
    <Compile Include="two.cs">
        <BuildDay>Tuesday</BuildDay>
    </Compile>
</ItemGroup>

Další informace naleznete v tématu Definice položek.

Atributy pro položky v položce ItemGroup cíle

Targetelementy mohou obsahovat elementy ItemGroup, které mohou obsahovat prvky položky. Atributy v této části jsou platné, pokud jsou zadány pro položku v ItemGroup objektu, který je v objektu Target.

Odebrat atribut

Atribut Remove odebere určité položky (soubory) z typu položky. Tento atribut byl zaveden v rozhraní .NET Framework 3.5 (pouze uvnitř cílů). Vnitřní i vnější cíle se podporují počínaje verzí MSBuild 15.0.

Následující příklad odebere každý .config soubor z Compile typu položky.

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

Atribut MatchOnMetadata

Atribut MatchOnMetadata se vztahuje pouze na Remove atributy, které odkazují na jiné položky (například Remove="@(Compile);@(Content)") a dává operaci pokyn Remove , aby odpovídala položkám na základě hodnot zadaných názvů metadat, a ne na základě hodnot položek.

Odpovídající pravidlo pro B Remove="@(A)" MatchOnMetadata="M": odeberte všechny položky, které B mají metadata M, jejichž hodnota V metadat odpovídá M libovolné položce z A metadat M hodnoty V.

<Project>
  <ItemGroup>
    <A Include='a1' M1='1' M2='a' M3="e"/>
    <A Include='b1' M1='2' M2='x' M3="f"/>
    <A Include='c1' M1='3' M2='y' M3="g"/>
    <A Include='d1' M1='4' M2='b' M3="h"/>

    <B Include='a2' M1='x' m2='c' M3="m"/>
    <B Include='b2' M1='2' m2='x' M3="n"/>
    <B Include='c2' M1='2' m2='x' M3="o"/>
    <B Include='d2' M1='3' m2='y' M3="p"/>
    <B Include='e2' M1='3' m2='Y' M3="p"/>
    <B Include='f2' M1='4'        M3="r"/>
    <B Include='g2'               M3="s"/>

    <B Remove='@(A)' MatchOnMetadata='M1;M2'/>
  </ItemGroup>

  <Target Name="PrintEvaluation">
    <Message Text="%(B.Identity) M1='%(B.M1)' M2='%(B.M2)' M3='%(B.M3)'" />
  </Target>
</Project>

V příkladu hodnoty b2položky , c2a d2 jsou odebrány z položky B , protože:

  • b2a c2 ze zápasu proti A B b1 M1=2M2=x
  • d2ze B shod od M1=3 c1 AM2=y

Úkol Message vypíše následující:

  a2 M1='x' M2='c' M3='m'
  e2 M1='3' M2='Y' M3='p'
  f2 M1='4' M2='' M3='r'
  g2 M1='' M2='' M3='s'

Příklad použití MatchOnMetadata nástroje MSBuild:

      <_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />

Tento řádek odebere položky se _TransitiveItemsToCopyToOutputDirectory stejnými TargetPath hodnotami metadat z položek v _ThisProjectItemsToCopyToOutputDirectory

Atribut MatchOnMetadataOptions

Určuje strategii porovnávání řetězců používanou MatchOnMetadata pro porovnávání hodnot metadat mezi položkami (názvy metadat jsou vždy nerozlišovány malá a velká písmena). Možné hodnoty jsou CaseSensitive, CaseInsensitivenebo PathLike. Výchozí hodnota je CaseSensitive.

PathLike použije normalizaci s podporou cesty na hodnoty, jako je normalizace lomítek, ignorování koncových lomítek, odstranění . a ..a provádění všech relativních cest absolutní vůči aktuálnímu adresáři.

Atribut KeepMetadata

Pokud je položka vygenerována v rámci cíle, prvek item může obsahovat KeepMetadata atribut. Pokud je tento atribut zadán, přenesou se ze zdrojové položky do cílové položky pouze metadata zadaná v seznamu názvů oddělených středníkem. Prázdná hodnota pro tento atribut je ekvivalentní tomu, aby ho nezadávejte. Atribut KeepMetadata byl zaveden v rozhraní .NET Framework 4.5.

Následující příklad ukazuje, jak použít KeepMetadata atribut.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
ToolsVersion="4.0">

    <ItemGroup>
        <FirstItem Include="rhinoceros">
            <Class>mammal</Class>
            <Size>large</Size>
        </FirstItem>

    </ItemGroup>
    <Target Name="MyTarget">
        <ItemGroup>
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
        </ItemGroup>

        <Message Text="FirstItem: %(FirstItem.Identity)" />
        <Message Text="  Class: %(FirstItem.Class)" />
        <Message Text="  Size:  %(FirstItem.Size)"  />

        <Message Text="SecondItem: %(SecondItem.Identity)" />
        <Message Text="  Class: %(SecondItem.Class)" />
        <Message Text="  Size:  %(SecondItem.Size)"  />
    </Target>
</Project>

<!--
Output:
  FirstItem: rhinoceros
    Class: mammal
    Size:  large
  SecondItem: rhinoceros
    Class: mammal
    Size:
-->

Atribut RemoveMetadata

Pokud je položka vygenerována v rámci cíle, prvek item může obsahovat RemoveMetadata atribut. Pokud je tento atribut zadán, všechna metadata se přenesou ze zdrojové položky na cílovou položku s výjimkou metadat, jejichž názvy jsou obsaženy v seznamu názvů oddělených středníkem. Prázdná hodnota pro tento atribut je ekvivalentní tomu, aby ho nezadávejte. Atribut RemoveMetadata byl zaveden v rozhraní .NET Framework 4.5.

Následující příklad ukazuje, jak použít RemoveMetadata atribut.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <PropertyGroup>
        <MetadataToRemove>Size;Material</MetadataToRemove>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)" />
        <Message Text="  Size:     %(Item1.Size)" />
        <Message Text="  Color:    %(Item1.Color)" />
        <Message Text="  Material: %(Item1.Material)" />
        <Message Text="Item2: %(Item2.Identity)" />
        <Message Text="  Size:     %(Item2.Size)" />
        <Message Text="  Color:    %(Item2.Color)" />
        <Message Text="  Material: %(Item2.Material)" />
    </Target>
</Project>

<!--
Output:
  Item1: stapler
    Size:     medium
    Color:    black
    Material: plastic
  Item2: stapler
    Size:
    Color:    black
    Material:
-->

Další operace s položkami naleznete v tématu MSBuild item functions.

Atribut KeepDuplicates

Pokud je položka vygenerována v rámci cíle, prvek item může obsahovat KeepDuplicates atribut. KeepDuplicatesBoolean je atribut, který určuje, zda má být položka přidána do cílové skupiny, pokud je položka přesnou duplikát existující položky.

Pokud zdroj a cílová položka mají stejnou Include hodnotu, ale různá metadata, přidá se položka i v případě, že KeepDuplicates je nastavena na falsehodnotu . Prázdná hodnota pro tento atribut je ekvivalentní tomu, aby ho nezadávejte. Atribut KeepDuplicates byl zaveden v rozhraní .NET Framework 4.5.

Následující příklad ukazuje, jak použít KeepDuplicates atribut.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <Item1 Include="hourglass;boomerang" />
        <Item2 Include="hourglass;boomerang" />
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item1 Include="hourglass" KeepDuplicates="false" />
            <Item2 Include="hourglass" />
        </ItemGroup>

        <Message Text="Item1: @(Item1)" />
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />
        <Message Text="Item2: @(Item2)" />
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />
    </Target>
</Project>

<!--
Output:
  Item1: hourglass;boomerang
    hourglass  Count: 1
    boomerang  Count: 1
  Item2: hourglass;boomerang;hourglass
    hourglass  Count: 2
    boomerang  Count: 1
-->

KeepDuplicates Vzhledem k tomu, že atribut považuje metadata položek kromě hodnot položek, je důležité vědět, co se děje s metadaty. Podívejte se například na zjištění duplicit při použití funkce položky metadat.

Aktualizace metadat u položek ve skupině Položek mimo cíl

Položky mimo cíle můžou mít stávající metadata aktualizovaná prostřednictvím atributu Update . Tento atribut není k dispozici pro položky v rámci cílů.

<Project>
    <PropertyGroup>
        <MetadataToUpdate>pencil</MetadataToUpdate>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Color>red</Color>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="notebook">
            <Size>SMALL</Size>
            <Color>YELLOW</Color>
        </Item2>

        <!-- Metadata can be expressed either as attributes or as elements -->
        <Item1 Update="$(MetadataToUpdate);stapler;er*r;@(Item2)" Price="10" Material="">
            <Color>RED</Color>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: medium
    Color: RED
    Material:
    Price: 10
Item1: pencil
    Size: small
    Color: RED
    Material:
    Price: 10
Item1: eraser
    Size:
    Color: RED
    Material:
    Price: 10
Item1: notebook
    Size: large
    Color: RED
    Material:
    Price: 10
-->

V msBuild verze 16.6 a novější Update podporuje atribut kvalifikované odkazy na metadata pro usnadnění importu metadat ze dvou nebo více položek.

<Project>
    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Size>small</Size>
            <Color>red</Color>
            <Material>gum</Material>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="pencil">
            <Size>MEDIUM</Size>
            <Color>RED</Color>
            <Material>PLASTIC</Material>
            <Price>10</Price>
        </Item2>

        <Item3 Include="notebook">
            <Size>SMALL</Size>
            <Color>BLUE</Color>
            <Price>20</Price>
        </Item3>

        <!-- Metadata can be expressed either as attributes or as elements -->
        <Item1 Update="@(Item2);er*r;@(Item3)" Size="%(Size)" Color="%(Item2.Color)" Price="%(Item3.Price)" Model="2020">
            <Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)
    Model: %(Item1.Model)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: medium
    Color: black
    Material: plastic
    Price:
    Model:
Item1: pencil
    Size: small
    Color: RED
    Material: Premium PLASTIC
    Price:
    Model: 2020
Item1: eraser
    Size: small
    Color:
    Material: gum
    Price:
    Model: 2020
Item1: notebook
    Size: large
    Color:
    Material: paper
    Price: 20
    Model: 2020
-->

Poznámky:

  • Nekvalifikovaná metadata (%(MetadataName)) se sváže s aktualizovaným typem položky (Item1 v předchozím příkladu). Kvalifikovaná metadata (%(Item2.Color)) se sváže uvnitř sady zachycených odpovídajících typů položek z výrazu Update.
  • Pokud položka odpovídá vícekrát uvnitř a mezi více odkazovanými položkami:
    • Poslední výskyt každého odkazovaného typu položky se zachytí (takže jedna zachycená položka na typ položky).
    • Odpovídá chování položek úkolů v dávkách v cílech.
  • Kde lze vložit odkazy %():
    • Metadata
    • Podmínky metadat
  • Porovnávání názvů metadat nerozlišuje malá a velká písmena.

Aktualizace metadat u položek ve skupině položek cíle

Metadata je možné upravovat i uvnitř cílů, a to méně výraznou syntaxí než Update:

<Project>
    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Size>small</Size>
            <Color>red</Color>
            <Material>gum</Material>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="pencil">
            <Size>MEDIUM</Size>
            <Color>RED</Color>
            <Material>PLASTIC</Material>
            <Price>10</Price>
        </Item2>

        <Item2 Include="ruler">
            <Color>GREEN</Color>
        </Item2>

    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <!-- Metadata can be expressed either as attributes or as elements -->
            <Item1 Size="GIGANTIC" Color="%(Item2.Color)">
                <Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
            </Item1>
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)
    Model: %(Item1.Model)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: pencil
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: eraser
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: notebook
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
-->

Související obsah