Dela via

MSBuild-objekt

MSBuild-objekt är indata i byggsystemet, och de representerar vanligtvis filer (filerna anges i Include attributet). Objekt grupperas i objekttyper baserat på deras elementnamn. Objekttyper är namngivna listor över objekt som kan användas som parametrar för aktiviteter. Uppgifterna använder objektvärdena för att utföra stegen i byggprocessen.

Eftersom objekt namnges efter den objekttyp som de tillhör kan termerna "item" och "item value" användas omväxlande.

Skapa objekt i en projektfil

Du deklarerar objekt i projektfilen som underordnade element i ett ItemGroup-element . Giltiga objektnamn börjar med versaler eller gemener eller understreck (_); giltiga efterföljande tecken innehåller alfanumeriska tecken (bokstäver eller siffror), understreck och bindestreck (-). Namnet på det underordnade elementet är objektets typ. Elementets Include attribut anger vilka objekt (filer) som ska ingå i den objekttypen. Följande XML skapar till exempel en objekttyp med namnet Compile, som innehåller två filer.

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

Objektet file2.cs ersätter inte objektet file1.cs. I stället läggs filnamnet till i listan med värden för Compile objekttypen.

Följande XML skapar samma objekttyp genom att deklarera båda filerna i ett Include attribut. Observera att filnamnen avgränsas med ett semikolon.

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

Attributet Include är en sökväg som tolkas i förhållande till projektfilens mapp, $(MSBuildProjectPath), även om objektet finns i en importerad fil, till exempel en .targets fil.

Skapa objekt under körning

Objekt som ligger utanför Målelement tilldelas värden under utvärderingsfasen av en version. Under den efterföljande körningsfasen kan objekt skapas eller ändras på följande sätt:

  • Alla aktiviteter kan generera ett objekt. Om du vill generera ett objekt måste aktivitetselementet ha ett underordnat utdataelement som har ett ItemName attribut.

  • Uppgiften CreateItem kan generera ett objekt. Den här användningen är inaktuell.

  • Target element kan innehålla ItemGroup-element som kan innehålla objektelement.

Referensobjekt i en projektfil

Om du vill referera till objekttyper i hela projektfilen använder du syntaxen @(ItemType). Du kan till exempel referera till objekttypen i föregående exempel med hjälp @(Compile)av . Genom att använda den här syntaxen kan du skicka objekt till aktiviteter genom att ange objekttypen som en parameter för aktiviteten. Mer information finns i Så här: Välj de filer som ska skapas.

Som standard avgränsas objekten av en objekttyp med semikolon (;) när de expanderas. Du kan använda syntaxen @(ItemType, 'separator') för att ange en annan avgränsare än standardvärdet. Mer information finns i Så här: Visa en objektlista avgränsad med kommatecken.

Använda jokertecken för att ange objekt

Du kan använda **tecknen , *och ? jokertecken för att ange en grupp filer som indata för en version i stället för att visa varje fil separat.

  • Jokertecknet ? matchar ett enskilt tecken.
  • Jokertecknet * matchar noll eller fler tecken.
  • Jokerteckensekvensen ** matchar en partiell sökväg.

Du kan till exempel ange alla .cs filer i katalogen som innehåller projektfilen med hjälp av följande element i projektfilen.

<CSFile Include="*.cs"/>

Följande element markerar alla .vb filer på D: enheten:

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

Om du vill inkludera literaltecken * eller ? tecken i ett objekt utan jokerteckensexpansion måste du undvika jokertecken.

Mer information om jokertecken finns i Så här: Välj de filer som ska skapas.

Använda attributet Exkludera

Objektelement kan innehålla Exclude attributet, vilket exkluderar specifika objekt (filer) från objekttypen. Attributet Exclude används vanligtvis tillsammans med jokertecken. Följande XML lägger till exempel varje .cs fil i katalogen till CSFile objekttypen, förutom den DoNotBuild.cs filen.

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

Attributet Exclude påverkar endast de objekt som läggs till av Include attributet i objektelementet som innehåller dem båda. Följande exempel skulle inte undanta filen Form1.cs, som lades till i föregående objektelement.

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

