MSBuild

  • Articolo

Microsoft Build Engine è una piattaforma per la compilazione di applicazioni. Questo motore, anche noto come MSBuild, fornisce un XML Schema per un file di progetto che controlla il modo in cui la piattaforma di compilazione elabora e compila il software. Visual Studio usa MSBuild, ma la piattaforma non dipende da Visual Studio. Richiamando msbuild.exe o dotnet build nel file del progetto o della soluzione, è possibile orchestrare e compilare prodotti in ambienti in cui Visual Studio non è installato.

Visual Studio utilizza MSBuild per caricare e compilare progetti gestiti. I file di progetto in Visual Studio (con estensione csproj, vbproj, vcxproj e altre) contengono il codice XML di MSBuild che viene eseguito quando si compila un progetto usando l'IDE. I progetti di Visual Studio importano tutte le impostazioni e tutti i processi di compilazione necessari per eseguire il normale lavoro di sviluppo standard, ma è possibile estenderli o modificarli in Visual Studio o mediante un editor XML.

Per installare MSBuild in un sistema Windows che non dispone di Visual Studio, passare a Build Tools for Visual Studio (Strumenti di compilazione per Visual Studio ) nella pagina dei download. L'installazione di MSBuild da questo metodo consente di MSBuild.exe.

Per .NET Core e .NET 5 o versione successiva, un altro modo per ottenere l'equivalente a MSBuild consiste nell'installare .NET SDK. Il comando dotnet build di compilazione .NET è disponibile con .NET SDK in macOS, Windows o Linux. Il comando dotnet build di compilazione .NET è un wrapper sottile sulla versione .NET Core di MSBuild.exe. È possibile usare l'interfaccia della riga di comando di .NET Core, che usa MSBuild, per compilare progetti destinati a .NET Core e .NET 5 e versioni successive.

A partire da Visual Studio 2022, quando si compila in Visual Studio, viene usata la versione a 64 bit di MSBuild.

Per informazioni su MSBuild per C++, vedere MSBuild (C++).

Gli esempi seguenti illustrano quando è possibile eseguire compilazioni richiamando MSBuild dalla riga di comando anziché dall'IDE di Visual Studio.

  • Visual Studio non è installato.

  • Si vuole usare la versione a 64 bit di MSBuild e si usa Visual Studio 2019 o versioni precedenti. Questa versione di MSBuild non è solitamente necessaria, ma consente l'accesso di MSBuild a una maggiore quantità di memoria.

  • Si desidera eseguire una compilazione in più processi. Tuttavia, è possibile usare l'IDE per ottenere lo stesso risultato nei progetti di C++ e C#.

  • Si intende modificare il sistema di compilazione. Ad esempio, può essere necessario consentire le azioni seguenti:

    • Pre-elabora i file prima che arrivino al compilatore.

    • Copiare gli output di compilazione in un'altra posizione.

    • Creare file compressi dagli output di compilazione.

    • Eseguire un passaggio di post-elaborazione. Ad esempio, può essere utile contrassegnare un assembly con una versione diversa.

È possibile scrivere codice nell'IDE di Visual Studio ed eseguire le compilazioni tramite MSBuild. In alternativa, è possibile compilare codice nell'IDE in un computer di sviluppo, ma eseguire MSBuild dalla riga di comando per compilare codice integrato da un repository di origine con collaborazione di più sviluppatori.

Nota

È possibile usare Azure Pipelines per compilare, testare e distribuire automaticamente l'applicazione. Il sistema di compilazione può eseguire le compilazioni automaticamente quando gli sviluppatori archiviano il codice, ad esempio come parte di una strategia di integrazione continuata, o secondo a una pianificazione, ad esempio una compilazione notturna di test di verifica compilazione. Azure Pipelines compila il codice usando MSBuild. Per altre informazioni, vedere Azure Pipelines.

Per un'esercitazione introduttiva per MSBuild in Windows, vedere Procedura dettagliata: Uso di MSBuild.

Uso di MSBuild al prompt dei comandi

Per eseguire MSBuild al prompt dei comandi, passare un file di progetto a MSBuild.exe, insieme alle opzioni della riga di comando appropriate. Le opzioni della riga di comando consentono di impostare proprietà, eseguire destinazioni specifiche e impostare altre opzioni che controllano il processo di compilazione. Ad esempio, per compilare il file MyProj.proj con la proprietà Configuration impostata su Debug si usa la sintassi della riga di comando seguente.

MSBuild.exe MyProj.proj -property:Configuration=Debug

MSBuild non modifica il comportamento in base all'estensione del file, ma la convenzione consiste nell'usare le estensioni che proj terminano, ad esempio .csproj, .vcxprojo .vbproj, per il file di input MSBuild principale, denominato "file di progetto".

Per altre informazioni sulle opzioni della riga di comando di MSBuild, vedere Informazioni di riferimento sulla riga di comando.

Importante

Prima di scaricare un progetto, determinare l'attendibilità del codice.

Per .NET Core e .NET 5 o versione successiva, in genere si usa dotnet build per richiamare MSBuild. Vedere dotnet build.See dotnet build. Se si installa solo .NET SDK e non Visual Studio o Visual Studio Build Tools, è disponibile solo MSBuild tramite dotnet build.

La riga dotnet build --help di comando elenca le opzioni della riga di comando specifiche di dotnet build, non tutte le opzioni di MSBuild.exe, ma è comunque possibile usare tutte le opzioni della riga di comando elencate nel riferimento alla riga di comando di MSBuild. Le opzioni non elaborate da dotnet build vengono passate a MSBuild.

File di progetto

MSBuild usa un formato di file di progetto basato su XML semplice ed estendibile. Il formato di file di progetto MSBuild consente agli sviluppatori di descrivere gli elementi che devono essere compilati e di come devono essere compilati per diversi sistemi operativi e configurazioni. Gli sviluppatori hanno inoltre la possibilità di creare regole di compilazione riutilizzabili che possono essere organizzate in file separati. Ciò consente di eseguire in modo coerente le compilazioni relative ai vari progetti del prodotto.

Il sistema di compilazione di Visual Studio archivia la logica specifica del progetto nel file di progetto stesso e usa i file XML MSBuild importati con estensioni come .props e .targets per definire la logica di compilazione standard. I .props file definiscono le proprietà di MSBuild e .targets i file definiscono le destinazioni MSBuild. Queste importazioni sono talvolta visibili nel file di progetto di Visual Studio, ma nei progetti più recenti, ad esempio .NET Core, .NET 5 e .NET 6, non vengono visualizzate le importazioni nel file di progetto. Viene invece visualizzato un riferimento ALL'SDK simile al seguente:

<Project Sdk="Microsoft.Net.Sdk">

Questi sono denominati progetti in stile SDK. Quando si fa riferimento a un SDK, ad esempio .NET SDK, le importazioni di .props file e .target vengono specificate in modo implicito dall'SDK.

Le sezioni seguenti descrivono alcuni degli elementi di base del formato di file di progetto MSBuild. Per un'esercitazione su come creare un file di progetto di base, vedere Procedura dettagliata: Creazione di un nuovo file di progetto MSBuild.

Proprietà

Le proprietà sono coppie di chiave/valore che possono essere usate per configurare le compilazioni. Per dichiarare le proprietà, è necessario creare un elemento con lo stesso nome della proprietà, come figlio di un elemento PropertyGroup. Tramite il codice seguente, ad esempio, viene creata una proprietà denominata BuildDir con un valore Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

È possibile definire una proprietà in modo condizionale aggiungendo un attributo Condition nell'elemento. Il contenuto degli elementi condizionali viene elaborato solo se la condizione risulta essere true. Nell'esempio seguente la Configuration proprietà viene definita se non è ancora stata definita.

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

Nel file di progetto, per fare riferimento a una proprietà, si usa la sintassi $(<PropertyName>). È possibile, ad esempio, fare riferimento alle proprietà degli esempi precedenti usando $(BuildDir) e $(Configuration).

Per altre informazioni sulle proprietà, vedere Proprietà di MSBuild.

Articoli

Gli elementi sono input nel sistema di compilazione e, in genere, rappresentano i file. Gli elementi vengono raggruppati in tipi di elemento in base ai nomi degli elementi definiti dall'utente. Tali tipi di elemento possono essere usati come parametri per le attività, le quali a loro volta utilizzano i singoli elementi dei tipi per eseguire i passaggi del processo di compilazione.

