Personalizzare la compilazione

Questo articolo offre una panoramica delle opzioni di personalizzazione del processo di build e indicazioni su quando usare ogni approccio. Le opzioni vengono presentate in ordine di complessità, dagli argomenti della riga di comando alle personalizzazioni a livello di sistema.

Prerequisiti

• Familiarità con la struttura dei file di progetto MSBuild (.csproj, .vbprojo simile)
• Conoscenza di base delle proprietà e delle destinazioni di MSBuild

Informazioni generali

I progetti MSBuild che usano il processo di compilazione standard (importazione di Microsoft.Common.props e Microsoft.Common.targets) hanno diversi hook di estendibilità che è possibile usare per personalizzare il processo di compilazione.

Molte operazioni di compilazione personalizzate 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.

Aggiungere argomenti alle chiamate 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 dalla riga di comando del progetto originale con le stesse impostazioni delle proprietà globali.

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 di MSBuild.

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

MSBuild è dipendente dall'ordine di importazione, e l'ultima definizione di una proprietà (o di un target UsingTask) è la 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 dalle <Project Sdk="SdkName"> importazioni ( ovvero l'importazione di Sdk.props viene prima, prima che tutto il contenuto del file, quindi Sdk.targets venga eseguito per ultimo, dopo tutto il contenuto del file).

Quando si decide dove inserire 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é accolgono le personalizzazioni dai singoli progetti.

• Se è necessario sovrascrivere le proprietà, farlo in un file .targets, dopo che tutte le personalizzazioni utente-progetto sono state applicate. Prestare attenzione quando si usano proprietà derivate; potrebbe essere necessario eseguire anche l'override delle proprietà derivate.

• Includere elementi nei file .props (condizionato da una proprietà). Tutte le proprietà sono valutate prima di ogni elemento, quindi vengono applicate le personalizzazioni delle proprietà del progetto utente e l'importare elementi nei file .props offre al progetto dell'utente l'opportunità di Remove o Update qualsiasi elemento introdotto dall'importazione.

• Definire gli obiettivi nei file .targets. 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, preferire la personalizzazione delle proprietà in fase di valutazione rispetto alla modifica delle proprietà all'interno di una destinazione. Questa linea guida semplifica il caricamento di un progetto e la comprensione delle operazioni da eseguire.

Contenuti correlati

• Panoramica del processo di compilazione
• Proprietà comuni del progetto MSBuild
• File di risposta di MSBuild
• Riferimento di MSBuild