Definicje elementów
Program MSBuild 2.0 umożliwia statyczną deklarację elementów w plikach projektu przy użyciu elementu ItemGroup . Metadane mogą być jednak dodawane tylko na poziomie elementu, nawet jeśli metadane są identyczne dla wszystkich elementów. Począwszy od programu MSBuild 3.5, element projektu o nazwie ItemDefinitionGroup przezwycięży to ograniczenie. Element ItemDefinitionGroup umożliwia zdefiniowanie zestawu definicji elementów, które dodają domyślne wartości metadanych do wszystkich elementów w nazwanym typie elementu.
Element ItemDefinitionGroup jest wyświetlany natychmiast po elemencie Project pliku projektu. Definicje elementów zapewniają następujące funkcje:
Możesz zdefiniować globalne domyślne metadane dla elementów spoza obiektu docelowego. Oznacza to, że te same metadane dotyczą wszystkich elementów określonego typu.
Typy elementów mogą mieć wiele definicji. Po dodaniu dodatkowych specyfikacji metadanych do typu ostatnia specyfikacja ma pierwszeństwo. (Metadane są zgodne z tą samą kolejnością importowania co właściwości).
Metadane mogą być addytywne. Na przykład wartości CDefines są gromadzone warunkowo, w zależności od właściwości, które są ustawiane. Na przykład
MT;STD_CALL;DEBUG;UNICODE.Metadane można usunąć.
Warunki mogą służyć do kontrolowania dołączania metadanych.
Wartości domyślne metadanych elementu
Metadane elementu zdefiniowane w elemencie ItemDefinitionGroup to tylko deklaracja metadanych domyślnych. Metadane nie mają zastosowania, chyba że zdefiniujesz element, który używa elementu ItemGroup do przechowywania wartości metadanych.
Uwaga
W wielu przykładach w tym temacie jest wyświetlany element ItemDefinitionGroup, ale jego odpowiadająca definicja elementu ItemGroup zostanie pominięta w celu uzyskania jasności.
Metadane jawnie zdefiniowane w elemencie ItemGroup mają pierwszeństwo przed metadanymi w elemencie ItemDefinitionGroup. Metadane w elemencie ItemDefinitionGroup są stosowane tylko dla niezdefiniowanych metadanych w grupie elementów. Na przykład:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemGroup>
<i Include="a">
<o>o1</o>
<n>n2</n>
</i>
</ItemGroup>
W tym przykładzie domyślne metadane "m" są stosowane do elementu "i", ponieważ metadane "m" nie są jawnie zdefiniowane przez element "i". Jednak domyślne metadane "n" nie są stosowane do elementu "i", ponieważ metadane "n" są już zdefiniowane przez element "i".
Uwaga
W nazwach elementów XML i parametrów uwzględniana jest wielkość liter. Metadane elementu i nazwy elementów/właściwości nie są uwzględniane wielkości liter. W związku z tym elementy ItemDefinitionGroup, które mają nazwy różniące się tylko wielkością liter, powinny być traktowane jako ta sama grupa elementów.
Źródła wartości
Wartości metadanych zdefiniowanych w elemencie ItemDefinitionGroup mogą pochodzić z wielu różnych źródeł w następujący sposób:
Właściwość PropertyGroup
Element z elementu ItemDefinitionGroup
Przekształcanie elementu w elemencie ItemDefinitionGroup
Zmienna środowiskowa
Właściwość globalna (z wiersza polecenia MSBuild.exe )
Właściwość zarezerwowana
Dobrze znane metadane elementu z elementu ItemDefinitionGroup
Sekcja <CDATA ![ CDATA[nic tutaj nie jest analizowane]]>
Uwaga
Metadane elementu z grupy elementów nie są przydatne w deklaracji metadanych ItemDefinitionGroup, ponieważ elementy ItemDefinitionGroup są przetwarzane przed elementami ItemGroup.
Definicje addytywne i wiele
Podczas dodawania definicji lub używania wielu grup ItemDefinitionGroup należy pamiętać o następujących kwestiach:
Dodatkowa specyfikacja metadanych jest dodawana do typu.
Ostatnia specyfikacja ma pierwszeństwo.
Jeśli masz wiele elementów ItemDefinitionGroups, każda kolejna specyfikacja dodaje metadane do poprzedniej definicji. Na przykład:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<o>o1</o>
</i>
</ItemDefinitionGroup>
W tym przykładzie metadane "o" są dodawane do "m" i "n".
Ponadto można również dodać wcześniej zdefiniowane wartości metadanych. Na przykład:
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
W tym przykładzie wcześniej zdefiniowana wartość metadanych "m" (m1) jest dodawana do nowej wartości (m2), dzięki czemu ostateczna wartość to "m1; m2".
Uwaga
Może to również wystąpić w tej samej grupie ItemDefinitionGroup.
Po zastąpieniu wcześniej zdefiniowanych metadanych ostatnia specyfikacja ma pierwszeństwo. W poniższym przykładzie ostateczna wartość metadanych "m" przechodzi od "m1" do "m1a".
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>m1a</m>
</i>
</ItemDefinitionGroup>
Używanie warunków w elemencie ItemDefinitionGroup
Warunki w elemencie ItemDefinitionGroup można użyć do kontrolowania dołączania metadanych. Na przykład:
<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
W takim przypadku domyślne metadane "m1" w elemencie "i" są uwzględniane tylko wtedy, gdy wartość właściwości "Configuration" to "Debug".
Uwaga
W warunkach są obsługiwane tylko odwołania do lokalnych metadanych.
Odwołania do metadanych zdefiniowanych we wcześniejszej grupie ItemDefinitionGroup są lokalne dla elementu, a nie do grupy definicji. Oznacza to, że zakres odwołań jest specyficzny dla elementu. Na przykład:
<ItemDefinitionGroup>
<test>
<yes>1</yes>
</test>
<i>
<m>m0</m>
<m Condition="'%(test.yes)'=='1'">m1</m>
</i>
</ItemDefinitionGroup>
W powyższym przykładzie element "i" odwołuje się do elementu "test" w jego warunku. Ten warunek nigdy nie będzie spełniony, ponieważ program MSBuild interpretuje odwołanie do metadanych innego elementu w elemencie ItemDefinitionGroup jako pusty ciąg. W związku z tym wartość "m" zostanie ustawiona na "m0".
<ItemDefinitionGroup>
<i>
<m>m0</m>
<yes>1</yes>
<m Condition="'%(i.yes)'=='1'">m1</m>
</i>
</ItemDefinitionGroup>
W powyższym przykładzie wartość "m" zostanie ustawiona na wartość "m1", ponieważ element Warunek odwołuje się do elementu "i" metadanych elementu "tak".
Zastępowanie i usuwanie metadanych
Metadane zdefiniowane w elemencie ItemDefinitionGroup można zastąpić w późniejszym elemencie ItemDefinitionGroup, ustawiając wartość metadanych na inną wartość. Element metadanych można również skutecznie usunąć, ustawiając go na pustą wartość. Na przykład:
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m></m>
</i>
</ItemDefinitionGroup>
Element "i" nadal zawiera metadane "m", ale jego wartość jest teraz pusta.
Zakres metadanych
Grupy ItemDefinitionGroups mają zakres globalny dla zdefiniowanych i globalnych właściwości wszędzie tam, gdzie są zdefiniowane. Domyślne definicje metadanych w elemencie ItemDefinitionGroup mogą być odwołujące się do siebie. Na przykład w poniższych celach użyto prostego odwołania do metadanych:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
Można również użyć kwalifikowanego odwołania do metadanych:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(i.m);m2</m>
</i>
</ItemDefinitionGroup>
Jednak następujące elementy są nieprawidłowe:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>@(x)</m>
</i>
</ItemDefinitionGroup>
Począwszy od programu MSBuild 3.5, grupy elementów mogą być również odwołujące się do siebie. Na przykład:
<ItemGroup>
<item Include="a">
<m>m1</m>
<m>%(m);m2</m>
</item>
</ItemGroup>