dotnet build

Artikel
11/27/2023

Dieser Artikel gilt für: ✔️ .NET Core 3.1 SDK und höher

Name

dotnet build: Erstellt ein Projekt und alle seine Abhängigkeiten

Übersicht

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-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

Beschreibung

Der dotnet build-Befehl erstellt das Projekt und die zugehörigen Abhängigkeiten in einen Satz von Binärdateien. Die Binärdateien enthalten den Projektcode in IL-Dateien (Intermediate Language) mit der Erweiterung DLL. Abhängig vom Projekttyp und den Einstellungen können auch andere Dateien enthalten sein, beispielsweise:

Eine ausführbare Datei, die zum Ausführen der Anwendung verwendet werden kann, wenn der Projekttyp eine ausführbare Datei für .NET Core 3.0 oder höher ist.
Symboldateien mit der Erweiterung PDB, die für das Debuggen verwendet werden.
Eine Datei .deps.json, die die Abhängigkeiten der Anwendung oder Bibliothek auflistet.
Eine Datei .runtimeconfig.json, die die freigegebene Laufzeit und deren Version für eine Anwendung angibt.
Andere Bibliotheken, von denen das Projekt abhängig ist (über Projektverweise oder NuGet-Paketverweise).

Bei ausführbaren Projekten für frühere Versionen als .NET Core 3.0 werden Bibliotheksabhängigkeiten von NuGet in der Regel NICHT in den Ausgabeordner kopiert. Sie werden zur Laufzeit aus dem NuGet-Ordner für globale Pakete aufgelöst. Bedenken Sie, dass das Produkt von dotnet build nicht auf einen anderen Computer zur Ausführung übertragen werden kann. Zum Erstellen einer Version der Anwendung, die bereitgestellt werden kann, müssen Sie sie veröffentlichen (z.B. mit dem Befehl dotnet publish). Weitere Informationen finden Sie unter .NET-Anwendungsbereitstellung.

Bei ausführbaren Projekten für .NET Core 3.0 oder höher werden Bibliotheksabhängigkeiten in den Ausgabeordner kopiert. Dies bedeutet, dass die Buildausgabe bereitstellbar sein sollte, wenn keine andere veröffentlichungsspezifische Logik (wie bei Webprojekten) vorhanden ist.

Implizite Wiederherstellung

Das Erstellen erfordert die project.assets.json-Datei, die die Abhängigkeiten Ihrer Anwendung aufführt. Die Datei wird erstellt, wenn dotnet restore ausgeführt wird. Ohne die vorhandenen Ressourcendateien kann das Tool die Verweisassemblys nicht auflösen, was zu Fehlern führt.

Sie müssen dotnet restore nicht ausführen, da der Befehl implizit von allen Befehlen ausgeführt wird, die eine Wiederherstellung erfordern. Zu diesen zählen z. B. dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish und dotnet pack. Verwenden Sie die Option --no-restore, um die implizite Wiederherstellung zu deaktivieren.

In bestimmten Fällen eignet sich der dotnet restore-Befehl dennoch. Dies ist etwa bei Szenarios der Fall, in denen die explizite Wiederherstellung sinnvoll ist. Beispiele hierfür sind Continuous Integration-Builds in Azure DevOps Services oder Buildsysteme, die den Zeitpunkt für die Wiederherstellung explizit steuern müssen.

Informationen zum Verwalten von NuGet-Feeds finden Sie in der dotnet restoreDokumentation.

Dieser Befehl unterstützt die dotnet restore-Optionen, wenn sie in der Langform (z. B. --source) übergeben werden. Optionen in Kurzform wie z.B. -s werden nicht unterstützt.

Ausgabe der ausführbaren Datei oder Bibliothek

Ob das Projekt ausführbar ist oder nicht, richtet sich nach der <OutputType>-Eigenschaft in der Projektdatei. Das folgende Beispiel zeigt ein Projekt, das ausführbaren Code erzeugt:

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