Per dichiarare gli elementi nel file di progetto è necessario creare, come figlio di un elemento ItemGroup, un elemento con lo stesso nome del tipo di elemento. Ad esempio, il codice seguente crea un tipo di elemento denominato Compile che include due file.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Nel file di progetto è possibile fare riferimento ai tipi di elementi usando la sintassi @(<ItemType>). Ad esempio, per fare riferimento al tipo di elemento dell'esempio si utilizza la sintassi @(Compile).

In MSBuild, i nomi di elementi e attributi prevedono la distinzione tra maiuscole e minuscole. I nomi di proprietà, elementi e metadati, invece, non prevedono tale distinzione. Nell'esempio seguente viene creato il tipo di elemento Compile, comPile o con qualsiasi altra variazione di maiuscole o minuscole e viene assegnato a esso il valore "one.cs;two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Gli elementi possono essere dichiarati usando caratteri jolly e, negli scenari di compilazione più avanzati, possono contenere metadati aggiuntivi. Per altre informazioni sugli elementi, vedere Elementi.

Attività

Le attività sono unità di codice eseguibile usate dai progetti MSBuild per eseguire operazioni di compilazione. Ad esempio, un'attività potrebbe compilare file di input o eseguire uno strumento esterno. Le attività possono essere riutilizzate e condivise da sviluppatori diversi in progetti diversi.

La logica di esecuzione di un'attività viene scritta nel codice gestito e mappata a MSBuild usando l'elemento UsingTask . Per scrivere un'attività personalizzata, è sufficiente creare un tipo gestito che implementi l'interfaccia ITask. Per altre informazioni su come scrivere le attività, vedere Scrittura di attività.

MSBuild include attività comuni che è possibile modificare in base alle proprie esigenze. Alcuni esempi sono Copy per eseguire la copia dei file, MakeDir per creare le directory e Csc per compilare i file di codice sorgente di Visual C#. Per l'elenco delle attività disponibili e delle relative informazioni sull'uso, vedere Informazioni di riferimento sulle attività.

Un'attività viene eseguita in un file di progetto MSBuild creando un elemento con il nome dell'attività come figlio di un elemento Target . In genere le attività accettano parametri che vengono passati come attributi dell'elemento. Sia le proprietà di MSBuild che gli elementi possono essere usati come parametri. Ad esempio, il codice seguente chiama l'attività MakeDir e le passa il valore della proprietà BuildDir dichiarata nell'esempio precedente.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Per altre informazioni sulle attività, vedere Attività.

Target

Le destinazioni raggruppano le attività in un determinato ordine ed espongono le sezioni del file di progetto come punti di ingresso al processo di compilazione. Le destinazioni vengono spesso raggruppate in sezioni logiche per garantire una maggiore leggibilità e consentire l'espansione. La suddivisione delle istruzioni di compilazione in più destinazioni consente di chiamare una parte del processo di compilazione da altre destinazioni senza dover copiare la corrispondente sezione di codice in ognuna di esse. Ad esempio, se alcuni punti di ingresso al processo di compilazione richiedono la compilazione di riferimenti, è possibile creare una destinazione che compila riferimenti e quindi eseguire tale destinazione da ognuno dei suddetti punti di ingresso.

Per dichiarare una destinazione nel file di progetto si usa l'elemento Target. Il codice seguente crea ad esempio una destinazione denominata Compile, che a sua volta chiama l'attività Csc con l'elenco di elementi dichiarato nell'esempio precedente.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

Negli scenari più avanzati, è possibile usare le destinazioni per descrivere relazioni reciproche ed eseguire analisi delle dipendenze, così da poter ignorare intere sezioni del processo di compilazione per le destinazioni che risultano essere già aggiornate. Per altre informazioni sulle destinazioni, vedere Destinazioni.

Log di compilazione

È possibile registrare errori di compilazione, avvisi e messaggi sulla console o in un altro dispositivo di output. Per altre informazioni, vedere Recupero dei log di compilazione con MSBuild.

Uso di MSBuild in Visual Studio

Visual Studio usa il formato di file di progetto MSBuild per archiviare le informazioni di compilazione sui progetti gestiti. Le impostazioni del progetto aggiunte o modificate tramite l'interfaccia di Visual Studio vengono riflesse nel file con estensione proj generato per ogni progetto. Visual Studio usa un'istanza ospitata di MSBuild per compilare progetti gestiti. Ciò significa che un progetto gestito può essere compilato in Visual Studio o al prompt dei comandi (anche se Visual Studio non è installato) e i risultati saranno identici.

