Procedura dettagliata: Creare un nuovo file di progetto MSBuild

Articolo
08/25/2023

I linguaggi di programmazione destinati a .NET Framework usano i file di progetto MSBuild per descrivere e controllare il processo di compilazione dell'applicazione. Quando si usa Visual Studio per creare un file di progetto MSBuild, il codice XML appropriato viene aggiunto automaticamente al file. Può tuttavia risultare utile comprendere l'organizzazione del codice XML e come è possibile modificarlo per controllare una compilazione.

Nota

Questo articolo è appropriato se si vogliono apprendere i concetti fondamentali di base del funzionamento di MSBuild indipendentemente da qualsiasi SDK. La compilazione con un SDK, ad esempio quando si usa dotnet build o si aggiunge l'attributo all'elemento Sdk di progetto radice, non viene trattato in questo articolo. Vedere .NET Project SDK (SDK per progetti .NET).

Per informazioni sulla creazione di un file di progetto per un progetto C++, vedere MSBuild (C++).

Questa procedura dettagliata mostra come creare in modo incrementale un file di progetto di base usando solo un editor di testo. I passaggi della procedura dettagliata sono i seguenti:

Estendere la variabile di ambiente PATH.
Creazione di un file di origine di applicazione minimo.
Creazione di un file di progetto MSBuild minimo.
Compilazione dell'applicazione tramite il file di progetto.
Aggiunta delle proprietà per controllare la compilazione.
Controllo della compilazione mediante la modifica dei valori delle proprietà.
Aggiunta delle destinazioni nella compilazione.
Controllo della compilazione specificando le destinazioni.
Eseguire la compilazione incrementale.

Questa procedura dettagliata mostra come compilare il progetto tramite il prompt dei comandi ed esaminarne i risultati. Per altre informazioni su MSBuild e sulla sua esecuzione al prompt dei comandi, vedere Procedura dettagliata: Uso di MSBuild.

Per completare la procedura dettagliata, è necessario che Visual Studio sia installato perché include MSBuild e il compilatore C#, necessari per la procedura dettagliata.

Estendere il percorso

Prima di poter usare MSBuild, è necessario estendere la variabile di ambiente PATH per includere tutti gli strumenti necessari. È possibile usare il prompt dei comandi per gli sviluppatori per Visual Studio. Cercalo in Windows 10 nella casella di ricerca nella barra delle applicazioni di Windows. Per configurare l'ambiente in un normale prompt dei comandi o in un ambiente di scripting, eseguire VSDevCmd.bat nella sottocartella Common7/Tools di un'installazione di Visual Studio.

Creare un'applicazione minima

Questa sezione illustra come creare un file di origine dell'applicazione C# minimo usando un editor di testo.

Al prompt dei comandi passare alla cartella in cui si vuole creare l'applicazione, ad esempio \Documenti\ o \Desktop\.
Creare una sottocartella denominata \HelloWorld\ e modificare la directory per passare all'interno di essa.

In un editor di testo creare un nuovo file HelloWorld.cs e quindi copiare e incollare il codice seguente:

using System;

class HelloWorld
{
    static void Main()
    {
#if DebugConfig
        Console.WriteLine("WE ARE IN THE DEBUG CONFIGURATION");
#endif

        Console.WriteLine("Hello, world!");
    }
}

Compilare l'applicazione digitando csc helloworld.cs al prompt dei comandi.
Testare l'applicazione digitando helloworld al prompt dei comandi.

Verrà visualizzato il messaggio Hello, world! .
Eliminare l'eseguibile.

Creare un file di progetto MSBuild minimo

Ora che si dispone di un file di origine di applicazione minimo, è possibile creare un file di progetto minimo per compilare l'applicazione. Questo file di progetto contiene gli elementi seguenti:

Il nodo radice Project obbligatorio.
Un nodo ItemGroup per contenere gli elementi Item.
Un elemento Item che fa riferimento al file di origine dell'applicazione.
Un nodo Target per contenere le attività necessarie per compilare l'applicazione.
Elemento Task per avviare il compilatore C# per compilare l'applicazione.

