MSBuild (attività)
Compila progetti MSBuild da un altro progetto MSBuild.
Parametri
Nella tabella che segue vengono descritti i parametri dell'attività MSBuild.
| Parametro | Descrizione |
|---|---|
BuildInParallel |
Parametro Boolean facoltativo.Se true, i progetti specificati nel parametro Projects vengono compilati in parallelo, se possibile. Il valore predefinito è false. |
Projects |
Parametro ITaskItem[] obbligatorio.Specifica i file di progetto da compilare. |
Properties |
Parametro String facoltativo.Elenco delimitato da punti e virgola di coppie nome/valore delle proprietà da applicare come proprietà globali al progetto figlio. Dal punto di vista delle funzionalità, l'impostazione di questo parametro equivale a impostare proprietà dotate dell'opzione -property quando si esegue la compilazione con MSBuild.exe. Ad esempio: Properties="Configuration=Debug;Optimize=$(Optimize)"Quando si passano proprietà al progetto tramite il Properties parametro , MSBuild potrebbe creare una nuova istanza del progetto anche se il file di progetto è già stato caricato. MSBuild crea una singola istanza di progetto per un determinato percorso di progetto e un set univoco di proprietà globali. Questo comportamento, ad esempio, consente di creare più attività MSBuild che chiamano myproject.proj con Configuration=Release, ottenendo una singola istanza di myproject.proj (se nell'attività non sono specificate proprietà univoche). Se si specifica una proprietà non ancora visualizzata da MSBuild, MSBuild crea una nuova istanza del progetto, che può essere compilata in parallelo ad altre istanze del progetto. Una configurazione per il rilascio, ad esempio, può essere compilata contemporaneamente a una configurazione per il debug. |
RebaseOutputs |
Parametro Boolean facoltativo.Se true, i percorsi relativi degli elementi di output di destinazione dai progetti compilati vengono modificati in modo da essere percorsi relativi al progetto chiamante. Il valore predefinito è false. |
RemoveProperties |
Parametro String facoltativo.Specifica il set di proprietà globali da rimuovere. |
RunEachTargetSeparately |
Parametro Boolean facoltativo.Se true, l'attività MSBuild richiama ogni destinazione nell'elenco passato a MSBuild uno alla volta, anziché contemporaneamente. Impostare questo parametro su true garantisce che le destinazioni successive vengano richiamate anche se le destinazioni richiamate prima hanno avuto esito negativo. In caso contrario, un errore di compilazione arresterà la chiamata di tutte le destinazioni successive. Il valore predefinito è false. |
SkipNonexistentProjects |
Parametro Boolean facoltativo.Se true, i file di progetto che non esistono sul disco verranno ignorati. In caso contrario, tali progetti genereranno un errore. Il valore predefinito è false. |
SkipNonexistentTargets |
Parametro Boolean facoltativo.Se true, i file di progetto esistenti ma non contengono il nome Targets verranno ignorati. In caso contrario, tali progetti genereranno un errore. Il valore predefinito è false. Introdotto in MSBuild 15.5. |
StopOnFirstFailure |
Parametro Boolean facoltativo.Se true, quando la compilazione di uno dei progetti non riesce, non verranno compilati altri progetti. Questo parametro non è attualmente supportato con la compilazione in parallelo (con più processori). |
TargetAndPropertyListSeparators |
Parametro String[] facoltativo.Specifica un elenco di destinazioni e proprietà come metadati dell'elemento Project. Il carattere di escape verrà rimosso dai separatori prima dell'elaborazione. Ad esempio, %3B (";" preceduto da un carattere di escape) verrà considerato come ";" non preceduto da un carattere di escape. |
TargetOutputs |
Parametro di output ITaskItem[] di sola lettura facoltativo.Restituisce gli output delle destinazioni compilate da tutti i file di progetto. Vengono restituiti solo gli output dalle destinazioni specificate, non tutti gli output esistenti nelle destinazioni da cui le destinazioni dipendono. Il parametro TargetOutputs contiene anche i metadati seguenti:- MSBuildSourceProjectFile: file di progetto MSBuild contenente la destinazione che imposta gli output.- MSBuildSourceTargetName: destinazione che imposta gli output. Nota: per identificare gli output da ogni file di progetto o destinazione separatamente, eseguire l'attività MSBuild separatamente per ogni file di progetto o destinazione. Se si esegue l'attività MSBuild solo una volta per compilare tutti i file di progetto, gli output di tutte le destinazioni vengono raccolte in una sola matrice. |
Targets |
Parametro String facoltativo.Specifica la destinazione o le destinazioni da compilare nei file di progetto. Usare un punto e virgola per separare le voci di un elenco di nomi di destinazione. Se nessuna destinazione viene specificata nell'attività MSBuild, vengono compilate le destinazioni predefinite specificate nei file di progetto. Nota: le destinazioni devono essere presenti in tutti i file di progetto. In caso contrario, si verifica un errore di compilazione. |
ToolsVersion |
Parametro String facoltativo.Specifica la ToolsVersion da usare quando si compilano i progetti passati a questa attività.Consente a un'attività MSBuild di compilare un progetto destinato a una versione diversa di .NET Framework rispetto a quella specificata nel progetto. I valori validi sono 2.0, 3.0 e 3.5. Il valore predefinito è 3.5. |
Osservazioni:
Oltre ai parametri elencati sopra, questa attività eredita i parametri dalla classe TaskExtension, che a sua volta eredita dalla classe Task. Per un elenco di questi parametri aggiuntivi e le rispettive descrizioni, vedere TaskExtension Base Class.
A differenza dell'uso dell'attività Exec per avviare MSBuild.exe, questa attività usa lo stesso processo MSBuild per compilare i progetti figlio. L'elenco di destinazioni già compilate che possono essere ignorate viene condiviso tra le compilazioni padre e figlio. Questa attività è anche più veloce perché non viene creato alcun nuovo processo MSBuild.
Questa attività può elaborare non solo i file di progetto, ma anche i file di soluzione.
Qualsiasi configurazione richiesta da MSBuild per consentire ai progetti di compilare contemporaneamente, anche se la configurazione prevede un'infrastruttura remota (ad esempio porte, protocolli, timeout, tentativi e così via), deve essere resa configurabile tramite un file di configurazione. Se possibile, gli elementi di configurazione devono essere specificati come parametri dell'attività nell'attività MSBuild.
A partire da MSBuild 3.5, i progetti di soluzione ora esecuno TargetOutputs da tutti i sottoproi progetti compilati.
Passare proprietà a progetti
Nelle versioni di MSBuild precedenti a MSBuild 3.5, il passaggio di diversi set di proprietà a progetti diversi elencati nell'elemento MSBuild era complesso. Se è stato usato l'attributo Properties dell'attività MSBuild, l'impostazione è stata applicata a tutti i progetti in corso di compilazione, a meno che l'attività MSBuild non sia stata divisa in batch e non siano state fornite proprietà diverse in modo condizionale per ogni progetto nell'elenco di elementi.
MSBuild 3.5, tuttavia, fornisce due nuovi elementi di metadati riservati, Proprietà e Proprietà aggiuntive, che consentono di passare proprietà diverse per progetti diversi compilati usando l'attività MSBuild.
Nota
Questi nuovi elementi di metadati sono applicabili solo agli elementi passati nell'attributo Projects dell'attività MSBuild.
Vantaggi della compilazione a più processori
Uno dei vantaggi principali derivanti dall'uso di questi nuovi metadati consiste nel compilare i progetti in parallelo in un sistema a più processori. I metadati consentono di consolidare tutti i progetti in una singola chiamata di attività MSBuild senza dover eseguire attività msbuild in batch o condizionali. E quando si chiama un'unica attività MSBuild, tutti i progetti elencati nell'attributo Projects vengono compilati in parallelo, Tuttavia, solo se l'attributo è presente nell'attività BuildInParallel=true MSBuild. Per altre informazioni, vedere Creare più progetti in parallelo.
Metadati Properties
Quando specificati, i metadati Properties eseguono l'override del parametro Properties dell'attività, mentre i metadati AdditionalProperties vengono accodati alle definizioni del parametro.
Uno scenario comune è quello in cui si compilano più file di soluzione tramite l'attività MSBuild, usando però configurazioni della build diverse. Potrebbe essere necessario compilare la soluzione a1 usando la configurazione per il debug e la soluzione a2 usando la configurazione per la versione. In MSBuild 2.0 questo file di progetto sarà simile al seguente:
Nota
Nell'esempio seguente "…" rappresenta file di soluzione aggiuntivi.
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Build">
<MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
<MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
</Target>
</Project>
Usando i metadati Properties, tuttavia, è possibile semplificare l'operazione e usare una sola attività MSBuild, come illustrato di seguito:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln...">
<Properties>Configuration=Debug</Properties>
</ProjectToBuild>
<ProjectToBuild Include="a2.sln">
<Properties>Configuration=Release</Properties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"/>
</Target>
</Project>
- oppure -
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln..."/>
<ProjectToBuild Include="a2.sln">
<Properties>Configuration=Release</Properties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"
Properties="Configuration=Debug"/>
</Target>
</Project>
Metadati AdditionalProperties
Si consideri lo scenario seguente, in cui due file di soluzione vengono compilati tramite l'attività MSBuild. Entrambi usano la configurazione per il rilascio, ma uno usa l'architettura x86 e l'altro l'architettura ia64. In MSBuild 2.0 è necessario creare più istanze dell'attività MSBuild: una per compilare il progetto usando la configurazione release con l'architettura x86, l'altra usando la configurazione release con l'architettura ia64. Il file di progetto sarà come il seguente:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Build">
<MSBuild Projects="a1.sln..." Properties="Configuration=Release;
Architecture=x86"/>
<MSBuild Projects="a2.sln" Properties="Configuration=Release;
Architecture=ia64"/>
</Target>
</Project>
Usando i metadati AdditionalProperties è possibile semplificare l'operazione e usare una sola attività MSBuild, come illustrato di seguito:
a.proj
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectToBuild Include="a1.sln...">
<AdditionalProperties>Architecture=x86
</AdditionalProperties>
</ProjectToBuild>
<ProjectToBuild Include="a2.sln">
<AdditionalProperties>Architecture=ia64
</AdditionalProperties>
</ProjectToBuild>
</ItemGroup>
<Target Name="Build">
<MSBuild Projects="@(ProjectToBuild)"
Properties="Configuration=Release"/>
</Target>
</Project>
Esempio
L'esempio seguente usa l'attività MSBuild per compilare i progetti specificati dalla raccolta di elementi ProjectReferences. Gli output di destinazione risultanti vengono archiviati nella raccolta di elementi AssembliesBuiltByChildProjects.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<ProjectReferences Include="*.*proj" />
</ItemGroup>
<Target Name="BuildOtherProjects">
<MSBuild
Projects="@(ProjectReferences)"
Targets="Build">
<Output
TaskParameter="TargetOutputs"
ItemName="AssembliesBuiltByChildProjects" />
</MSBuild>
</Target>
</Project>