Elementi MSBuild
Gli elementi 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é il nome degli elementi dipende dal tipo di elemento a cui appartengono, i termini "elemento" e "valore dell'elemento" possono essere utilizzati indifferentemente.
Creazione di elementi in un file di progetto
Gli elementi vengono dichiarati in un 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. Il codice XML seguente consente, ad esempio, di creare 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" ma viene invece aggiunto all'elenco di valori per il tipo di elemento Compile. Un elemento non può essere rimosso 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
Agli elementi al di fuori degli elementi Target vengono assegnati valori durante la fase di valutazione di una compilazione. Durante la fase di esecuzione successiva, gli elementi possono essere creati o modificati come indicato di seguito:
Gli elementi possono essere creati da qualsiasi attività. Per creare un elemento, l'elemento Task deve disporre di un elemento Output figlio con un attributo ItemName.
Gli elementi possono essere creati dall'attività CreateItem. 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
Nel file di progetto viene fatto riferimento ai tipi di elementi utilizzando la sintassi @(ItemType). Per fare riferimento al tipo di elemento dell'esempio precedente si utilizza, ad esempio @(Compile). Questa sintassi consente di 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 punti e virgola (;) quando vengono espansi. Per specificare un separatore diverso da quello predefinito, utilizzare la sintassi @(ItemType, 'separatore'). 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.
Per specificare, ad esempio, tutti i file con estensione cs nella directory che contiene il file di progetto, utilizzare l'elemento seguente nel file di progetto.
<CSFile Include="*.cs"/>
Un elemento per la selezione di tutti i file con estensione vb nell'unità D: sarebbe
<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>
L'attributo Exclude influisce solo sugli elementi aggiunti dall'attributo Include nell'elemento Item che li contiene entrambi. Ad esempio,
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
non escluderebbe il file Form1.cs, aggiunto nell'elemento Item precedente.
Per ulteriori informazioni, vedere Procedura: escludere file dalla compilazione.
Utilizzo dell'attributo Remove
A partire da .NET Framework 3.5, gli elementi Target possono contenere elementi ItemGroup che possono contenere a loro volta elementi Item. Questi elementi Item possono contenere l'attributo Remove, che consente di rimuovere elementi (file) specifici dal tipo di elemento. Il codice XML seguente consente, ad esempio, di rimuovere tutti i file con estensione config dal tipo di elemento Compile.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Metadati degli elementi
Oltre alle informazioni raccolte dagli attributi Include e Exclude, gli elementi possono contenere anche metadati. È possibile utilizzare i metadati nelle attività che necessitano di maggiori informazioni sugli elementi o per dividere in batch attività e destinazioni. Per ulteriori informazioni sulla suddivisione in batch, vedere Batch MSBuild.
I metadati sono un insieme 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. Nel codice XML seguente vengono ad esempio aggiunti metadati Culture con il valore Fr a entrambi gli elementi "one.cs" e "two.cs" 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. L'impostazione dei metadati su un valore vuoto equivale a rimuoverli dalla compilazione.
Riferimento ai metadati degli elementi in un file di progetto
Nel file di progetto è possibile fare riferimento ai metadati degli elementi utilizzando la sintassi %(ItemMetadataName). In caso di ambiguità, è possibile qualificare il riferimento utilizzando il nome del tipo di elemento, ad esempio %(ItemType.ItemMetaDataName). Nell'esempio seguente 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. Tutti gli elementi includono, ad esempio, i metadati noti %(Filename), il cui valore è il nome file dell'elemento. Per un elenco di tutti i metadati di elemento noti, vedere Metadati noti degli elementi di MSBuild.
Trasformazione di tipi di elementi tramite i metadati
Gli elenchi di elementi possono essere trasformati in nuovi elenchi di elementi utilizzando i metadati. Un tipo di elemento CppFiles che include elementi che rappresentano file con estensione cpp può ad esempio essere trasformato in un elenco corrispondente di file con estensione 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, l'elemento ItemDefinitionGroup consente di aggiungere metadati predefiniti a qualsiasi tipo di elemento. Come i metadati noti, i metadati predefiniti sono associati a tutti gli elementi del tipo di elemento specificato. L'override dei metadati predefiniti può essere eseguito in modo esplicito in una definizione di elemento. Nel codice XML seguente vengono ad esempio assegnati agli elementi Compile "one.cs" e "three.cs" i metadati BuildDay con il valore "Monday" e all'elemento "two.cs" i metadati BuildDay con il valore "Tuesday".
<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.
Vedere anche
Attività
Procedura: selezionare i file da compilare
Procedura: escludere file dalla compilazione
Procedura: visualizzare un elenco di elementi separati da virgole