Um eine Bibliothek zu generieren, lassen Sie die Eigenschaft <OutputType> weg, oder ändern Sie ihren Wert in Library. Die IL-DLL für eine Bibliothek enthält keine Einstiegspunkte und kann nicht ausgeführt werden.

MSBuild

dotnet build verwendet MSBuild zum Erstellen des Projekts und unterstützt daher parallele und inkrementelle Builds. Weitere Informationen finden Sie unter Incremental Builds (Inkrementelle Builds).

Zusätzlich zu diesen Optionen akzeptiert der dotnet build-Befehl MSBuild-Optionen, wie z.B. -p zum Festlegen von Eigenschaften oder -l zum Definieren eines Protokolls. Weitere Informationen zu diesen Optionen finden Sie in der MSBuild-Befehlszeilenreferenz. Sie können auch den Befehl dotnet msbuild verwenden.

Hinweis

Wenn dotnet build automatisch von dotnet run ausgeführt wird, werden Argumente wie -property:property=value nicht beachtet.

Das Ausführen von dotnet build entspricht der Ausführung von dotnet msbuild -restore. Die Standardausführlichkeit der Ausgabe unterscheidet sich jedoch.

Workload manifest downloads

Wenn Sie diesen Befehl ausführen, wird im Hintergrund ein asynchroner Download initiiert, der Ankündigungsmanifeste für Workloads herunterlädt. Wenn der Download noch ausgeführt wird, wenn der Befehl abgeschlossen ist, wird der Download angehalten. Weitere Informationen finden Sie unter Ankündigungsmanifeste.

Argumente

PROJECT | SOLUTION

Die zu erstellende Projekt- oder Projektmappendatei. Wenn Sie keine Projekt- oder Projektmappendatei angeben, durchsucht MSBuild das aktuelle Arbeitsverzeichnis nach einer Dateierweiterung, die mit proj oder sln endet, und verwendet diese.

Optionen

-a|--arch <ARCHITECTURE>

Legt die Zielarchitektur fest. Dies ist eine Kurzsyntax zum Setzen des Runtimebezeichners (RID), wobei der angegebene Wert mit dem Standard-RID kombiniert wird. Auf einem win-x64 Rechner wird beispielsweise durch die Angabe von --arch x86 der RID auf win-x86 gesetzt. Wenn Sie diese Option verwenden, dürfen Sie Option -r|--runtime nicht verwenden. Verfügbar seit .NET 6 Preview 7.

--artifacts-path <ARTIFACTS_DIR>

Alle Buildausgabedateien des ausgeführten Befehls werden in Unterordnern unter dem angegebenen Pfad, getrennt durch Das Projekt, verschoben. Weitere Informationen finden Sie unter "Artifacts Output Layout". Verfügbar ab dem .NET 8 SDK.

-c|--configuration <CONFIGURATION>

Legt die Buildkonfiguration fest. Der Standardwert für die meisten Projekte ist Debug, aber Sie können die Buildkonfigurationseinstellungen in Ihrem Projekt überschreiben.

--disable-build-servers

Erzwingt, dass der Befehl alle persistenten Buildserver ignoriert. Diese Option bietet eine konsistente Möglichkeit, die gesamte Verwendung von Buildcaches zu deaktivieren, wodurch die Neuerstellung eines Build von Grund auf erzwungen wird. Ein Build, der sich nicht auf Caches stützt, ist nützlich, wenn die Caches aus irgendeinem Grund beschädigt oder fehlerhaft sein können. Verfügbar ab dem .NET 7 SDK.

-f|--framework <FRAMEWORK>

Kompiliert für ein bestimmtes Framework. Das Framework muss in der Projektdatei definiert werden. Beispiele: net7.0, net462.
--force

Erzwingt das Auflösen aller Abhängigkeiten, auch wenn die letzte Wiederherstellung erfolgreich war. Dieses Flag anzugeben, entspricht dem Löschen der Datei project.assets.json.

