dotnet build

  • Articolo

Questo articolo si applica a: ✔️ .NET Core 3.1 SDK e versioni successive

Nome

dotnet build: consente di compilare un progetto e tutte le relative dipendenze.

Riepilogo

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
    [--disable-build-servers]
    [--force] [--interactive] [--no-dependencies] [--no-incremental]
    [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>]
    [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] [--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet build -h|--help

Descrizione

Il comando dotnet build compila il progetto e le relative dipendenze in un set di file binari. I file binari includono il codice del progetto nei file di linguaggio intermedio (IL) con estensione dll. A seconda del tipo di progetto e delle impostazioni, è possibile includere altri file, ad esempio:

  • Eseguibile che può essere usato per eseguire l'applicazione, se il tipo di progetto è un eseguibile con destinazione .NET Core 3.0 o versione successiva.
  • File di simboli usati per il debug con estensione pdb.
  • File con estensione deps.json che visualizza le dipendenze dell'applicazione o della libreria.
  • File con estensione runtimeconfig.json che specifica il runtime condiviso e la relativa versione per un'applicazione.
  • Altre librerie da cui dipende il progetto (tramite riferimenti al progetto o riferimenti al pacchetto NuGet).

Per i progetti eseguibili destinati a versioni precedenti a .NET Core 3.0, le dipendenze della libreria da NuGet in genere non vengono copiate nella cartella di output. Vengono risolti dalla cartella pacchetti globali NuGet in fase di esecuzione. Per queste ragioni, il prodotto di dotnet build non è pronto per essere trasferito in un altro computer per l'esecuzione. Per creare una versione dell'applicazione che può essere distribuita, è necessario pubblicarla, ad esempio con il comando dotnet publish. Per altre informazioni, vedere Distribuzione di applicazioni .NET.

Per i progetti eseguibili destinati a .NET Core 3.0 e versioni successive, le dipendenze della libreria vengono copiate nella cartella di output. Ciò significa che se non è presente alcuna logica specifica della pubblicazione, ad esempio i progetti Web, l'output di compilazione deve essere distribuibile.

Ripristino implicito

Per la compilazione è necessario il file project.assets.json, che elenca le dipendenze dell'applicazione. Il file viene creato quando dotnet restore viene eseguito. Senza il file di asset sul posto, gli strumenti non possono risolvere gli assembly di riferimento, generando così errori.

Non è necessario eseguire dotnet restore perché viene eseguito in modo implicito da tutti i comandi che richiedono un ripristino, ad esempio dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish e dotnet pack. Per disabilitare il ripristino implicito, usare l'opzione --no-restore.

Il comando dotnet restore è ancora utile in alcuni scenari in cui ha senso eseguire un ripristino esplicito, ad esempio le compilazioni di integrazione continua in Azure DevOps Services o in sistemi di compilazione che richiedono il controllo esplicito quando viene eseguito il ripristino.

Per informazioni su come gestire i feed NuGet, vedere la dotnet restore documentazione.

Questo comando supporta le opzioni dotnet restore passate nel formato continuo (ad esempio, --source). Le opzioni in formato breve, come -s, non sono supportate.

Output eseguibile o della libreria

La proprietà <OutputType> nel file di progetto determina se il progetto è eseguibile o meno. L'esempio seguente descrive un progetto che produce codice eseguibile:

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Per produrre una libreria, omettere la proprietà <OutputType> o modificarne il valore in Library. La DLL di linguaggio intermedio per una libreria non contiene punti di ingresso e non può essere eseguita.

MSBuild

Poiché dotnet build usa MSBuild per compilare il progetto, sono supportate le compilazioni parallele e incrementali. Per altre informazioni, vedere Compilazioni incrementali.

In aggiunta alle proprie opzioni, il comando dotnet build accetta anche le opzioni di MSBuild, ad esempio -p per l'impostazione delle proprietà o -l per la definizione di un logger. Per altre informazioni su queste opzioni, vedere Riferimenti alla riga di comando di MSBuild. In alternativa è anche possibile usare il comando dotnet msbuild.

Nota

Quando dotnet build viene eseguito automaticamente da dotnet run, gli argomenti come -property:property=value non vengono rispettati.

L'esecuzione di dotnet build equivale all'esecuzione di dotnet msbuild -restore. Tuttavia, il livello di dettaglio predefinito dell'output è diverso.

Download del manifesto del carico di lavoro

Quando si esegue questo comando, avvia un download in background asincrono dei manifesti pubblicitari per i carichi di lavoro. Se il download è ancora in esecuzione al termine di questo comando, il download viene arrestato. Per altre informazioni, vedere Manifesti pubblicitari.

Argomenti

PROJECT | SOLUTION

File di progetto o di soluzione da compilare. Se non viene specificato alcun file di progetto o di soluzione, MSBuild cercherà nella directory di lavoro corrente un file con estensione proj o sln e userà questo file.

Opzioni

  • -a|--arch <ARCHITECTURE>

    Specifica l'architettura di destinazione. Si tratta di una sintassi abbreviata per l'impostazione dell'identificatore di runtime (RID), in cui il valore fornito viene combinato con il RID predefinito. Ad esempio, in un computer win-x64, specificando --arch x86 si imposta il RID su win-x86. Se si usa questa opzione, non usare l'opzione -r|--runtime. Disponibile a partire da .NET 6 Preview 7.

  • -c|--configuration <CONFIGURATION>

    Definisce la configurazione di compilazione. Il valore predefinito per la maggior parte dei progetti è Debug, ma è possibile eseguire l'override delle impostazioni di configurazione della compilazione nel progetto.

  • --disable-build-servers

    Forza il comando a ignorare tutti i server di compilazione persistenti. Questa opzione consente di disabilitare in modo coerente l'uso della memorizzazione nella cache di compilazione, che forza una compilazione da zero. Una compilazione che non si basa sulle cache è utile quando le cache potrebbero essere danneggiate o errate per qualche motivo. Disponibile da .NET 7 SDK.

  • -f|--framework <FRAMEWORK>

    Esegue la compilazione per un framework specifico. Il framework deve essere definito nel file di progetto. Esempi: net7.0, net462.

  • --force

    Forza la risoluzione di tutte le dipendenze, anche se l'ultimo ripristino ha avuto esito positivo. La specifica di questo flag equivale all'eliminazione del file project.assets.json.

  • -?|-h|--help

    Stampa una descrizione di come usare il comando.

  • --interactive

    Consente al comando di arrestarsi e attendere l'input o l'azione dell'utente, ad esempio il completamento dell'autenticazione. Disponibile a partire da .NET Core 3.0 SDK.

  • --no-dependencies

    Ignora i riferimenti da progetto a progetto e compila solo il progetto radice specificato.

  • --no-incremental

    Contrassegna la compilazione come non sicura per la compilazione incrementale. Questo flag disattiva la compilazione incrementale e impone una ricompilazione pulita del grafico delle dipendenze del progetto.

  • --no-restore

    Non esegue un ripristino implicito durante la compilazione.

  • --nologo

    Non visualizza il messaggio di avvio né il messaggio di copyright.

  • --no-self-contained

    Pubblica l'applicazione come applicazione dipendente dal framework. Per eseguire l'applicazione, è necessario installare un runtime .NET compatibile nel computer di destinazione. Disponibile da .NET 6 SDK.

  • -o|--output <OUTPUT_DIRECTORY>

    Directory in cui inserire i file binari compilati. Se non specificata, il percorso predefinito è ./bin/<configuration>/<framework>/. Per i progetti con più framework di destinazione (tramite la proprietà TargetFrameworks), è necessario definire --framework anche quando si specifica questa opzione.

    • .NET 7.0.200 SDK e versioni successive

      Se si specifica l'opzione --output quando si esegue questo comando in una soluzione, l'interfaccia della riga di comando genererà un avviso (un errore nella versione 7.0.200) a causa della semantica non chiara del percorso di output. L'opzione --output non è consentita perché tutti gli output di tutti i progetti compilati verrebbero copiati nella directory specificata e questo non è compatibile con progetti con più destinazioni, né con progetti con versioni diverse di dipendenze dirette e transitive. Per altre informazioni, vedere Opzione --output a livello di soluzione non più valida per i comandi correlati alla compilazione.

  • --os <OS>

    Specifica il sistema operativo di destinazione. Si tratta di una sintassi abbreviata per l'impostazione dell'identificatore di runtime (RID), in cui il valore fornito viene combinato con il RID predefinito. Ad esempio, in un computer win-x64, specificando --os linux si imposta il RID su linux-x64. Se si usa questa opzione, non usare l'opzione -r|--runtime. Disponibile a partire da .NET 6.

  • -p|--property:<PROPERTYNAME>=<VALUE>

    Imposta una o più proprietà MSBuild. Specificare più proprietà delimitate da punti e virgola o ripetendo l'opzione:

    --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>

  • -r|--runtime <RUNTIME_IDENTIFIER>

    Specifica il runtime di destinazione. Per un elenco degli identificatori di runtime (RID, Runtime Identifier), vedere il catalogo RID. Se si usa questa opzione con .NET 6 SDK, usare --self-contained o anche --no-self-contained. Se non specificato, l'impostazione predefinita consiste nel compilare per il sistema operativo e l'architettura correnti.

  • --self-contained [true|false]

    Pubblica il runtime .NET con l'applicazione in modo che non sia necessario installare il runtime nel computer di destinazione. Se viene specificato un identificatore di runtime, il valore predefinito è true. Disponibile a partire da .NET 6.

  • --source <SOURCE>

    URI dell'origine del pacchetto NuGet da usare durante l'operazione di ripristino.

  • --tl:[auto|on|off]

    Specifica se il logger del terminale deve essere usato per l'output di compilazione. Il valore predefinito è auto, che prima di abilitare la registrazione del terminale verifica l'ambiente. Prima di abilitare il nuovo logger, il controllo dell'ambiente verifica che il terminale sia in grado di usare le funzionalità di output moderne e che non utilizzi un output standard reindirizzato. on ignora il controllo dell'ambiente e abilita la registrazione del terminale. off ignora il controllo dell'ambiente e usa il logger di console predefinito.

    Il logger del terminale mostra la fase di ripristino seguita dalla fase di compilazione. Durante ogni fase, i progetti che sono in corso di compilazione vengono visualizzati nella parte inferiore del terminale. Ogni progetto che compila restituisce sia la destinazione MSBuild attualmente in fase di compilazione che la quantità di tempo impiegato per tale destinazione. È possibile cercare queste informazioni per altre informazioni sulla compilazione. Al termine della compilazione di un progetto, viene scritta una singola sezione "compilazione completata" che acquisisce:

    • Il nome del progetto compilato.
    • Il framework di destinazione (se sono presenti più destinazioni).
    • Lo stato della compilazione.
    • L'output primario di tale compilazione (con collegamento ipertestuale).
    • Qualsiasi diagnostica generata per il progetto.

    Questa opzione è disponibile a partire da .NET 8.

  • -v|--verbosity <LEVEL>

    Imposta il livello di dettaglio del comando. I valori consentiti sono q[uiet], m[inimal], n[ormal], d[etailed] e diag[nostic]. Il valore predefinito è minimal. Per impostazione predefinita, MSBuild visualizza avvisi ed errori a tutti i livelli di dettaglio. Per escludere gli avvisi, usare /property:WarningLevel=0. Per altre informazioni, vedere LoggerVerbosity e WarningLevel.

  • --use-current-runtime, --ucr [true|false]

    Imposta su RuntimeIdentifier una piattaforma portabile RuntimeIdentifier in base a quella del computer. Ciò avviene in modo implicito con le proprietà che richiedono un oggetto RuntimeIdentifier, ad esempio SelfContained, PublishAot, PublishSelfContained, PublishSingleFile e PublishReadyToRun. Se la proprietà è impostata su false, la risoluzione implicita non verrà più eseguita.

  • --version-suffix <VERSION_SUFFIX>

    Imposta il valore della proprietà $(VersionSuffix) da usare durante la compilazione del progetto. Funziona solo se la proprietà $(Version) non è impostata. La proprietà $(Version) viene quindi impostata su $(VersionPrefix) combinata con $(VersionSuffix), separati da un trattino.

Esempi

  • Compilare un progetto e le relative dipendenze:

    dotnet build

  • Compilare un progetto e le relative dipendenze usando la configurazione per il rilascio:

    dotnet build --configuration Release

  • Compilare un progetto e le relative dipendenze per un runtime specifico (in questo esempio Linux):

    dotnet build --runtime linux-x64

  • Compilare il progetto e usare l'origine del pacchetto NuGet specificato durante l'operazione di ripristino:

    dotnet build --source c:\packages\mypackages

  • Compilare il progetto e impostare la versione 1.2.3.4 come parametro di compilazione usando l'opzione MSBuild-p:

    dotnet build -p:Version=1.2.3.4