Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Los elementos de MSBuild son entradas en el sistema de compilación y normalmente representan archivos (los archivos se especifican en el Include atributo ). Los elementos se agrupan en tipos de elementos en función de sus nombres de elemento. Los tipos de elemento se denominan listas de elementos que se pueden usar como parámetros para las tareas. Las tareas usan los valores de elemento para realizar los pasos del proceso de compilación.
Dado que los elementos se denominan por el tipo de elemento al que pertenecen, los términos "item" y "item value" se pueden usar indistintamente.
Crear elementos en un archivo de proyecto
Los elementos del archivo de proyecto se declaran como elementos secundarios de un elemento ItemGroup . Los nombres de elementos válidos comienzan con una letra mayúscula o minúscula o un carácter de subrayado (_); los caracteres posteriores válidos incluyen caracteres alfanuméricos (letras o dígitos), caracteres de subrayado y guion (-). El nombre del elemento secundario es el tipo del elemento. El Include atributo del elemento especifica los elementos (archivos) que se incluirán con ese tipo de elemento. Por ejemplo, el siguiente XML crea un tipo de elemento denominado Compile, que incluye dos archivos.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
El elemento file2.cs no reemplaza el elemento file1.cs; en su lugar, el nombre de archivo se anexa a la lista de valores para el tipo de Compile elemento.
El siguiente XML crea el mismo tipo de elemento declarando ambos archivos en un Include atributo. Observe que los nombres de archivo están separados por un punto y coma.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
El Include atributo es una ruta de acceso que se interpreta en relación con la carpeta del archivo del proyecto, $(MSBuildProjectPath), incluso si el elemento está en un archivo importado, como un .targets archivo.
Crear elementos durante la ejecución
Los elementos que están fuera de los elementos target se asignan valores durante la fase de evaluación de una compilación. Durante la fase de ejecución posterior, los elementos se pueden crear o modificar de las siguientes maneras:
Cualquier tarea puede emitir un elemento. Para emitir un elemento, el elemento Task debe tener un elemento Output secundario que tenga un
ItemNameatributo .La tarea CreateItem puede emitir un elemento. Este uso está en desuso.
Targetlos elementos pueden contener elementos ItemGroup que pueden contener elementos item.
Elementos de referencia en un archivo de proyecto
Para hacer referencia a los tipos de elementos a lo largo del archivo de proyecto, use la sintaxis @(ItemType). Por ejemplo, haría referencia al tipo de elemento en el ejemplo anterior mediante @(Compile). Mediante esta sintaxis, puede pasar elementos a tareas especificando el tipo de elemento como parámetro de esa tarea. Para obtener más información, vea Cómo: Seleccionar los archivos que se van a compilar.
De forma predeterminada, los elementos de un tipo de elemento están separados por punto y coma (;) cuando se expande. Puede usar la sintaxis @(ItemType, 'separator') para especificar un separador distinto del predeterminado. Para obtener más información, vea Cómo: Mostrar una lista de elementos separada por comas.
Usar caracteres comodín para especificar elementos
Puede usar los **caracteres comodín , *y ? para especificar un grupo de archivos como entradas para una compilación en lugar de enumerar cada archivo por separado.
- El
?carácter comodín coincide con un solo carácter. - El
*carácter comodín coincide con cero o más caracteres. - La secuencia de
**caracteres comodín coincide con una ruta de acceso parcial.
Por ejemplo, puede especificar todos los .cs archivos del directorio que contiene el archivo del proyecto mediante el siguiente elemento del archivo de proyecto.
<CSFile Include="*.cs"/>
El siguiente elemento selecciona todos los .vb archivos de la D: unidad:
<VBFile Include="D:/**/*.vb"/>
Si desea incluir caracteres literales * o ? en un elemento sin expansión de caracteres comodín, debe escapar los caracteres comodín.
Para obtener más información sobre los caracteres comodín, vea Cómo: Seleccionar los archivos que se van a compilar.
Uso del atributo Exclude
Los elementos item pueden contener el Exclude atributo , que excluye elementos específicos (archivos) del tipo de elemento. El Exclude atributo se usa normalmente junto con caracteres comodín. Por ejemplo, el siguiente XML agrega cada archivo .cs del directorio al CSFile tipo de elemento, excepto el archivo DoNotBuild.cs .
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
El Exclude atributo afecta solo a los elementos agregados por el Include atributo en el elemento item que los contiene ambos. En el ejemplo siguiente no se excluiría el archivo Form1.cs, que se agregó en el elemento de elemento anterior.
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
Para obtener más información, vea Cómo: Excluir archivos de la compilación.
Metadatos de elementos
Los elementos pueden contener metadatos además de la información de los Include atributos y Exclude . Estas tareas pueden usar estos metadatos que requieren más información sobre los elementos o para procesar por lotes tareas y destinos. Para obtener más información, consulte Procesamiento por lotes.
Los metadatos son una colección de pares clave-valor que se declaran en el archivo de proyecto como elementos secundarios de un elemento de elemento. El nombre del elemento secundario es el nombre de los metadatos y el valor del elemento secundario es el valor de los metadatos.
Los metadatos están asociados al elemento de elemento que lo contiene. Por ejemplo, el siguiente XML agrega Culture metadatos que tienen el valor Fr tanto a la one.cs como a los elementos two.cs del CSFile tipo de elemento.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Un elemento puede tener cero o más valores de metadatos. Puede cambiar los valores de metadatos en cualquier momento. Si establece metadatos en un valor vacío, lo quita de la compilación de forma eficaz.
Metadatos de elementos de referencia en un archivo de proyecto
Puede hacer referencia a metadatos de elementos en todo el archivo de proyecto mediante la sintaxis %(ItemMetadataName). Si existe ambigüedad, puede calificar una referencia mediante el nombre del tipo de elemento. Por ejemplo, puede especificar %(ItemType.ItemMetaDataName). En el ejemplo siguiente se usan los Display metadatos para procesar por lotes la Message tarea. Para obtener más información sobre cómo usar metadatos de elementos para el procesamiento por lotes, consulte Metadatos de elementos en el procesamiento por lotes de tareas.
<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>
Metadatos de elementos conocidos
Cuando se agrega un elemento a un tipo de elemento, a ese elemento se le asignan algunos metadatos conocidos. Por ejemplo, todos los elementos tienen los metadatos conocidos %(Filename), cuyo valor es el nombre de archivo del elemento (sin la extensión). Para obtener más información, vea Metadatos de elementos conocidos.
Transformación de tipos de elementos mediante metadatos
Puede transformar listas de elementos en nuevas listas de elementos mediante metadatos. Por ejemplo, puede transformar un tipo CppFiles de elemento que tenga elementos que representan .cpp archivos en una lista correspondiente de .obj archivos mediante la expresión @(CppFiles -> '%(Filename).obj').
El código siguiente crea un CultureResource tipo de elemento que contiene copias de todos los EmbeddedResource elementos con Culture metadatos. El Culture valor de metadatos se convierte en el valor de los nuevos metadatos CultureResource.TargetDirectory.
<Target Name="ProcessCultureResources">
<ItemGroup>
<CultureResource Include="@(EmbeddedResource)"
Condition="'%(EmbeddedResource.Culture)' != ''">
<TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
</CultureResource>
</ItemGroup>
</Target>
Para obtener más operaciones sobre elementos, consulte Funciones y transformaciones de elementos de MSBuild.
Definiciones de elementos
Puede agregar metadatos predeterminados a cualquier tipo de elemento mediante el elemento ItemDefinitionGroup. Al igual que los metadatos conocidos, los metadatos predeterminados están asociados a todos los elementos del tipo de elemento que especifique. Puede invalidar explícitamente los metadatos predeterminados en una definición de elemento. Por ejemplo, el siguiente XML proporciona los Compile elementos one.cs y three.cs los metadatos BuildDay con el valor "Monday". El código proporciona al elemento two.cs los metadatos BuildDay con el valor "Tuesday".
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
Para obtener más información, vea Definiciones de elementos.
Atributos para los elementos de un itemGroup de un destino
Target los elementos pueden contener elementos ItemGroup que pueden contener elementos item. Los atributos de esta sección son válidos cuando se especifican para un elemento de que ItemGroup se encuentra en .Target
Quitar atributo
El Remove atributo quita elementos específicos (archivos) del tipo de elemento. Este atributo se introdujo en .NET Framework 3.5 (solo dentro de destinos). Los destinos internos y externos se admiten a partir de MSBuild 15.0.
En el ejemplo siguiente se quitan todos los .config archivos del Compile tipo de elemento.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Atributo MatchOnMetadata
El MatchOnMetadata atributo solo es aplicable a los atributos que hacen referencia a Remove otros elementos (por ejemplo, Remove="@(Compile);@(Content)") e indica a la Remove operación que coincida con los elementos en función de los valores de los nombres de metadatos especificados, en lugar de coincidir en función de los valores de elemento.
Regla de coincidencia para B Remove="@(A)" MatchOnMetadata="M": quite todos los elementos de B que tienen metadatos M, cuyo valor V de metadatos para M coincide con cualquier elemento de A con metadatos M de valor 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>
En el ejemplo, los valores b2de elemento , c2y d2 se quitan del elemento B porque:
-
b2yc2deBla coincidencia contrab1desdeAyM1=2M2=x -
d2deBcoincidencias contrac1desdeAyM1=3M2=y
La Message tarea genera lo siguiente:
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'
Ejemplo de uso de MatchOnMetadata desde MSBuild:
<_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />
Esta línea quita los elementos de _TransitiveItemsToCopyToOutputDirectory que tienen los mismos TargetPath valores de metadatos de los elementos de . _ThisProjectItemsToCopyToOutputDirectory
Atributo MatchOnMetadataOptions
Especifica la estrategia de coincidencia de cadenas utilizada por MatchOnMetadata para buscar coincidencias con los valores de metadatos entre elementos (los nombres de metadatos siempre no distinguen mayúsculas de minúsculas). Los valores posibles son CaseSensitive, CaseInsensitiveo PathLike. El valor predeterminado es CaseSensitive.
PathLike aplica la normalización compatible con la ruta de acceso a los valores, como normalizar las orientaciones de barra diagonal, omitir las barras diagonales finales, eliminar . y .., y hacer que todas las rutas de acceso relativas sean absolutas en el directorio actual.
Atributo KeepMetadata
Si se genera un elemento dentro de un destino, el elemento de elemento puede contener el KeepMetadata atributo . Si se especifica este atributo, solo se transferirán los metadatos especificados en la lista de nombres delimitada por punto y coma del elemento de origen al elemento de destino. Un valor vacío para este atributo es equivalente a no especificarlo. El KeepMetadata atributo se introdujo en .NET Framework 4.5.
En el ejemplo siguiente se muestra cómo usar el KeepMetadata atributo .
<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:
-->
Atributo RemoveMetadata
Si se genera un elemento dentro de un destino, el elemento de elemento puede contener el RemoveMetadata atributo . Si se especifica este atributo, todos los metadatos se transfieren del elemento de origen al elemento de destino, excepto los metadatos cuyos nombres se encuentran en la lista delimitada por punto y coma de nombres. Un valor vacío para este atributo es equivalente a no especificarlo. El RemoveMetadata atributo se introdujo en .NET Framework 4.5.
En el ejemplo siguiente se muestra cómo usar el RemoveMetadata atributo .
<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:
-->
Para obtener más operaciones sobre los elementos, consulte Funciones de elementos de MSBuild.
Atributo KeepDuplicates
Si se genera un elemento dentro de un destino, el elemento de elemento puede contener el KeepDuplicates atributo .
KeepDuplicates es un Boolean atributo que especifica si se debe agregar un elemento al grupo de destino si el elemento es un duplicado exacto de un elemento existente.
Si el elemento de origen y destino tienen el mismo Include valor pero metadatos diferentes, el elemento se agrega incluso si KeepDuplicates se establece en false. Un valor vacío para este atributo es equivalente a no especificarlo. El KeepDuplicates atributo se introdujo en .NET Framework 4.5.
En el ejemplo siguiente se muestra cómo usar el KeepDuplicates atributo .
<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
-->
Dado que el KeepDuplicates atributo tiene en cuenta los metadatos de los elementos además de los valores de elemento, es importante saber lo que sucede con los metadatos. Por ejemplo, consulte Detección de duplicados al usar la función Elemento de metadatos.
Actualización de metadatos en elementos de un itemGroup fuera de un destino
Los elementos fuera de los destinos pueden tener sus metadatos existentes actualizados a través del Update atributo . Este atributo no está disponible para los elementos en destinos.
<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
-->
En MSBuild versión 16.6 y posteriores, el Update atributo admite referencias de metadatos calificadas para facilitar la importación de metadatos de dos o más elementos.
<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
-->
Observaciones:
- Los metadatos no calificados (
%(MetadataName)) se enlazan al tipo de elemento que se actualiza (Item1en el ejemplo anterior). Los metadatos completos (%(Item2.Color)) se enlazan dentro del conjunto de tipos de elementos coincidentes capturados de la expresión Update. - Si un elemento coincide varias veces dentro y entre varios elementos a los que se hace referencia:
- La última aparición de cada tipo de elemento al que se hace referencia se captura (por lo que se captura un elemento por tipo de elemento).
- Esto coincide con el comportamiento del procesamiento por lotes de elementos de tarea en destinos.
- Donde se pueden colocar referencias %():
- Metadatos
- Condiciones de metadatos
- La coincidencia de nombres de metadatos no distingue mayúsculas de minúsculas.
Actualización de metadatos en elementos de un itemGroup de un destino
Los metadatos también se pueden modificar dentro de destinos, mediante una sintaxis menos expresiva que 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:
-->