Mer information finns i Så här: Exkludera filer från bygget.

Objektmetadata

Objekt kan innehålla metadata utöver informationen i attributen Include och Exclude . Dessa metadata kan användas av uppgifter som kräver mer information om objekten eller batchuppgifter och mål. Mer information finns i Batching.

Metadata är en samling nyckel/värde-par som deklareras i projektfilen som underordnade element i ett objektelement. Namnet på det underordnade elementet är namnet på metadata och värdet för det underordnade elementet är värdet för metadata.

Metadata är associerade med objektelementet som innehåller det. Följande XML lägger till exempel till Culture metadata som har värdet Fr för både one.cs och two.cs objekt av CSFile objekttypen.

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

Ett objekt kan ha noll eller fler metadatavärden. Du kan ändra metadatavärden när som helst. Om du anger metadata till ett tomt värde tar du effektivt bort det från bygget.

Metadata för referensobjekt i en projektfil

Du kan referera till objektmetadata i hela projektfilen med hjälp av syntaxen %(ItemMetadataName). Om det finns tvetydighet kan du kvalificera en referens med hjälp av namnet på objekttypen. Du kan till exempel ange %(ItemType.ItemMetaDataName). I följande exempel används metadata för Display att batcha Message uppgiften. Mer information om hur du använder objektmetadata för batchbearbetning finns i Objektmetadata i aktivitetsbatchbearbetning.

<Project>
    <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>

Välkända objektmetadata

När ett objekt läggs till i en objekttyp tilldelas objektet några välkända metadata. Till exempel har alla objekt välkända metadata %(Filename), vars värde är filnamnet för objektet (utan tillägget). Mer information finns i Välkända objektmetadata.

Transformera objekttyper med hjälp av metadata

Du kan omvandla objektlistor till nya objektlistor med hjälp av metadata. Du kan till exempel omvandla en objekttyp CppFiles som har objekt som representerar .cpp filer till en motsvarande lista med .obj filer med hjälp av uttrycket @(CppFiles -> '%(Filename).obj').

Följande kod skapar en CultureResource objekttyp som innehåller kopior av alla EmbeddedResource objekt med Culture metadata. Metadatavärdet Culture blir värdet för de nya metadata CultureResource.TargetDirectory.

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

Fler åtgärder för objekt finns i MSBuild-objektfunktioner och transformeringar.

Objektdefinitioner

Du kan lägga till standardmetadata till valfri objekttyp med elementet ItemDefinitionGroup. Precis som välkända metadata associeras standardmetadata med alla objekt av den objekttyp som du anger. Du kan uttryckligen åsidosätta standardmetadata i en objektdefinition. Följande XML ger till exempel objekten Compileone.cs och three.cs metadata BuildDay med värdet "Måndag". Koden ger objektet two.cs metadata BuildDay med värdet "Tisdag".

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

Mer information finns i Objektdefinitioner.

Attribut för objekt i en ItemGroup för ett mål

Target element kan innehålla ItemGroup-element som kan innehålla objektelement. Attributen i det här avsnittet är giltiga när de anges för ett objekt i en ItemGroup som finns i en Target.

Ta bort attribut

Attributet Remove tar bort specifika objekt (filer) från objekttypen. Det här attributet introducerades i .NET Framework 3.5 (endast inuti mål). Både mål inom och utanför stöds från och med MSBuild 15.0.

I följande exempel tas alla .config filer bort från Compile objekttypen.

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

Attributet MatchOnMetadata

Attributet MatchOnMetadata gäller endast attribut som refererar till Remove andra objekt (till exempel Remove="@(Compile);@(Content)") och instruerar Remove åtgärden att matcha objekt baserat på värdena för angivna metadatanamn, i stället för att matcha baserat på objektvärdena.

Matchningsregel för B Remove="@(A)" MatchOnMetadata="M": ta bort alla objekt från B som har metadata M, vars metadatavärde V för M matchar alla objekt från A med metadata M av värdet 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>

I exemplet tas objektvärdena b2, c2och bort d2 från objektet B eftersom:

  • b2och c2 från B match mot b1 från A och M1=2M2=x
  • d2från B matcher mot c1 från A och M1=3M2=y

