Elementi MSBuild
Gli elementi MSBuild sono input nel sistema di compilazione e in genere rappresentano file. Gli elementi sono raggruppati in tipi di elementi, in base al relativo nome. I tipi di elementi sono elenchi denominati di elementi che possono essere utilizzati come parametri per le attività. Le attività utilizzano i valori degli elementi per eseguire i passaggi del processo di compilazione.
Poiché gli elementi dipende dal tipo di elemento a cui appartengono, i termini “elemento„ e “valore dell'elemento„ possono essere utilizzati indifferentemente.
In questo argomento
Creazione di elementi in un file di progetto
Creazione di elementi durante l'esecuzione
Riferimento a elementi in un file di progetto
Utilizzo di caratteri jolly per specificare gli elementi
Utilizzo dell'attributo Exclude
Metadati degli elementi
Riferimento ai metadati degli elementi in un file di progetto
Metadati di elementi noti
Trasformazione dei tipi di elementi tramite i metadati
Definizioni di elementi
Attributi per gli elementi in un ItemGroup di un database di destinazione
Rimuovere l'attributo
Attributo di KeepMetadata
Attributo di RemoveMetadata
Attributo di KeepDuplicates
Creazione di elementi in un file di progetto
Dichiarare gli elementi nel file di progetto come elementi figlio di un elemento ItemGroup. Il nome dell'elemento figlio corrisponde al tipo dell'elemento. L'attributo Include dell'elemento specifica gli elementi (file) da includere nel tipo di elemento. Ad esempio, il codice XML seguente crea un tipo di elemento denominato Compile, che include due file.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
L'elemento “file2.cs„ non sostituisce l'elemento “file1.cs„; invece, il nome file è connesso all'elenco di valori per il tipo di elemento Compile. Non è possibile eliminare un elemento da un tipo di elemento durante la fase di valutazione di una compilazione.
Il codice XML seguente consente di creare lo stesso tipo di elemento dichiarando entrambi i file in un unico attributo Include. Si noti che i nomi file sono separati da un punto e virgola.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
Creazione di elementi durante l'esecuzione
Gli elementi che sono elementi esterni Destinazione vengono assegnati valori durante la fase di valutazione di una compilazione. Durante la fase di esecuzione successiva, gli elementi possono essere creati o modificati nei modi seguenti:
Qualsiasi attività può generare un elemento. Per creare un elemento, l'elemento Task deve disporre di un elemento Output figlio con un attributo ItemName.
l'attività CreateItem può generare un elemento. Questo tipo di utilizzo è deprecato.
A partire da .NET Framework 3.5, gli elementi Target possono contenere elementi ItemGroup che possono contenere a loro volta elementi Item.
Riferimento a elementi in un file di progetto
Per fare riferimento ai tipi di elemento nel file di progetto, utilizzare la sintassi @ (ItemType). Ad esempio, è possibile fare riferimento al tipo di elemento dell'esempio precedente utilizzando @(Compile). Tramite questa sintassi, è possibile passare elementi alle attività specificando il tipo di elemento come parametro dell'attività. Per ulteriori informazioni, vedere Procedura: selezionare i file da compilare.
Per impostazione predefinita, gli elementi di un tipo sono separati da punto e virgola (;) quando si è espanso. È possibile utilizzare la sintassi @ (ItemType, “separatore") per specificare un separatore diverso da quello predefinito. Per ulteriori informazioni, vedere Procedura: visualizzare un elenco di elementi separati da virgole.
Utilizzo di caratteri jolly per specificare gli elementi
È possibile utilizzare i caratteri jolly **, * e ? per specificare un gruppo di file come input per una compilazione anziché elencare ogni file separatamente.
Il carattere jolly ? corrisponde a qualsiasi carattere singolo.
Il carattere jolly * corrisponde a zero o più caratteri.
La sequenza di caratteri jolly ** corrisponde a un percorso parziale.
Ad esempio, è possibile specificare tutti i file con estensione cs nella directory contenente il file di progetto utilizzando l'elemento seguente nel file di progetto.
<CSFile Include="*.cs"/>
Nell'selezionare tutti i file con estensione cs in D: unità:
<VBFile Include="D:/**/*.vb"/>
Per ulteriori informazioni sui caratteri jolly, vedere Procedura: selezionare i file da compilare.
Utilizzo dell'attributo Exclude
Gli elementi Item possono contenere l'attributo Exclude, che consente di escludere elementi (file) specifici dal tipo di elemento. L'attributo Exclude viene utilizzato in genere con i caratteri jolly. Il codice XML seguente consente, ad esempio, di aggiungere tutti i file con estensione cs nella directory al tipo di elemento CSFile, ad eccezione del file DoNotBuild.cs.
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
Influisce su attributo Exclude solo gli elementi aggiunti dall'attributo Include nell'elemento Item che li contiene entrambi. Nell'esempio non esclude il file Form1.cs, aggiunto nell'elemento Item precedente.
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
Per ulteriori informazioni, vedere Procedura: escludere file dalla compilazione.
Metadati degli elementi
Gli elementi possono contenere metadati oltre alle informazioni degli attributi Exclude e Include. Questi metadati possono essere utilizzati dalle attività che richiedono ulteriori informazioni sugli elementi o dividere in batch attività e destinazioni. Per ulteriori informazioni, vedere Batch MSBuild.
I metadati sono una raccolta di coppie chiave-valore dichiarate nel file di progetto come elementi figlio di un elemento Item. Il nome dell'elemento figlio è il nome dei metadati e il valore dell'elemento figlio è il valore dei metadati.
I metadati sono associati all'elemento Item che li contiene. Ad esempio, il codice XML aggiunge i metadati Culture con il valore Fr a entrambi gli elementi “one.cs„ e " del tipo di elemento CSFile.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Un elemento può contenere zero o più valori di metadati. È possibile modificare i valori dei metadati in qualsiasi momento. Se i metadati impostati su un valore vuoto, è effettivamente lo si rimuove dalla compilazione.
Riferimento ai metadati degli elementi in un file di progetto
È possibile fare riferimento ai metadati degli elementi nel file di progetto utilizzando la sintassi % (ItemMetadataName). In caso di ambiguità, è possibile qualificare un riferimento tramite il nome del tipo di elemento. Ad esempio, è possibile specificare %(ItemType.ItemMetaDataName). Nell'esempio vengono utilizzati i metadati display per dividere in batch l'attività message. Per ulteriori informazioni sull'utilizzo dei metadati degli elementi per la divisione in batch, vedere Metadati degli elementi nell'esecuzione in batch delle attività.
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<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>
Metadati di elementi noti
Quando un elemento viene aggiunto a un tipo di elemento, a tale elemento vengono assegnati metadati noti. Ad esempio, tutti gli elementi includono %(Filename)di metadati noti, il cui valore è il nome file dell'elemento. Per ulteriori informazioni, vedere Metadati noti degli elementi di MSBuild.
Trasformazione dei tipi di elementi tramite i metadati
È possibile trasformare gli elenchi di elementi in nuovi elenchi di elementi tramite i metadati. Ad esempio, è possibile trasformare un tipo di elemento CppFiles che include elementi che rappresentano file CPP in un elenco corrispondente di file obj utilizzando l'espressione @(CppFiles -> '%(Filename).obj').
Nel codice seguente viene creato un tipo di elemento CultureResource che contiene copie di tutti gli elementi EmbeddedResource con metadati Culture. Il valore dei metadati Culture diventa il valore dei nuovi metadati CultureResource.TargetDirectory.
<Target Name="ProcessCultureResources">
<ItemGroup>
<CultureResource Include="@(EmbeddedResource)"
Condition="'%(EmbeddedResource.Culture)' != ''">
<TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
</CultureResource>
</ItemGroup>
</Target>
Per ulteriori informazioni, vedere Trasformazioni di MSBuild.
Definizioni di elementi
A partire da.NET Framework 3.5, è possibile aggiungere metadati predefiniti a qualsiasi tipo di elemento Elemento ItemDefinitionGroup. Come i metadati noti, i metadati predefiniti sono associati a tutti gli elementi del tipo di elemento specificato. È possibile creare in modo esplicito l'override dei metadati predefiniti in una definizione di elemento. Ad esempio, il codice XML gli elementi “one.cs„ e “three.cs„ CompileBuildDay di metadati con il valore “monday„. Il codice consente all'elemento “two.cs„ BuildDay di metadati con il valore “martedì.„
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
Per ulteriori informazioni, vedere Definizioni degli elementi.
Attributi per gli elementi in un ItemGroup di un database di destinazione
A partire da .NET Framework 3.5, gli elementi Target possono contenere elementi ItemGroup che possono contenere a loro volta elementi Item. Gli attributi in questa sezione sono validi quando vengono specificati per un elemento in ItemGroup in Target.
Rimuovere l'attributo
Gli elementi in ItemGroup di una destinazione possono contenere l'attributo Remove, che rimuove gli elementi (file) specifici dal tipo di elemento. L'attributo è stato introdotto in .NET Framework 3.5.
L'esempio seguente consente di rimuovere ogni file config dal tipo di elemento compile.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Attributo di KeepMetadata
Se un elemento viene generato in un database di destinazione, nell'elemento Item possono contenere l'attributo KeepMetadata. Se questo attributo viene specificato, solo i metadati specificato nell'elenco delimitato da punti e virgola dei nomi verranno trasferiti dall'elemento originale all'elemento di destinazione. Un valore vuoto per questo attributo è equivalente a non specificarlo. L'attributo KeepMetadata è stato introdotto in .NET Framework 4,5.
Nell'esempio seguente viene illustrato come utilizzare l'attributo KeepMetadata.
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003"
ToolsVersion="4.0">
<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:
-->
Attributo di RemoveMetadata
Se un elemento viene generato in un database di destinazione, nell'elemento Item possono contenere l'attributo RemoveMetadata. Se questo attributo viene specificato, tutti i metadati vengono trasferiti dall'elemento originale all'elemento di destinazione eccetto i metadati dei cui nomi sono contenuti nell'elenco delimitato da punti e virgola dei nomi. Un valore vuoto per questo attributo è equivalente a non specificarlo. L'attributo RemoveMetadata è stato introdotto in .NET Framework 4,5.
Nell'esempio seguente viene illustrato come utilizzare l'attributo RemoveMetadata.
<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<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:
-->
Attributo di KeepDuplicates
Se un elemento viene generato in un database di destinazione, nell'elemento Item possono contenere l'attributo KeepDuplicates. KeepDuplicates è un attributo Boolean che specifica se un elemento viene aggiunto al gruppo-obiettivo se l'elemento è un duplicato esatto di un elemento esistente.
Se l'elemento di origine e di destinazione con lo stesso valore Include ma metadati diversi, l'elemento viene aggiunto anche se KeepDuplicates è impostato su false. Un valore vuoto per questo attributo è equivalente a non specificarlo. L'attributo KeepDuplicates è stato introdotto in .NET Framework 4,5.
Nell'esempio seguente viene illustrato come utilizzare l'attributo KeepDuplicates.
<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<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
-->
Vedere anche
Attività
Procedura: selezionare i file da compilare
Procedura: escludere file dalla compilazione
Procedura: visualizzare un elenco di elementi separati da virgole