Per creare un file di progetto MSBuild minimo

Nell'editor di testo creare un nuovo file HelloWorld.csproj e immettere il codice seguente:
```
<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
</Project>
```
Contiene ItemGroup un elemento Compile elemento e specifica un file di origine come elemento.
Aggiungere un nodo Target come elemento figlio del nodo Project. Denominare il nodo Build.
```
<Target Name="Build">
</Target>
```
Inserire questo elemento Task come elemento figlio del nodo Target:
```
<Csc Sources="@(Compile)"/>
```
Salvare questo file di progetto con il nome Helloworld.csproj.

Il file di progetto minimo sarà simile al codice seguente:

<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs"/>
  </ItemGroup>
  <Target Name="Build">
    <Csc Sources="@(Compile)"/>
  </Target>
</Project>

Le attività nella destinazione Build vengono eseguite in sequenza. In questo caso, l'attività del compilatore Csc C# è l'unica attività. Questa attività deve ricevere un elenco di file di origine da compilare e tale elenco viene fornito dal valore dell'elemento Compile. L'elemento Compile fa riferimento a un solo file sorgente, Helloworld.cs.

Nota

Nell'elemento item è possibile usare il carattere jolly asterisco (*) per fare riferimento a tutti i file con estensione cs , come indicato di seguito:

<Compile Include="*.cs" />

Compilare l'applicazione

A questo punto, usare il file di progetto appena creato per compilare l'applicazione.

Al prompt dei comandi digitare msbuild helloworld.csproj -t:Build.

Viene compilata la destinazione di compilazione del file di progetto Helloworld richiamando il compilatore C# per creare l'applicazione Helloworld.
Testare l'applicazione digitando helloworld.

Verrà visualizzato il messaggio Hello, world! .

Nota

Per visualizzare più dettagli sulla build, è possibile aumentare il livello di dettaglio. Per impostare il livello di dettaglio su "detailed", al prompt dei comandi digitare questo comando:

msbuild helloworld.csproj -t:Build -verbosity:detailed

Aggiungere proprietà di compilazione

Per aumentare il controllo della compilazione è possibile aggiungere proprietà di compilazione al file di progetto. Aggiungere le proprietà seguenti:

Una proprietà AssemblyName per specificare il nome dell'applicazione.
Una proprietà OutputPath per specificare la cartella contenente l'applicazione.

Per aggiungere le proprietà di compilazione

Eliminare il file eseguibile dell'applicazione esistente (in un secondo momento si aggiungerà una Clean destinazione per gestire l'eliminazione dei file di output precedenti).

Nel file di progetto, inserire l'elemento PropertyGroup subito dopo l'elemento Project di apertura:

<PropertyGroup>
  <AssemblyName>MSBuildSample</AssemblyName>
  <OutputPath>Bin\</OutputPath>
</PropertyGroup>

Aggiungere questa attività alla destinazione Build subito prima dell'attività Csc:
```
<MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
```
L'attività MakeDir crea una cartella con il nome specificato nella proprietà OutputPath, a condizione che al momento non esistano altre cartelle con lo stesso nome.
Aggiungere questo attributo OutputAssembly all'attività Csc:
```
<Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
```
In questo modo il compilatore C# deve produrre un assembly denominato dalla AssemblyName proprietà e inserirlo nella cartella denominata dalla OutputPath proprietà .
Salvare le modifiche.

Il file di progetto sarà ora simile al codice seguente:

<Project>
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
</Project>

Nota

È consigliabile aggiungere il delimitatore di percorso barra rovesciata (\) alla fine del nome della cartella quando lo si specifica nell'elemento OutputPath , anziché aggiungerlo nell'attributo dell'attività OutputAssemblyCsc . Quindi,

<OutputPath>Bin\</OutputPath>

OutputAssembly="$(OutputPath)$(AssemblyName).exe" />

è meglio di

<OutputPath>Bin</OutputPath>

OutputAssembly="$(OutputPath)\$(AssemblyName).exe" />

Testare le proprietà di compilazione

