Elemento Item (MSBuild)

  • Artículo

Contiene un elemento definido por el usuario y sus metadatos. Cada elemento que se utiliza en un proyecto de MSBuild debe especificarse como elemento secundario de un elemento ItemGroup.

<Proyecto>
 <ItemGroup>
  <Elemento>

Sintaxis

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Condition="'String A'=='String B'">
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

Especificar metadatos como atributos

En MSBuild 15.1 o versiones posteriores, los metadatos con un nombre que no entre en conflicto con la lista actual de atributos pueden expresarse opcionalmente como un atributo.

Por ejemplo, para especificar una lista de paquetes NuGet, normalmente se usaría algo parecido a la sintaxis siguiente.

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

Ahora, puede pasar los metadatos Version como un atributo, como se muestra en la sintaxis siguiente:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

Atributos y elementos

En las siguientes secciones se describen los atributos, los elementos secundarios y los elementos primarios.

Atributos

Atributo Descripción
Include Atributo opcional.

El archivo o comodín que se incluirá en la lista de elementos.
Exclude Atributo opcional.

El archivo o comodín que se excluirá de la lista de elementos.
Condition Atributo opcional.

La condición que se va a evaluar. Para obtener más información, consulte Condiciones.
Remove Atributo opcional.

El archivo o comodín que se quitará de la lista de elementos.
MatchOnMetadata Atributo opcional.

Modifica los atributos Remove que hacen referencia a otros elementos para que coincidan en los nombres de metadatos especificados en lugar de coincidir con los valores de los elementos a los que se hace referencia.

Este atributo solo es válido si se especifica junto con un atributo Remove que solo contiene referencias a otros elementos (por ejemplo, Remove="@(Compile);@(Content)"). Para obtener más información, consulte Elementos.
MatchOnMetadataOptions Atributo opcional.

Especifica la estrategia de coincidencia de cadenas utilizada por MatchOnMetadata. Los valores posibles son CaseSensitive, CaseInsensitive o PathLike. El valor predeterminado es CaseInsensitive.
KeepDuplicates Atributo opcional.

Especifica si se debe agregar al grupo de destino un elemento que es un duplicado exacto de un elemento existente. Si el elemento de origen y de destino tienen el mismo valor Include pero distintos metadatos, el elemento se agrega aunque KeepDuplicates está establecido en false. Para obtener más información, consulte Elementos.

Este atributo solo es válido si se ha especificado para un elemento de un ItemGroup que se encuentra en un Target.
KeepMetadata Atributo opcional.

Los metadatos de los elementos de origen que se van a agregar a los elementos de destino. Solo los metadatos cuyos nombres están especificados en la lista delimitada por punto y coma se transfieren desde un elemento de origen a un elemento de destino. Para obtener más información, consulte Elementos.

Este atributo solo es válido si se ha especificado para un elemento de un ItemGroup que se encuentra en un Target.
RemoveMetadata Atributo opcional.

Los metadatos de los elementos de origen que no se van a transferir a los elementos de destino. Todos los metadatos se transfieren desde un elemento de origen a un elemento de destino excepto aquellos cuyos nombres figuran en la lista de nombres delimitada por punto y coma. Para obtener más información, consulte Elementos.

Este atributo solo es válido si se ha especificado para un elemento de un ItemGroup que se encuentra en un Target.
Update Atributo opcional. (Disponible únicamente para los proyectos de .NET Core en Visual Studio 2017 o versiones posteriores).

Permite modificar metadatos de un elemento; Normalmente se usa para invalidar los metadatos predeterminados de elementos específicos después de especificar inicialmente un grupo de elementos (por ejemplo, con un carácter comodín).

Este atributo solo es válido si se ha especificado para un elemento de un ItemGroup que no se encuentra en un Target.

Elementos secundarios

Elemento Descripción
ItemMetadata Una clave de metadatos de elemento definida por el usuario que contiene el valor de metadatos del elemento. Puede haber cero o más elementos ItemMetadata en un elemento.

Elementos primarios

Elemento Descripción
ItemGroup Elemento grouping de los elementos.

Comentarios

Los elementos Item definen las entradas en el sistema de compilación y se agrupan en colecciones de elementos basadas en sus nombres de colección definidos por el usuario. Estas colecciones de elementos se pueden utilizar como parámetros para las tareas, que utilizan los elementos individuales de las colecciones para llevar a cabo los pasos del proceso de compilación. Para obtener más información, consulte Elementos.

El empleo de la notación @(<myType>) permite expandir una colección de elementos de tipo <myType> en una lista de cadenas delimitada por puntos y coma, y pasarla a un parámetro. Si el parámetro es de tipo string, entonces el valor del parámetro es la lista de elementos separados por punto y coma. Si el parámetro es una matriz de cadenas (string[]), entonces cada elemento se inserta en la matriz según la ubicación de los signos punto y coma. Si el parámetro de tarea es de tipo ITaskItem[], el valor es el contenido de la colección de elementos junto con los metadatos adjuntos. Para delimitar cada elemento mediante un carácter que no sea un punto y coma, utilice la sintaxis @(<myType>, '<separator>').

El motor de MSBuild puede evaluar comodines como * y ?, y comodines recursivos como /**/*.cs. Para obtener más información, consulte Elementos.

Ejemplos

En el ejemplo de código siguiente se muestra la declaración de dos elementos de tipo CSFile. El segundo elemento declarado contiene metadatos en los que MyMetadata está establecido en HelloWorld.

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>

En el ejemplo de código siguiente se muestra cómo usar el atributo Update para modificar los metadatos de un archivo denominado somefile.cs que se ha incluido mediante un glob. (Disponible únicamente para los proyectos de .NET Core en Visual Studio 2017 o versiones posteriores).

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>

Vea también