Uppgiften Message matar ut följande:

  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'

Exempel på användning av MatchOnMetadata från MSBuild:

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

Den här raden tar bort objekt från _TransitiveItemsToCopyToOutputDirectory som har samma TargetPath metadatavärden från objekt i _ThisProjectItemsToCopyToOutputDirectory

Attributet MatchOnMetadataOptions

Anger den strängmatchningsstrategi som används för MatchOnMetadata att matcha metadatavärdena mellan objekt (metadatanamn matchas alltid skiftlägesokänsliga). Möjliga värden är CaseSensitive, CaseInsensitiveeller PathLike. Standardvärdet är CaseSensitive.

PathLike tillämpar sökvägsmedveten normalisering på värden som normalisering av snedstrecksorienteringar, ignorera avslutande snedstreck, eliminera . och .., och göra alla relativa sökvägar absoluta mot den aktuella katalogen.

KeepMetadata-attribut

Om ett objekt genereras inom ett mål kan objektelementet innehålla attributet KeepMetadata . Om det här attributet anges överförs endast de metadata som anges i den semikolonavgränsade listan med namn från källobjektet till målobjektet. Ett tomt värde för det här attributet motsvarar att det inte anges. Attributet KeepMetadata introducerades i .NET Framework 4.5.

I följande exempel visas hur du använder attributet KeepMetadata .

<Project>
    <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:
-->

Attributet RemoveMetadata

Om ett objekt genereras inom ett mål kan objektelementet innehålla attributet RemoveMetadata . Om det här attributet anges överförs alla metadata från källobjektet till målobjektet förutom metadata vars namn finns i den semikolonavgränsade listan med namn. Ett tomt värde för det här attributet motsvarar att det inte anges. Attributet RemoveMetadata introducerades i .NET Framework 4.5.

I följande exempel visas hur du använder attributet RemoveMetadata .

<Project>

    <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:
-->

Fler åtgärder för objekt finns i MSBuild-objektfunktioner.

KeepDuplicates-attribut

Om ett objekt genereras inom ett mål kan objektelementet innehålla attributet KeepDuplicates . KeepDuplicates är ett Boolean attribut som anger om ett objekt ska läggas till i målgruppen om objektet är en exakt dubblett av ett befintligt objekt.

Om käll- och målobjektet har samma Include värde men olika metadata läggs objektet till även om KeepDuplicates det är inställt på false. Ett tomt värde för det här attributet motsvarar att det inte anges. Attributet KeepDuplicates introducerades i .NET Framework 4.5.

I följande exempel visas hur du använder attributet KeepDuplicates .

<Project>

    <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 Eftersom attributet tar hänsyn till metadata för objekt utöver objektvärdena är det viktigt att veta vad som händer med metadata. Se till exempel Identifiera dubbletter när du använder funktionen Metadataobjekt.

Uppdatera metadata för objekt i en ItemGroup utanför ett mål

Objekt utanför målen kan få sina befintliga metadata uppdaterade via attributet Update . Det här attributet är inte tillgängligt för objekt under må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
-->

I MSBuild version 16.6 och senare Update stöder attributet kvalificerade metadatareferenser för att underlätta import av metadata från två eller flera objekt.

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

Kommentarer:

  • Okvalificerade metadata (%(MetadataName)) binder till den objekttyp som uppdateras (Item1 i exemplet ovan). Kvalificerade metadata (%(Item2.Color)) binder i uppsättningen med insamlade matchande objekttyper från uppdateringsuttrycket.
  • Om ett objekt matchar flera gånger inom och mellan flera refererade objekt:
    • Den senaste förekomsten från varje refererad objekttyp hämtas (så ett avbildat objekt per objekttyp).
    • Detta matchar beteendet för batchbearbetning av aktivitetsobjekt under mål.
  • Där man kan placera %() referenser:
    • Metainformation
    • Metadatavillkor
  • Matchning av metadatanamn är skiftlägeskänsligt.

Uppdatera metadata för objekt i en ItemGroup för ett mål

Metadata kan också ändras inuti mål med en mindre uttrycksfull syntax än 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:
-->

Relaterat innehåll