Ora è possibile compilare l'applicazione tramite il file di progetto in cui sono state usate le proprietà di compilazione per specificare la cartella di output e il nome dell'applicazione.

Al prompt dei comandi digitare msbuild helloworld.csproj -t:Build.

Verrà creata la cartella \Bin\ e quindi richiamato il compilatore C# per creare l'applicazione MSBuildSample e la inserisce nella cartella \Bin\ .
Per verificare che la cartella \Bin\ sia stata creata e che contenga l'applicazione MSBuildSample , digitare dir Bin.
Testare l'applicazione digitando Bin\MSBuildSample per eseguire il file eseguibile.

Verrà visualizzato il messaggio Hello, world! .

Aggiungere destinazioni di compilazione

A questo punto, aggiungere altre due destinazioni al file di progetto, come segue:

Una destinazione Clean che elimina i file meno recenti.
Una destinazione Rebuild che usa l'attributo DependsOnTargets per forzare l'esecuzione dell'attività Clean prima dell'attività Build.

Ora che sono presenti più destinazioni è possibile impostare la destinazione Build come destinazione predefinita.

Per aggiungere destinazioni di compilazione

Nel file di progetto, aggiungere subito dopo la destinazione Build le due destinazioni seguenti:
```
<Target Name="Clean" >
  <Delete Files="$(OutputPath)$(AssemblyName).exe" />
</Target>
<Target Name="Rebuild" DependsOnTargets="Clean;Build" />
```
La destinazione Clean richiama l'attività Delete per eliminare l'applicazione. La destinazione Rebuild viene eseguita solo dopo l'esecuzione di entrambe le destinazioni Clean e Build. Anche se è priva di attività, la destinazione Rebuild comporta l'esecuzione della destinazione Clean prima della destinazione Build.
Aggiungere questo attributo DefaultTargets all'elemento Project di apertura:
```
<Project DefaultTargets="Build">
```
La destinazione Build viene impostata come destinazione predefinita.

Il file di progetto sarà ora simile al codice seguente:

<Project DefaultTargets="Build">
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Clean" >
    <Delete Files="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Rebuild" DependsOnTargets="Clean;Build" />
</Project>

Testare le destinazioni di compilazione

È possibile usare le nuove destinazioni di compilazione per testare le funzionalità seguenti del file di progetto:

Compilazione della build predefinita.
Impostazione del nome dell'applicazione tramite il prompt dei comandi.
Eliminazione dell'applicazione prima che venga compilata un'altra applicazione.
Eliminazione dell'applicazione senza compilare un'altra applicazione.

Per testare le destinazioni di compilazione

Al prompt dei comandi digitare msbuild helloworld.csproj -p:AssemblyName=Greetings.

Poiché non è stata usata l'opzione -t per impostare in modo esplicito la destinazione, MSBuild esegue la destinazione Build predefinita. L'opzione -p esegue l'override della proprietà AssemblyName e le assegna il nuovo valore Greetings. In questo modo viene creata una nuova applicazione Greetings.exe nella cartella \Bin\.
Per verificare che la cartella \Bin\ contenga sia l'applicazione MSBuildSample che la nuova applicazione Greetings , digitare dir Bin.
Testare l'applicazione Greetings (ad esempio, digitando Bin\Greetings in Windows).

Verrà visualizzato il messaggio Hello, world! .
Eliminare l'applicazione MSBuildSample digitando msbuild helloworld.csproj -t:clean.

Viene eseguita l'attività Clean per rimuovere l'applicazione avente il valore predefinito della proprietà AssemblyName, ovvero MSBuildSample.
Eliminare l'applicazione Greetings digitando msbuild helloworld.csproj -t:clean -p:AssemblyName=Greetings.

Viene eseguita l'attività Clean per rimuovere l'applicazione avente il valore specificato della proprietà AssemblyName, Greetings.
Per verificare che la cartella \Bin\ sia ora vuota, digitare dir Bin.
Digitare msbuild.

Anche se non è stato specificato alcun file di progetto, MSBuild compila il file helloworld.csproj, poiché nella cartella corrente è presente un solo file di progetto. In questo modo, l'applicazione MSBuildSample viene creata nella cartella \Bin\ .

