Esercitazione: Usare MSBuild

MSBuild è la piattaforma di compilazione per Microsoft e Visual Studio. Questa esercitazione presenta i blocchi predefiniti di MSBuild e illustra come scrivere, modificare ed eseguire il debug di progetti MSBuild. Vengono fornite informazioni su:

• Creazione e modifica di un file di progetto.

• Come usare le proprietà di compilazione.

• Come usare gli elementi di build.

È possibile eseguire MSBuild da Visual Studio o dalla finestra di comando . In questa esercitazione viene creato un file di progetto MSBuild usando Visual Studio. Si modifica il file di progetto in Visual Studio e si usa la finestra di comando per compilare il progetto ed esaminare i risultati.

Installare MSBuild

Se hai Visual Studio, allora hai già MSBuild installato. Con Visual Studio 2022, viene installato nella cartella di installazione di Visual Studio. Per un'installazione predefinita tipica in Windows 10, MSBuild.exe si trova nella cartella di installazione in MSBuild\Current\Bin.

Nel programma di installazione di Visual Studio passare a singoli componentie individuare la casella di controllo per MSBuild. Viene selezionato automaticamente quando si sceglie uno degli altri carichi di lavoro da installare.

Per installare MSBuild in un sistema che non dispone di Visual Studio, passare a Build Tools per Visual Studio 2022 nella pagina di download . Un altro modo per ottenere MSBuild consiste nell'installare .NET SDK.

Creare un progetto MSBuild

Il sistema di progetto di Visual Studio si basa su MSBuild. È facile creare un nuovo file di progetto usando Visual Studio. In questa sezione viene creato un file di progetto C#. È possibile scegliere di creare invece un file di progetto Visual Basic. Nel contesto di questa esercitazione, la differenza tra i due file di progetto è secondaria.

Per creare un file di progetto

1. Aprire Visual Studio e creare un progetto:

   Nella casella di ricerca digitare winforms, quindi scegliere Crea una nuova app Windows Form (.NET Framework). Nella finestra di dialogo visualizzata scegliere Crea.

   Nella casella Nome progetto, digitare BuildApp. Immettere un percorso per la soluzione, ad esempio D:\.

2. Fare clic su OK o Crea per creare il file di progetto.

Esaminare il file di progetto

Nella sezione precedente è stato usato Visual Studio per creare un file di progetto C#. Il file di progetto è rappresentato in Esplora soluzioni dal nodo di progetto denominato BuildApp. È possibile usare l'editor di codice di Visual Studio per esaminare il file di progetto.

Per esaminare il file di progetto

1. In Esplora Soluzioni, fare clic sul nodo del progetto BuildApp.

2. Nel browser Proprietà, si noti che la proprietà file di progetto è BuildApp.csproj. Tutti i file di progetto vengono denominati con il suffisso proj. Se è stato creato un progetto Visual Basic, il nome del file di progetto sarà BuildApp.vbproj.

3. Fare di nuovo clic con il pulsante destro del mouse sul nodo del progetto, quindi scegliere Modifica BuildApp.csproj.

   Il file di progetto viene visualizzato nell'editor di codice.

Nota

Per alcuni tipi di progetto, ad esempio C++, è necessario scaricare il progetto (fare clic con il pulsante destro del mouse sul file di progetto e scegliere Scarica progetto) prima di poter aprire e modificare il file di progetto.

Destinazioni e attività

I file di progetto sono file in formato XML con il nodo radice Project.

La maggior parte dei progetti .NET ha un attributo Sdk. Questi progetti sono denominati progetti in stile SDK. Fare riferimento a un SDK significa che MSBuild importa un set di file che forniscono l'infrastruttura di compilazione per tale SDK. Se non si fa riferimento ad alcun SDK, è comunque possibile usare MSBuild, non si avranno automaticamente tutte le proprietà e le destinazioni specifiche dell'SDK disponibili.

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

Esistono molte varianti di .NET SDK per scopi speciali; sono descritti in .NET Project SDK.

Il lavoro di costruzione di un'applicazione viene eseguito con gli elementi Target e Task.

• Un'attività è la più piccola unità di lavoro, ovvero l'"atomo" di un build. Le attività sono componenti eseguibili indipendenti, che possono avere input e output. Non sono attualmente presenti attività a cui viene fatto riferimento o definito nel file di progetto. Aggiungere attività al file di progetto nelle sezioni seguenti. Per altre informazioni, vedere Attività.