-?|-h|--help

Gibt eine Beschreibung zur Verwendung des Befehls aus.

--interactive

Ermöglicht dem Befehl, anzuhalten und auf Benutzereingaben oder Aktionen zu warten. Beispielsweise, um die Authentifizierung abzuschließen. Verfügbar seit .NET Core 3.0 SDK.

--no-dependencies

Ignoriert Verweise zwischen Projekten (P2P) und erstellt nur das angegebene Stammprojekt.
--no-incremental

Markiert den Build als unsicher für inkrementelle Builds. Das Flag deaktiviert die inkrementelle Kompilierung und erzwingt eine komplette Neuerstellung des Abhängigkeitsdiagramms des Projekts.
--no-restore

Führt keine implizite Wiederherstellung während der Projekterstellung durch.
--nologo

Unterdrückt die Anzeige von Startbanner und Copyrightmeldung.
--no-self-contained

Veröffentlicht die Anwendung als frameworkabhängige Anwendung. Es muss eine kompatible .NET-Runtime auf dem Zielcomputer installiert sein, um die Anwendung auszuführen. Verfügbar ab .NET 6 SDK.
-o|--output <OUTPUT_DIRECTORY>

Verzeichnis, in dem die erstellten Binärdateien platziert werden. Wenn nicht angegeben, ist der Standardpfad ./bin/<configuration>/<framework>/. Bei Projekten mit mehreren Zielframeworks (über die TargetFrameworks-Eigenschaft) müssen Sie auch --framework definieren, wenn Sie diese Option angeben.
- .NET 7.0.200 SDK und höher
  
  Wenn Sie beim Ausführen dieses Befehls in einer Projektmappe die --output-Option angeben, gibt die CLI aufgrund der unklaren Semantik des Ausgabepfads eine Warnung (einen Fehler in 7.0.200) aus. Die --output-Option ist unzulässig, da alle Ausgaben aller erstellten Projekte in das angegebene Verzeichnis kopiert werden, das nicht mit Projekten mit mehreren Zielen kompatibel ist, sowie Projekten mit unterschiedlichen Versionen von direkten und transitiven Abhängigkeiten. Weitere Informationen finden Sie unter Option --output auf Projektmappenebene ist für buildbezogene Befehle nicht mehr gültig.

--os <OS>

Gibt das Zielbetriebssystem an. Dies ist eine Kompaktsyntax zum Festlegen des Runtimebezeichners (RID), wobei der angegebene Wert mit der Standard-RID kombiniert wird. Auf einem win-x64 Rechner wird beispielsweise durch die Angabe von --os linux der RID auf linux-x64 gesetzt. Wenn Sie diese Option verwenden, dürfen Sie Option -r|--runtime nicht verwenden. Verfügbar seit .NET 6.

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

Legt eine oder mehrere MSBuild Eigenschaften fest. Geben Sie mehrere Eigenschaften an, die durch Semikolons getrennt sind, oder wiederholen Sie die Option:
```
--property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
```
-r|--runtime <RUNTIME_IDENTIFIER>

Legt die Ziellaufzeit fest. Eine Liste der Runtime-IDs (RIDs) finden Sie unter RID-Katalog. Wenn Sie diese Option mit dem .NET 6 SDK verwenden, verwenden Sie auch --self-contained oder --no-self-contained. Wenn keine Angabe erfolgt, wird standardmäßig für das aktuelle Betriebssystem und die aktuelle Architektur erstellt.
--self-contained [true|false]

Veröffentlicht die .NET-Runtime mit der Anwendung, sodass die Runtime nicht auf dem Zielcomputer installiert werden muss. Wenn ein Runtime-Bezeichner angegeben ist, ist der Standardwert true. Verfügbar seit .NET 6.
--source <SOURCE>

Der URI der NuGet-Paketquelle, die während des Wiederherstellungsvorgangs zu verwenden ist.