Per un'esercitazione sull'uso di MSBuild in Visual Studio, vedere Procedura dettagliata: Uso di MSBuild.

Multitargeting

Usando Visual Studio, è possibile compilare un'applicazione da eseguire in una delle diverse versioni di .NET Framework o .NET Core, tra cui .NET 5 e versioni successive. Ad esempio, è possibile compilare un'applicazione da eseguire in .NET Framework 4 in una piattaforma a 32 bit ed è possibile compilare la stessa applicazione da eseguire in .NET Framework 4.8 in una piattaforma a 64 bit. La possibilità di compilare in più framework è denominata multitargeting.

Di seguito sono riportati alcuni dei vantaggi del multitargeting:

  • È possibile sviluppare applicazioni destinate a versioni precedenti di .NET Framework, ad esempio le versioni 3.5 e 4.7.2.

  • L'applicazione può essere destinata a un profilo del framework, vale a dire un subset predefinito di un framework di destinazione.

  • Se viene rilasciato un Service Pack per la versione corrente di .NET Framework, è possibile specificarlo come destinazione.

  • Il multitargeting garantisce che un'applicazione utilizzi solo le funzionalità disponibili nel framework e nella piattaforma di destinazione.

Per altre informazioni, vedere Multitargeting.

Personalizzazione della compilazione

MSBuild offre supporto per un'ampia gamma di scenari di compilazione personalizzati. La maggior parte delle funzionalità predefinite può essere sottoposta a override o estesa. Vedere Personalizzare la compilazione.

Accesso a MSBuild a livello di codice

Se si sviluppa uno strumento di compilazione, è possibile richiamare MSBuild a livello di codice da un'applicazione .NET. Usando l'API MSBuild, è possibile controllare tutti gli aspetti di un sistema di compilazione complesso. MSBuild fornisce un pacchetto NuGet con un'API completa (lo spazio dei nomi Microsoft.Build) che è possibile usare da un'applicazione .NET per questi scopi. Vedere Usare l'API MSBuild.

MSBuild è open source

MSBuild è un progetto open source che accetta contributi utente, proprio come il resto dell'ecosistema .NET. Il repository che contiene l'origine MSBuild è disponibile in GitHub: repository GitHub MSBuild.

Vedi anche

Posizione Descrizione
Procedura dettagliata: Creazione di un nuovo file di progetto MSBuild Mostra come creare in modo incrementale un file di progetto di base usando soltanto un editor di testo.
Procedura dettagliata: uso di MSBuild Introduce i blocchi predefiniti di MSBuild e mostra come scrivere, modificare ed eseguire il debug di progetti MSBuild senza chiudere l'IDE di Visual Studio.
Concetti relativi a MSBuild Presenta i quattro blocchi predefiniti di MSBuild: proprietà, elementi, destinazioni e attività.
Articoli Vengono descritti i concetti generali relativi al formato di file MSBuild e al modo in cui le parti si integrano.
Proprietà di MSBuild Introduce proprietà e raccolte di proprietà. Le proprietà sono coppie di chiave/valore che possono essere usate per configurare le compilazioni
Destinazioni Spiega come raggruppare le attività in un dato ordine e consentire che determinate sezioni del processo di compilazione vengano richiamate dalla riga di comando.
Attività Illustra come creare un'unità di codice eseguibile che può essere usata da MSBuild per eseguire operazioni di compilazione atomica.
Condizioni Descrive come usare l'attributo Condition in un elemento MSBuild.
Batch Illustra in che modo MSBuild classifica gli elenchi di elementi in base ai metadati per l'esecuzione in attività e destinazioni.
Multitargeting Illustra come impostare come destinazione più versioni di .NET e/o più piattaforme.
Recupero di log di compilazione Descrive come registrare eventi, messaggi ed errori.
Modalità di compilazione dei progetti di MSBuild Descrive il processo di compilazione interno usato in MSBuild
Creare un'attività personalizzata per la generazione di codice Illustra come creare un'attività personalizzata con un esempio di codice.
Usare MSBuild per generare un client API REST Illustra come estendere la compilazione per gestire la generazione del client API REST, con un esempio di codice.
Risorse aggiuntive Elenca risorse della community e di supporto che consentono di ottenere altre informazioni su MSBuild.

Riferimento