• Un obiettivo è una sequenza di attività denominata. Potrebbe trattarsi di una sequenza denominata di attività, ma in modo critico, rappresenta un elemento da compilare o eseguire, quindi deve essere definito in modo orientato agli obiettivi. Per altre informazioni, vedere Obiettivi.

La destinazione predefinita non è definita nel file di progetto. Viene invece specificato nei progetti importati. L'elemento Import specifica i progetti importati. Ad esempio, in un progetto C#, la destinazione predefinita viene importata dal file Microsoft.CSharp.targets.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

I file importati vengono inseriti nel file di progetto ovunque vi si faccia riferimento.

Nei progetti in stile SDK questo elemento di importazione non viene visualizzato, poiché l'attributo SDK causa l'importazione implicita di questo file.

MSBuild tiene traccia delle destinazioni di una compilazione e garantisce che ogni destinazione venga compilata non più di una volta.

Aggiungere una destinazione e un'attività

Aggiungere una destinazione al file di progetto. Aggiungere un'attività alla destinazione che stampa un messaggio.

Per aggiungere una destinazione e un'attività

1. Aggiungere queste righe al file di progetto subito dopo l'istruzione Import o l'elemento Project di apertura.

   <Target Name="HelloWorld">
   </Target>
   

   Questo codice crea una destinazione denominata HelloWorld. Si noti che è disponibile il supporto di IntelliSense durante la modifica del file di progetto.

2. Aggiungere righe alla destinazione HelloWorld, in modo che la sezione risultante abbia un aspetto simile al seguente:

   <Target Name="HelloWorld">
     <Message Text="Hello"></Message>
     <Message Text="World"></Message>
   </Target>
   

3. Salvare il file di progetto.

L'attività Message è una delle numerose attività disponibili con MSBuild. Per un elenco completo delle attività e delle informazioni sull'utilizzo disponibili, vedere Informazioni di riferimento sulle attività.

L'attività Message accetta il valore stringa dell'attributo Text come input e lo visualizza nel dispositivo di output (o lo scrive in uno o più log, se applicabile). La destinazione HelloWorld esegue due volte il task di messaggio: prima per visualizzare "Hello" e quindi per visualizzare "World".

Costruire l'obiettivo

Se si tenta di compilare questo progetto da Visual Studio, non viene compilato l'obiettivo che hai definito. Questo perché Visual Studio sceglie la destinazione predefinita, che è ancora quella nel file di .targets importato.

Eseguire MSBuild dal Prompt dei comandi dello sviluppatore per Visual Studio per compilare il target HelloWorld definito in precedenza. Usare l'opzione della riga di comando -target o -t per selezionare la destinazione.

Nota

Verrà fatto riferimento al prompt dei comandi per sviluppatori come alla finestra di comando nelle sezioni seguenti.

Per costruire l'obiettivo:

1. Aprire la finestra di comando .

   Nella casella di ricerca sulla barra delle applicazioni iniziare a digitare il nome dello strumento, ad esempio dev o developer command prompt. Viene visualizzato un elenco di app installate che corrispondono al modello di ricerca.

   Se è necessario trovarlo manualmente, il file viene LaunchDevCmd.bat nella cartella {cartella di installazione di Visual Studio}\Common7\Tools.

2. Nella finestra di comando passare alla cartella contenente il file di progetto, in questo caso D:\BuildApp\BuildApp.

3. Eseguire msbuild con l'opzione di comando -t:HelloWorld. Questo comando seleziona e compila la destinazione HelloWorld:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output nella finestra di comando . Verranno visualizzate le due righe "Hello" e "World":

   Hello
   World
   

Nota

Se invece viene visualizzato The target "HelloWorld" does not exist in the project, probabilmente si è dimenticato di salvare il file di progetto nell'editor di codice. Salvare il file e riprovare.

Alternando tra l'editor di codice e la finestra di comando, è possibile modificare il file di progetto e visualizzare rapidamente i risultati.

Proprietà di compilazione