--tl:[auto|on|off]

Gibt an, ob die Terminalprotokollierung für die Buildausgabe verwendet werden soll. Der Standardwert ist auto, mit den zunächst die Umgebung überprüft wird, bevor die Terminalprotokollierung aktiviert wird. Die Umgebungsprüfung testet, ob das Terminal moderne Ausgabefeatures verwenden kann und keine umgeleitete Standardausgabe verwendet, bevor die neue Protokollierung aktiviert wird. on überspringt die Umgebungsprüfung und aktiviert die Terminalprotokollierung. off überspringt die Umgebungsprüfung und verwendet die Standardkonsolenprotokollierung.

Die Terminalprotokollierung zeigt die Wiederherstellungsphase gefolgt von der Buildphase an. Während jeder Phase werden am unteren Rand des Terminals die derzeit erstellten Projekte angezeigt. Für jedes erstellte Projekt wird sowohl das MSBuild-Ziel für den Build als auch die Zeit ausgegeben, die für dieses Ziel aufgewendet wurde. Sie können diese Informationen durchsuchen, um mehr über den Build zu erfahren. Wenn die Erstellung eines Projekts abgeschlossen ist, wird ein einzelner Abschnitt „Build abgeschlossen“ geschrieben, in dem Folgendes erfasst wird:
- Der Name des erstellten Projekts
- Das Zielframework (bei mehreren Zielen)
- Der Status dieses Builds
- Die primäre Ausgabe dieses Builds (als Link)
- Alle für dieses Projekt generierten Diagnoseinformationen
Diese Option ist ab .NET 8 verfügbar.

-v|--verbosity <LEVEL>

Legt den Ausführlichkeitsgrad für den Befehl fest. Zulässige Werte sind q[uiet], m[inimal], n[ormal], d[etailed] und diag[nostic]. Der Standardwert ist minimal. Standardmäßig zeigt MSBuild Warnungen und Fehler auf allen Ausführlichkeitsstufen an. Zum Ausschließen von Warnungen verwenden Sie /property:WarningLevel=0. Weitere Informationen finden Sie unter LoggerVerbosity und WarningLevel.
--use-current-runtime, --ucr [true|false]

Legt den RuntimeIdentifier auf einen plattformübergreifenden RuntimeIdentifier fest, der auf dem Computer basiert. Dies erfolgt implizit bei Eigenschaften, die einen RuntimeIdentifiererfordern, z. B. SelfContained, PublishAot, PublishSelfContained, PublishSingleFile und PublishReadyToRun. Wenn die Eigenschaft auf FALSE festgelegt ist, tritt diese implizite Auflösung nicht mehr auf.
--version-suffix <VERSION_SUFFIX>

Hiermit wird der Wert der $(VersionSuffix)-Eigenschaft festgelegt, die beim Erstellen des Projekts verwendet werden soll. Dies funktioniert nur, wenn die $(Version)-Eigenschaft nicht festgelegt ist. Dann wird $(Version) auf $(VersionPrefix) festgelegt, kombiniert mit dem $(VersionSuffix), getrennt durch einen Bindestrich.

Beispiele

Erstellt ein Projekt und seine Abhängigkeiten:
```
dotnet build
```
Erstellt ein Projekt und seine Abhängigkeiten mithilfe der Release-Konfiguration:
```
dotnet build --configuration Release
```
Erstellen Sie ein Projekt und dessen Abhängigkeiten für eine bestimmte Laufzeit (in diesem Beispiel Linux):
```
dotnet build --runtime linux-x64
```
Erstellen eines Projekts und Verwenden der angegebenen NuGet-Paketquelle während des Wiederherstellungsvorgangs:
```
dotnet build --source c:\packages\mypackages
```
Erstellen eines Projekts und festlegen der Version 1.2.3.4 als Buildparameter mithilfe der -pMSBuild-Option:
```
dotnet build -p:Version=1.2.3.4
```

Freigeben über