Elemento Item (MSBuild)

Articolo
08/25/2023

Contiene un elemento definito dall'utente e i relativi metadati. Ogni elemento utilizzato in un progetto MSBuild deve essere specificato come elemento figlio di un ItemGroup elemento.

Sintassi

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

Specificare i metadati come attributi

In MSBuild 15.1 o versioni successive, un metadato con un nome che non è in conflitto con l'elenco di attributi corrente può essere espresso come un attributo.

Ad esempio, per specificare un elenco di pacchetti NuGet, si userebbe normalmente una sintassi simile alla seguente:

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

Ora è tuttavia possibile passare il metadato Version come un attributo, come illustrato nella sintassi seguente:

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

Attributi ed elementi

Nelle sezioni seguenti vengono descritti gli attributi, gli elementi figlio e gli elementi padre.

Attributi

Attributo	Descrizione
`Include`	Attributo facoltativo. Il file o carattere jolly da includere nell'elenco di elementi.
`Exclude`	Attributo facoltativo. Il file o carattere jolly da escludere dall'elenco di elementi.
`Condition`	Attributo facoltativo. La condizione da valutare. Per altre informazioni, vedere Condizioni.
`Remove`	Attributo facoltativo. Il file o carattere jolly da eliminare dall'elenco di elementi.
`MatchOnMetadata`	Attributo facoltativo. `Remove` Modifica gli attributi che fanno riferimento ad altri elementi in modo che corrispondano ai nomi di metadati specificati invece di corrispondere ai valori degli elementi a cui si fa riferimento. Questo attributo è valido solo se viene specificato insieme a un `Remove` attributo che contiene solo riferimenti ad altri elementi , ad esempio `Remove="@(Compile);@(Content)"`. Altri dettagli in Elementi.
`MatchOnMetadataOptions`	Attributo facoltativo. Specifica la strategia di corrispondenza delle stringhe utilizzata da `MatchOnMetadata`. I valori possibili sono `CaseSensitive`, `CaseInsensitive`o `PathLike`. Il valore predefinito è `CaseInsensitive`.
`KeepDuplicates`	Attributo facoltativo. Specifica se un elemento deve essere aggiunto al gruppo di destinazione se è un duplicato esatto di un elemento esistente. Se l'elemento di origine e destinazione hanno lo stesso valore `Include`, ma metadati diversi, l'elemento viene aggiunto anche se `KeepDuplicates` è impostato su `false`. Per altre informazioni, vedere Elementi. Questo attributo è valido solo se è stato specificato per un elemento in un `ItemGroup` che si trova in un `Target`.
`KeepMetadata`	Attributo facoltativo. I metadati per gli elementi di origine da aggiungere agli elementi di destinazione. Solo i metadati i cui nomi vengono specificati nell'elenco delimitato da punto e virgola vengono trasferiti da un elemento di origine a un elemento di destinazione. Per altre informazioni, vedere Elementi. Questo attributo è valido solo se è stato specificato per un elemento in un `ItemGroup` che si trova in un `Target`.
`RemoveMetadata`	Attributo facoltativo. I metadati per gli elementi di origine da non trasferire agli elementi di destinazione. Tutti i metadati vengono trasferiti da un elemento di origine a un elemento di destinazione, ad eccezione dei metadati i cui nomi sono contenuti nell'elenco di nomi separati da punto e virgola. Per altre informazioni, vedere Elementi. Questo attributo è valido solo se è stato specificato per un elemento in un `ItemGroup` che si trova in un `Target`.
`Update`	Attributo facoltativo. È disponibile solo per i progetti .NET Core in Visual Studio 2017 o versioni successive. Consente di modificare i metadati di un elemento; in genere usato per eseguire l'override dei metadati predefiniti di elementi specifici dopo che inizialmente viene specificato un gruppo di elementi, ad esempio con un carattere jolly. Questo attributo è valido solo se è stato specificato per un elemento in un `ItemGroup` che non si trova in un `Target`.

Elementi figlio

Elemento	Descrizione
ItemMetadata	Chiave dei metadati di elemento definita dall'utente che contiene il valore dei metadati dell'elemento. Possono esistere zero o più elementi `ItemMetadata` in un elemento.

Elementi padre

Elemento	Descrizione
ItemGroup	Elemento di raggruppamento per elementi.

Osservazioni:

Gli elementi Item definiscono gli input nel sistema di compilazione e vengono raggruppati in raccolte di elementi in base ai relativi nomi definiti dall'utente. Queste raccolte di elementi possono essere usate come parametri per le attività, che a loro volta usano i singoli elementi nelle raccolte per eseguire i passaggi del processo di compilazione. Per altre informazioni, vedere Elementi.

L'uso della notazione @(<myType>) consente l'espansione di una raccolta di elementi di tipo <myType> in un elenco di stringhe delimitato da punto e virgola e passato a un parametro. Se il parametro è di tipo string, il valore del parametro è l'elenco di elementi, separati da punti e virgola. Se il parametro è una matrice di stringhe (string[]), ogni elemento viene inserito nella matrice in base alla posizione dei punti e virgola. Se il parametro dell'attività è di tipo ITaskItem[], il valore è il contenuto della raccolta di elementi con eventuali metadati associati. Per delimitare ogni elemento usando un carattere diverso da un punto e virgola, usare la sintassi @(<myType>, '<separator>').

Il motore MSBuild può valutare caratteri jolly come * e e ? caratteri jolly ricorsivi, ad esempio /**/*.cs. Per altre informazioni, vedere Elementi.

Esempi

Nell'esempio di codice seguente viene illustrato come dichiarare due elementi di tipo CSFile. Il secondo elemento dichiarato contiene i metadati con MyMetadata impostato su HelloWorld.

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

L'esempio di codice seguente illustra come usare l'attributo Update per modificare i metadati in un file denominato somefile.cs, incluso tramite un criterio GLOB. È disponibile solo per i progetti .NET Core in Visual Studio 2017 o versioni successive.

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