Le proprietà di compilazione sono coppie nome-valore che indirizzano la compilazione. Nella parte superiore del file di progetto sono già definite diverse proprietà di compilazione:

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Tutte le proprietà sono elementi figlio degli elementi PropertyGroup. Il nome della proprietà è il nome dell'elemento figlio e il valore della proprietà è l'elemento di testo dell'elemento figlio. Per esempio

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

definisce la proprietà denominata TargetFrameworkVersion, assegnando il valore stringa "net8.0"

Le proprietà di compilazione possono essere ridefinite in qualsiasi momento. Se

<TargetFrameworkVersion>net6.0</TargetFrameworkVersion>

viene visualizzato più avanti nel file di progetto o in un file importato più avanti nel file di progetto, quindi TargetFrameworkVersion accetta il nuovo valore "net6.0"

Esaminare un valore della proprietà

Per ottenere il valore di una proprietà, usare la sintassi seguente, dove PropertyName è il nome della proprietà:

$(PropertyName)

Usare questa sintassi per esaminare alcune delle proprietà nel file di progetto.

Per esaminare un valore di una proprietà

1. Nell'editor di codice sostituire la destinazione HelloWorld con questo codice:

   <Target Name="HelloWorld">
     <Message Text="Configuration is $(Configuration)" />
     <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
   </Target>
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Dovrebbero essere visualizzate queste due righe (l'output potrebbe essere diverso):

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
   

Proprietà condizionali

Molte proprietà come Configuration vengono definite in modo condizionale, ovvero l'attributo Condition viene visualizzato nell'elemento property. Le proprietà condizionali vengono definite o ridefinite solo se la condizione restituisce "true". Alle proprietà non predefinite viene assegnato il valore predefinito di una stringa vuota. Per esempio

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

significa "Se la proprietà Configuration non è ancora stata definita, definirla e assegnargli il valore "Debug".

Quasi tutti gli elementi MSBuild possono avere un attributo Condition. Per altre informazioni sull'uso dell'attributo Condition, vedere Condizioni.

Proprietà riservate

MSBuild riserva alcuni nomi di proprietà per archiviare informazioni sul file di progetto e sui file binari di MSBuild. MSBuildToolsPath è un esempio di proprietà riservata. Alle proprietà riservate viene fatto riferimento con la notazione $ come qualsiasi altra proprietà. Per altre informazioni, vedere Procedura: Fare riferimento al nome o al percorso del file di progetto e proprietà riservate e ben note di MSBuild.

Variabili di ambiente

È possibile fare riferimento alle variabili di ambiente nei file di progetto allo stesso modo delle proprietà di compilazione. Ad esempio, per usare la variabile di ambiente PATH nel file di progetto, usare $(Path). Se il progetto contiene una definizione di proprietà con lo stesso nome di una variabile di ambiente, la proprietà nel progetto esegue l'override del valore della variabile di ambiente. Per altre informazioni, vedere Procedura: Usare le variabili di ambiente in una compilazione.

Impostare le proprietà dalla riga di comando

Le proprietà possono essere definite nella riga di comando usando l'opzione della riga di comando -property o -p. I valori delle proprietà ricevuti dalla riga di comando sostituiscono i valori delle proprietà impostati nel file di progetto e nelle variabili di ambiente.

Per impostare un valore della proprietà dalla riga di comando:

1. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release
   

2. Esaminare l'output. Verrà visualizzata questa riga:

   Configuration is Release.
   

MSBuild crea la proprietà Configuration e assegna il valore "Release".

Caratteri speciali

Alcuni caratteri hanno un significato speciale nei file di progetto MSBuild. Esempi di questi caratteri includono punti e virgola (;) e asterischi (*). Per usare questi caratteri speciali come valori letterali in un file di progetto, è necessario specificarli usando la sintassi %<xx>, dove <xx> rappresenta il valore esadecimale ASCII del carattere.

Modificare l'attività Messaggio per visualizzare il valore della proprietà Configuration con caratteri speciali per renderlo più leggibile.

Per usare caratteri speciali nell'attività Messaggio:

1. Nell'editor di codice, sostituire entrambe le attività Message con questa riga:

   <Message Text="%24(Configuration) is %22$(Configuration)%22" />
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verrà visualizzata questa riga:

   $(Configuration) is "Debug"
   

Per altre informazioni, vedere caratteri speciali di MSBuild.

Elementi di costruzione

Un elemento è una parte di informazioni, in genere un nome di file, usato come input per il sistema di compilazione. Ad esempio, una raccolta di elementi che rappresentano i file di origine potrebbe essere passata a un'attività denominata Compile per compilarle in un assembly.

Tutti gli elementi sono elementi figlio degli elementi ItemGroup. Il nome dell'elemento è il nome dell'elemento figlio e il valore dell'elemento è il valore dell'attributo Include dell'elemento figlio. I valori degli elementi con lo stesso nome vengono raccolti in tipi di elemento di tale nome. Per esempio

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

definisce un gruppo di elementi contenente due elementi. Il tipo di elemento Compile ha due valori: Program.cs e Proprietà\AssemblyInfo.cs.

Il codice seguente crea lo stesso tipo di elemento dichiarando entrambi i file in un attributo Include, separati da un punto e virgola.

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

Per altre informazioni, vedere Items.

Nota

I percorsi dei file sono relativi alla cartella contenente il file di progetto MSBuild, anche se il file di progetto è un file di progetto importato. Esistono alcune eccezioni, ad esempio quando si utilizzano gli elementi Import e UsingTask.

Esaminare i valori del tipo di elemento

Per ottenere i valori di un tipo di elemento, usare la sintassi seguente, dove ItemType è il nome del tipo di elemento:

@(ItemType)

Usare questa sintassi per esaminare il tipo di elemento Compile nel file di progetto.

Per esaminare i valori del tipo di elemento:

1. Dall'editor di codice, sostituisci il compito target HelloWorld con il codice seguente:

   <Target Name="HelloWorld">
     <Message Text="Compile item type contains @(Compile)" />
   </Target>
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verrà visualizzata questa lunga riga:

   Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
   

I valori di un tipo di elemento sono separati da punti e virgola per impostazione predefinita.

Per modificare il separatore di un tipo di elemento, utilizzare la sintassi seguente, dove ItemType è il tipo di elemento e Separator è una stringa di uno o più caratteri di separazione:

@(ItemType, Separator)

Modificare l'attività Message per utilizzare i ritorni a capo (CR) e gli avanzamenti di riga (LF) (%0A%0D) e visualizzare gli elementi della compilazione uno per riga.

Per visualizzare i valori del tipo di elemento uno per riga

1. Nell'editor di codice sostituire l'attività Messaggio con questa riga:

   <Message Text="Compile item type contains @(Compile, '%0A%0D')" />
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verranno visualizzate le righe seguenti:

   Compile item type contains Form1.cs
   Form1.Designer.cs
   Program.cs
   Properties\AssemblyInfo.cs
   Properties\Resources.Designer.cs
   Properties\Settings.Designer.cs
   

Includere, escludere e caratteri jolly

È possibile usare i caratteri jolly "*", "**" e "?" con l'attributo Include per aggiungere elementi a una tipologia di elemento. Per esempio

<Photos Include="images\*.jpeg" />

aggiunge tutti i file con l'estensione di file .jpeg nella cartella immagini al tipo di elemento Foto, mentre

<Photos Include="images\**\*.jpeg" />

aggiunge tutti i file con l'estensione di file .jpeg nella immagini cartella e tutte le relative sottocartelle al tipo di elemento Photos. Per altri esempi, vedere Procedura: Selezionare i file da compilare.

Si noti che quando gli elementi vengono dichiarati vengono aggiunti al tipo di elemento. Per esempio

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

crea un tipo di elemento denominato Photo che contiene tutti i file nella immagini cartella con estensione di file di .jpeg o .gif. Queste righe sono equivalenti alla riga seguente:

<Photos Include="images\*.jpeg;images\*.gif" />

È possibile escludere un elemento da un tipo di elemento con l'attributo Exclude. Per esempio

<Compile Include="*.cs" Exclude="*Designer*">

aggiunge tutti i file con l'estensione di file .cs al tipo di elemento Compile, ad eccezione dei file i cui nomi contengono la stringa Designer. Per altri esempi, vedere Procedura: Escludere i file dalla compilazione.

L'attributo Exclude influisce solo sugli elementi aggiunti dall'attributo Include nell'elemento dell'elemento che li contiene entrambi. Per esempio

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

non escluderebbe il file Form1.cs, che è stato aggiunto nell'elemento precedente.

Includere ed escludere elementi

1. Nell'editor di codice sostituire l'attività Messaggio con questa riga:

   <Message Text="XFiles item type contains @(XFiles)" />
   

2. Aggiungere questo gruppo di elementi subito dopo l'elemento Import:

   <ItemGroup>
      <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
   </ItemGroup>
   

3. Salvare il file di progetto.

4. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Esaminare l'output. Verrà visualizzata questa riga:

   XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx
   

Metadati dell'elemento

Gli elementi possono contenere metadati oltre alle informazioni raccolte dagli attributi Include e Exclude. Le attività che richiedono più informazioni sugli elementi rispetto al solo valore dell'elemento possono usare questi metadati.

I metadati degli elementi vengono dichiarati nel file di progetto creando un elemento con il nome dei metadati come elemento figlio dell'elemento. Un elemento può avere zero o più valori di metadati. Ad esempio, l'elemento CSFile seguente include metadati relativi alla cultura con il valore "Fr".

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Per ottenere il valore dei metadati di un tipo di elemento, usare la sintassi seguente, dove ItemType è il nome del tipo di elemento e MetaDataName è il nome dei metadati:

%(ItemType.MetaDataName)

Per esaminare i metadati degli elementi:

1. Nell'editor di codice, sostituire il compito Messaggio con questa riga:

   <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verranno visualizzate le righe seguenti:

   Compile.DependentUpon:
   Compile.DependentUpon: Form1.cs
   Compile.DependentUpon: Resources.resx
   Compile.DependentUpon: Settings.settings
   

Si noti che la frase "Compile.DependentUpon" viene visualizzata più volte. L'uso dei metadati con questa sintassi all'interno di una destinazione causa l'invio in batch. L'invio in batch significa che le attività all'interno della destinazione vengono eseguite una sola volta per ogni valore di metadati univoco. L'invio in batch è l'equivalente dello script MSBuild del costrutto di programmazione comune "ciclo foreach". Per ulteriori informazioni, vedere Raggruppamento.

Metadati noti

Ogni volta che un elemento viene aggiunto a un elenco di elementi, a tale elemento vengono assegnati alcuni metadati noti. Ad esempio, %(Filename) restituisce il nome file di qualsiasi elemento. Per un elenco completo dei metadati noti, vedere metadati di elementi noti.

Per esaminare i metadati noti:

1. Nell'editor di codice, sostituisci l'attività Messaggio con questa riga:

   <Message Text="Compile Filename: %(Compile.Filename)" />
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verranno visualizzate le righe seguenti:

   Compile Filename: Form1
   Compile Filename: Form1.Designer
   Compile Filename: Program
   Compile Filename: AssemblyInfo
   Compile Filename: Resources.Designer
   Compile Filename: Settings.Designer
   

Confrontando i due esempi precedenti, è possibile notare che, anche se non tutti gli elementi nel tipo di elemento Compile hanno metadati DependentUpon, tutti gli elementi hanno i metadati filename noti.

Trasformazioni dei metadati

Gli elenchi di elementi possono essere trasformati in nuovi elenchi di elementi. Per trasformare un elenco di elementi, usare la sintassi seguente, dove <ItemType> è il nome del tipo di elemento e <MetadataName> è il nome dei metadati:

@(ItemType -> '%(MetadataName)')

Ad esempio, un elenco di elementi dei file di origine può essere trasformato in una raccolta di file oggetto usando un'espressione come @(SourceFiles -> '%(Filename).obj'). Per altre informazioni, vedere Transforms.

Per trasformare gli elementi usando i metadati:

1. Sostituisci l'attività Messaggio con questa riga nell'editor di codice:

   <Message Text="Backup files: @(Compile->'%(filename).bak')" />
   

2. Salvare il file di progetto.

3. Nella finestra di comando immettere ed eseguire questa riga:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Esaminare l'output. Verrà visualizzata questa riga:

   Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
   

Si noti che i metadati espressi in questa sintassi non causano l'invio in batch.

Passaggi successivi

Per informazioni su come creare un file di progetto semplice una volta alla volta, in Windows provare Creare un file di progetto MSBuild da zero.

Se stai usando principalmente il .NET SDK, continua a leggere su riferimento a MSBuild per i progetti del .NET SDK.

Contenuto correlato

• panoramica di MSBuild
• di riferimento di MSBuild