Per verificare che la cartella \Bin\ contenga l'applicazione MSBuildSample , digitare dir Bin.

Eseguire la compilazione incrementale

È possibile configurare MSBuild affinché compili una destinazione solo in caso di modifica dei file di origine o dei file di destinazione da cui la destinazione dipende. MSBuild usa il timestamp di un file per determinare se è stato modificato.

Per eseguire la compilazione incrementale

Nel file di progetto, aggiungere alla destinazione di apertura Build gli attributi seguenti:
```
Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"
```
Questo specifica che la destinazione Build dipende dai file di input specificati nel gruppo di elementi Compile e che la destinazione di output è il file dell'applicazione.

La destinazione Build risultante sarà simile al codice seguente:
```
<Target Name="Build" Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe">
  <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
  <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
</Target>
```
Testare la destinazione Build digitando msbuild -v:d al prompt dei comandi.

Tenere presente che helloworld.csproj è il file di progetto predefinito e che Build è la destinazione predefinita.

L'opzione -v:d è un'abbreviazione di -verbosity:detailed usata in precedenza.

Se l'output è già stato compilato, verranno visualizzate le righe seguenti:

La destinazione "Build" verrà ignorata. Tutti i file di output sono aggiornati rispetto ai file di input.

MSBuild ignora la destinazione Build perché nessuno dei file di origine è stato modificato dall'ultima compilazione dell'applicazione.

Esempio in C#

L'esempio seguente mostra un file di progetto che compila un'applicazione C# e registra un messaggio contenente il nome del file di output.

Codice

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldCS</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <CSFile Include = "*.cs"/>
    </ItemGroup>

    <Target Name="Compile">
        <!-- Run the C# compilation using input files of type CSFile -->
        <CSC
            Sources = "@(CSFile)"
            OutputAssembly = "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the CSC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </CSC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Esempio in Visual Basic

Nell'esempio seguente viene illustrato un file di progetto che compila un'applicazione Visual Basic e registra un messaggio contenente il nome del file di output.

Codice

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldVB</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <VBFile Include = "consolehwvb1.vb"/>
    </ItemGroup>

    <Target Name = "Compile">
        <!-- Run the Visual Basic compilation using input files of type VBFile -->
        <VBC
            Sources = "@(VBFile)"
            OutputAssembly= "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the VBC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </VBC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Passaggi successivi

Visual Studio è in grado di eseguire automaticamente molte delle operazioni descritte in questa procedura dettagliata. Per informazioni su come usare Visual Studio per creare, modificare, compilare e testare i file di progetto MSBuild, vedere Procedura dettagliata: Uso di MSBuild.

Procedura dettagliata: Creare un nuovo file di progetto MSBuild

Estendere il percorso

Creare un'applicazione minima

Creare un file di progetto MSBuild minimo

Per creare un file di progetto MSBuild minimo

Compilare l'applicazione

Aggiungere proprietà di compilazione

Per aggiungere le proprietà di compilazione

Testare le proprietà di compilazione

Aggiungere destinazioni di compilazione

Per aggiungere destinazioni di compilazione

Testare le destinazioni di compilazione

Per testare le destinazioni di compilazione

Eseguire la compilazione incrementale

Per eseguire la compilazione incrementale

Esempio in C#

Codice

Esempio in Visual Basic

Codice

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

Procedura dettagliata: Creare un nuovo file di progetto MSBuild

Estendere il percorso

Creare un'applicazione minima

Creare un file di progetto MSBuild minimo

Per creare un file di progetto MSBuild minimo

Compilare l'applicazione

Aggiungere proprietà di compilazione

Per aggiungere le proprietà di compilazione

Testare le proprietà di compilazione

Aggiungere destinazioni di compilazione

Per aggiungere destinazioni di compilazione

Testare le destinazioni di compilazione

Per testare le destinazioni di compilazione

Eseguire la compilazione incrementale

Per eseguire la compilazione incrementale

Esempio in C#

Codice

Esempio in Visual Basic

Codice

Passaggi successivi

Contenuto correlato

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive