Personalizzare la compilazione

  • Articolo

I progetti MSBuild che usano il processo di compilazione standard, vale a dire l'importazione di Microsoft.Common.props e Microsoft.Common.targets, possono usare diversi hook di estensibilità per personalizzare il processo di compilazione.

Molte operazioni di compilazione personalizzabili sono controllate dalle proprietà. È importante sapere come e dove impostare un valore della proprietà per ottenere l'effetto desiderato. È possibile impostare le proprietà nella riga di comando (e nei file di risposta), in file speciali come Directory.Build.props, nei file importati o nel file di progetto. È importante sapere dove viene usata, impostata o modificata una proprietà e l'ordine dei file importati, incluse le importazioni implicite da SDK come .NET SDK.

Per un elenco delle proprietà, vedere Proprietà comuni di MSBuild.

Esplorare le opzioni di personalizzazione

Le opzioni di personalizzazione seguenti sono elencate in ordine di complessità crescente e ambito di influenza. È consigliabile usare l'opzione di personalizzazione meno complessa che serve allo scopo, a partire dall'inizio di questo elenco.

Opzione di personalizzazione Descrizione
Aggiungere argomenti alla riga di comando di MSBuild Impostare le proprietà globali che influiscono sulla compilazione e le compilazioni principali di tutti i progetti dipendenti.
Personalizzare la compilazione per un singolo progetto Aggiungere proprietà a .props o .targets file per personalizzare le impostazioni di compilazione.
Gestire i file generati nel processo di compilazione Come assicurarsi che i file generati siano inclusi correttamente nell'output di compilazione.
Personalizzare la compilazione per uno o più progetti Aggiungere proprietà a Directory.Build.props o aggiungere proprietà e destinazioni a Directory.Build.targets per personalizzare la compilazione per tutti i progetti in una cartella. Questa tecnica è utile per impostare le proprietà impostate o usate da un SDK, nonché per definire l'ambito delle personalizzazioni in modo che influiscano su tutti i progetti in una cartella o in una sottocartella.
Personalizzare la compilazione locale Apportare modifiche alla compilazione solo nel computer locale senza influire sui file di origine condivisi.
Personalizzare tutte le compilazioni .NET Personalizzare la compilazione con ambito a livello di sistema per le compilazioni .NET.
Personalizzare le compilazioni C++ Personalizzare la compilazione C++, con ambito in un progetto, una soluzione, una cartella o tutte le compilazioni regolate da un'installazione di MSBuild in un sistema.

Aggiungere argomenti alle chiamate di MSBuild da riga di comando per il progetto

È possibile impostare le proprietà globali nella riga di comando. Le proprietà globali influiscono su tutte le compilazioni del progetto, incluse le dipendenze. Tenere presente che la compilazione di un progetto attiva automaticamente una possibile compilazione per tutte le dipendenze del progetto. Il comportamento normale di MSBuild consiste nel compilare tutti i progetti dipendenti non aggiornati. Le compilazioni di progetti dipendenti vengono avviate con le stesse impostazioni delle proprietà globali dalla riga di comando del progetto originale.

Un file Directory.Build.rsp in o sopra la directory di origine viene applicato alle compilazioni della riga di comando del progetto. Per informazioni dettagliate, vedere File di risposta MSBuild.

Scegliere tra l'aggiunta di proprietà a un .props file o .targets

MSBuild si basa sull'ordine di importazione e l'ultima definizione di una proprietà (o un UsingTask o una destinazione) diventa l'ultima definizione usata.

Quando si usano importazioni esplicite, è possibile importare da un .props file o .targets in qualsiasi momento. Ecco la convenzione ampiamente usata:

  • .props i file vengono importati all'inizio dell'ordine di importazione.

  • .targets i file vengono importati in ritardo nell'ordine di compilazione.

Questa convenzione viene applicata dai processi di importazione <Project Sdk="SdkName"> (ovvero, per prima cosa viene eseguita l'importazione di Sdk.props, prima di tutti i contenuti del file, e quindi viene importato Sdk.targets, dopo tutti i contenuti del file).

Prima di decidere a quale tipo di file aggiungere le proprietà, usare le linee guida generali seguenti:

  • Per molte proprietà, non è importante dove sono definite, perché non vengono sovrascritte e vengono lette solo in fase di esecuzione.

  • Per il comportamento che potrebbe essere personalizzato in un singolo progetto, impostare le impostazioni predefinite nei .props file.

  • Evitare di impostare proprietà dipendenti nei .props file leggendo il valore di una proprietà possibilmente personalizzata, perché la personalizzazione non viene eseguita finché MSBuild non legge il progetto dell'utente.

  • Impostare le proprietà dipendenti nei .targets file, perché selezionano le personalizzazioni dai singoli progetti.

  • Se è necessario eseguire l'override delle proprietà, eseguirla in un .targets file, dopo che tutte le personalizzazioni del progetto utente hanno avuto la possibilità di rendere effettive. Prestare attenzione quando si usano proprietà derivate, poiché potrebbe essere necessario eseguire l'override anche di esse.

  • Includere elementi nei .props file (con condizione per una proprietà). Tutte le proprietà vengono considerate prima di qualsiasi elemento, quindi le personalizzazioni delle proprietà del progetto utente vengono prelevate e l'importazione di elementi nei .props file offre al progetto dell'utente l'opportunità Remove o Update qualsiasi elemento portato dall'importazione.

  • Definire le destinazioni nei .targets file. Tuttavia, se il .targets file viene importato da un SDK, tenere presente che questo scenario rende più difficile eseguire l'override della destinazione perché il progetto dell'utente non ha una posizione per eseguirne l'override per impostazione predefinita.

  • Se possibile, personalizzare le proprietà in fase di valutazione anziché modificarle all'interno di una destinazione. In questo modo, infatti, risulterà più facile caricare un progetto e seguirne l'andamento.

Contenuto correlato