Freigeben über

MSBuild

Das Microsoft Build Engine ist eine Plattform zum Erstellen von Anwendungen. Dieses Modul, das auch als MSBuild bezeichnet wird, stellt ein XML-Schema für eine Projektdatei bereit, das steuert, wie die Buildplattform Software verarbeitet und erstellt. Visual Studio verwendet MSBuild, aber MSBuild hängt nicht von Visual Studio ab. Durch Aufrufen von msbuild.exe oder dotnet build in Ihrer Projekt- oder Lösungsdatei können Sie Produkte in Umgebungen koordinieren und erstellen, in denen Visual Studio nicht installiert ist.

Visual Studio verwendet MSBuild zum Laden und Erstellen verwalteter Projekte. Die Projektdateien in Visual Studio (.csproj, .vbproj, .vcxprojund andere) enthalten MSBuild-XML-Code, der beim Erstellen eines Projekts in der IDE ausgeführt wird. Visual Studio-Projekte importieren alle erforderlichen Einstellungen und Buildprozesse, um typische Entwicklungsaufgaben zu erledigen, aber Sie können sie in Visual Studio oder mithilfe eines Text-Editors erweitern oder ändern.

Installieren von MSBuild

Um MSBuild auf einem Windows-System zu installieren, das nicht über Visual Studio verfügt, wechseln Sie zu Buildtools für Visual Studio auf der Downloadseite . Wenn Sie MSBuild mit dieser Methode installieren, erhalten Sie MSBuild.exe.

Für .NET Core und .NET 5 oder höher gibt es eine weitere Möglichkeit, das Äquivalent zu MSBuild zu erhalten, indem Sie das .NET SDKinstallieren. Der .NET-Buildbefehl dotnet build ist mit dem .NET SDK unter macOS, Windows oder Linux verfügbar. Der .NET-Buildbefehl dotnet build ist ein dünner Wrapper für die .NET Core-Version von MSBuild.exe. Sie können die .NET Core-Befehlszeilenschnittstelle (CLI)verwenden, die MSBuild verwendet, um Projekte zu erstellen, die auf .NET Core und .NET 5 und höher abzielen.

Informationen zu MSBuild

Ab Visual Studio 2022 wird beim Erstellen in Visual Studio die 64-Bit-Version von MSBuild verwendet.

Informationen zu MSBuild für C++ finden Sie unter MSBuild (C++).

Die folgenden Beispiele veranschaulichen, wann Sie Builds ausführen können, indem Sie MSBuild über die Befehlszeile anstelle der Visual Studio-IDE aufrufen.

  • Visual Studio ist nicht installiert.

  • Sie möchten die 64-Bit-Version von MSBuild verwenden, und Sie verwenden Visual Studio 2019 oder früher. Diese Version von MSBuild ist in der Regel nicht erforderlich, aber msBuild kann auf mehr Arbeitsspeicher zugreifen.

  • Sie möchten einen Build in mehreren Prozessen ausführen. Sie können jedoch die IDE verwenden, um dasselbe Ergebnis für Projekte in C++ und C# zu erzielen.

  • Sie möchten das Buildsystem ändern. Sie können beispielsweise die folgenden Aktionen aktivieren:

    • Vorverarbeitung von Dateien, bevor sie den Compiler erreichen.

    • Kopieren Sie die Buildausgaben an eine andere Stelle.

    • Erstellen Sie komprimierte Dateien aus Buildausgaben.

    • Führen Sie einen Nachbearbeitungsschritt aus. Beispielsweise können Sie eine Assembly mit einer anderen Version stempeln.

Sie können Code in der Visual Studio-IDE schreiben, aber Builds mithilfe von MSBuild ausführen. Als weitere Alternative können Sie Code in der IDE auf einem Entwicklungscomputer erstellen, aber MSBuild über die Befehlszeile ausführen, um Code zu erstellen, der aus einem Quell-Repository mit Zusammenarbeit von mehreren Entwicklern integriert ist.

Anmerkung

Sie können Azure Pipelines verwenden, um Ihre Anwendung automatisch zu kompilieren, zu testen und bereitzustellen. Ihr Buildsystem kann Builds automatisch ausführen, wenn Entwickler Code einchecken (z. B. als Teil einer Fortlaufenden Integrationsstrategie) oder gemäß einem Zeitplan (z. B. einem nächtlichen Buildüberprüfungstest). Azure Pipelines kompiliert Ihren Code mithilfe von MSBuild. Weitere Informationen finden Sie unter Azure Pipelines.

Ein einführendes Lernprogramm für MSBuild unter Windows finden Sie unter Walkthrough: Using MSBuild.

Verwenden von MSBuild an einer Eingabeaufforderung

Um MSBuild an einer Eingabeaufforderung auszuführen, übergeben Sie eine Projektdatei an MSBuild.exezusammen mit den entsprechenden Befehlszeilenoptionen. Mithilfe von Befehlszeilenoptionen können Sie Eigenschaften festlegen, bestimmte Ziele ausführen und andere Optionen festlegen, die den Buildprozess steuern. Sie würden beispielsweise die folgende Befehlszeilensyntax verwenden, um die Datei MyProj.proj.proj zu erstellen, wobei die Configuration-Eigenschaft auf Debugfestgelegt ist.

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

MSBuild ändert sein Verhalten nicht basierend auf der Dateierweiterung, aber die Konvention besteht darin, Erweiterungen zu verwenden, die auf proj enden, z. B. .csproj, .vcxprojoder .vbproj, für die Haupt-MSBuild-Eingabedatei, die als "Projektdatei" bezeichnet wird.

Weitere Informationen zu MSBuild-Befehlszeilenoptionen finden Sie unter Befehlszeilenreferenz.

Wichtig

Bevor Sie ein Projekt herunterladen, bestimmen Sie die Vertrauenswürdigkeit des Codes.

Für .NET Core und .NET 5 oder höher verwenden Sie in der Regel dotnet build, um MSBuild aufzurufen. Weitere Informationen finden Sie unter dotnet build. Wenn Sie nur das .NET SDK und nicht Visual Studio oder die Visual Studio Build Tools installieren, verfügen Sie nur über MSBuild über dotnet build.

Die Befehlszeile dotnet build --help listet die befehlszeilenspezifischen Optionen für dotnet buildauf, nicht alle Optionen von MSBuild.exe, aber Sie können weiterhin alle Befehlszeilenoptionen verwenden, die in der Befehlszeilenreferenz "MSBuild" aufgeführt sind. Die Optionen, die nicht von dotnet build verarbeitet werden, werden an MSBuild übergeben.

Projektdatei

MSBuild verwendet ein XML-basiertes Projektdateiformat, das unkompliziert und erweiterbar ist. Mit dem MSBuild-Projektdateiformat können Entwickler die elemente beschreiben, die erstellt werden sollen, und wie sie für verschiedene Betriebssysteme und Konfigurationen erstellt werden sollen. Darüber hinaus ermöglicht das Projektdateiformat Entwicklern das Erstellen wiederverwendbarer Buildregeln, die in separate Dateien unterteilt werden können, sodass Builds konsistent für verschiedene Projekte im Produkt ausgeführt werden können.

Das Visual Studio-Buildsystem speichert projektspezifische Logik in der Projektdatei selbst und verwendet importierte MSBuild-XML-Dateien mit Erweiterungen wie .props und .targets zum Definieren der Standardbuildlogik. Die .props Dateien definieren MSBuild-Eigenschaften, und .targets Dateien definieren MSBuild-Ziele. Diese Importe sind manchmal in der Visual Studio-Projektdatei sichtbar, aber in neueren Projekten wie .NET Core, .NET 5- und .NET 6-Projekten werden die Importe in der Projektdatei nicht angezeigt. Stattdessen wird ein SDK-Verweis angezeigt, der wie folgt aussieht:

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

Diese werden als SDK-Formatprojekte bezeichnet. Wenn Sie auf ein SDK wie das .NET SDK verweisen, werden die Importe von .props- und .target Dateien implizit vom SDK angegeben.

In den folgenden Abschnitten werden einige der grundlegenden Elemente des MSBuild-Projektdateiformats beschrieben. Ein Tutorial zum Erstellen einer einfachen Projektdatei finden Sie unter Exemplarische Vorgehensweise: Erstellen einer neuen MSBuild-Projektdatei.

Eigenschaften

Eigenschaften stellen Schlüssel-Wert-Paare dar, die zum Konfigurieren von Builds verwendet werden können. Eigenschaften werden deklariert, indem ein Element erstellt wird, das den Namen der Eigenschaft als untergeordnetes Element eines PropertyGroup--Elements besitzt. Mit dem folgenden Code wird beispielsweise eine Eigenschaft mit dem Namen BuildDir erstellt, die den Wert Buildhat.

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

Sie können eine Eigenschaft bedingt definieren, indem Sie ein Condition Attribut im Element platzieren. Der Inhalt der bedingten Elemente wird ignoriert, es sei denn, die Bedingung wird als trueausgewertet. Im folgenden Beispiel wird die Configuration-Eigenschaft definiert, wenn sie noch nicht definiert wurde.

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

Eigenschaften können in der gesamten Projektdatei mithilfe der Syntax $(<PropertyName>) referenziert werden. Beispielsweise können Sie mithilfe von $(BuildDir) und $(Configuration)auf die Eigenschaften in den vorherigen Beispielen verweisen.

Weitere Informationen zu Eigenschaften finden Sie unter MSBuild Properties (MSBuild-Eigenschaften).

Elemente

Elemente sind Eingaben im Buildsystem und stellen in der Regel Dateien dar. Elemente werden basierend auf benutzerdefinierten Elementnamen in Elementtypen gruppiert. Diese Elementtypen können als Parameter für Aufgaben verwendet werden, die die einzelnen Elemente verwenden, um die Schritte des Buildprozesses auszuführen.

Elemente werden in der Projektdatei deklariert, indem ein Element mit dem Namen des Elementtyps als untergeordnetes Element eines ItemGroup--Elements erstellt wird. Mit dem folgenden Code wird beispielsweise ein Elementtyp namens Compileerstellt, der zwei Dateien enthält.

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

Elementtypen können in der gesamten Projektdatei mithilfe der Syntax @(<ItemType>) referenziert werden. Beispielsweise wird mithilfe von @(Compile)auf den Elementtyp im Beispiel verwiesen.

In MSBuild muss bei Elementen und Attributnamen die Groß-/Kleinschreibung beachtet werden. Bei Namen von Eigenschaften, Elementen und Metadaten ist dies nicht der Fall. Im folgenden Beispiel werden der Compile-Elementtyp oder der comPile-Elementtyp oder eine beliebige andere Fallvariante erstellt und der Wert „one.cs;two.cs“ zugewiesen.

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

Elemente können mithilfe von Wildcardzeichen deklariert werden und können zusätzliche Metadaten für erweiterte Buildszenarien enthalten. Weitere Informationen zu Elementen finden Sie unter Items.

Aufgaben

Aufgaben sind Einheiten von ausführbarem Code, den MSBuild-Projekte zum Ausführen von Buildvorgängen verwenden. Beispielsweise kann eine Aufgabe Eingabedateien kompilieren oder ein externes Tool ausführen. Aufgaben können wiederverwendet werden, und sie können von verschiedenen Entwicklern in verschiedenen Projekten gemeinsam genutzt werden.

Die Ausführungslogik einer Aufgabe wird in verwaltetem Code geschrieben und msBuild mithilfe des UsingTask--Elements zugeordnet. Sie können Ihre eigene Aufgabe schreiben, indem Sie einen verwalteten Typ erstellen, der die ITask Schnittstelle implementiert. Weitere Informationen zum Schreiben von Aufgaben finden Sie unter Schreiben von Aufgaben.

MSBuild enthält allgemeine Aufgaben, die Sie an Ihre Anforderungen anpassen können. Beispiele sind Copy, die Dateien kopiert, MakeDir, die Verzeichnisse erstellt, und Csc, die Visual C#-Quellcodedateien kompiliert. Eine Liste der verfügbaren Aufgaben zusammen mit Verwendungsinformationen finden Sie unter Aufgabenreferenz.

Eine Aufgabe wird in einer MSBuild-Projektdatei ausgeführt, indem ein Element mit dem Namen des Vorgangs als untergeordnetes Element eines Target-Elements erstellt wird. Aufgaben akzeptieren in der Regel Parameter, die als Attribute des Elements übergeben werden. Sowohl MSBuild-Eigenschaften als auch Elemente können als Parameter verwendet werden. Der folgende Code ruft beispielsweise die MakeDir- Aufgabe auf und übergibt ihn den Wert der BuildDir-Eigenschaft, die im vorherigen Beispiel deklariert wurde.

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

Weitere Informationen zu Aufgaben finden Sie unter Aufgaben.

Ziele

Zielt darauf ab, Vorgänge in einer bestimmten Reihenfolge zu gruppieren und Abschnitte der Projektdatei als Einstiegspunkte in den Buildprozess verfügbar zu machen. Ziele werden häufig in logische Abschnitte gruppiert, um die Lesbarkeit zu erhöhen und die Erweiterung zu ermöglichen. Wenn Sie die Buildschritte in Ziele unterteilen, können Sie einen Teil des Buildprozesses von anderen Zielen aufrufen, ohne diesen Codeabschnitt in jedes Ziel zu kopieren. Wenn beispielsweise mehrere Einstiegspunkte in den Buildprozess Verweise erfordern, können Sie ein Ziel erstellen, das Verweise erstellt und dieses Ziel dann von jedem Einstiegspunkt aus ausführen, an dem er erforderlich ist.

Ziele werden in der Projektdatei mithilfe des Target-Elements deklariert. Mit dem folgenden Code wird beispielsweise ein Ziel mit dem Namen Compileerstellt, das dann die Csc- Aufgabe aufruft, die die Elementliste enthält, die im vorherigen Beispiel deklariert wurde.

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

In komplexeren Szenarien können Ziele verwendet werden, um Beziehungen zwischeneinander zu beschreiben und Abhängigkeitsanalysen durchzuführen, sodass ganze Abschnitte des Buildprozesses übersprungen werden können, wenn dieses Ziel up-to-date ist. Weitere Informationen zu Zielen finden Sie unter Targets.

Erstellen von Protokollen

Sie können Buildfehler, Warnungen und Meldungen an der Konsole oder einem anderen Ausgabegerät protokollieren. Weitere Informationen finden Sie unter Erhalten von Buildprotokollen mit MSBuild.

Verwenden von MSBuild in Visual Studio

Visual Studio verwendet das MSBuild-Projektdateiformat, um Buildinformationen zu verwalteten Projekten zu speichern. Projekteinstellungen, die mithilfe der Visual Studio-Schnittstelle hinzugefügt oder geändert werden, spiegeln sich in der .*proj--Datei wider, die für jedes Projekt generiert wird. Visual Studio verwendet eine gehostete Instanz von MSBuild zum Erstellen verwalteter Projekte. Dies bedeutet, dass ein verwaltetes Projekt in Visual Studio oder an einer Eingabeaufforderung erstellt werden kann (auch wenn Visual Studio nicht installiert ist), und die Ergebnisse sind identisch.

Ein Lernprogramm zur Verwendung von MSBuild in Visual Studio finden Sie unter Walkthrough: Using MSBuild.

Mehrfachzielansprache

Mithilfe von Visual Studio können Sie eine Anwendung kompilieren, die auf einer von mehreren Versionen von .NET Framework oder .NET Core ausgeführt wird, einschließlich .NET 5 und höher. Sie können beispielsweise eine Anwendung kompilieren, die auf .NET Framework 4 auf einer 32-Bit-Plattform ausgeführt wird, und Sie können dieselbe Anwendung kompilieren, die auf .NET Framework 4.8 auf einer 64-Bit-Plattform ausgeführt wird. Die Möglichkeit, für mehrere Frameworks zu kompilieren, wird als Multitargeting bezeichnet.

Dies sind einige der Vorteile von Multitargeting:

  • Sie können Anwendungen entwickeln, die auf frühere Versionen von .NET Framework abzielen, z. B. Die Versionen 3.5 und 4.7.2.

  • Sie können auf ein Frameworkprofilabzielen, bei dem es sich um eine vordefinierte Teilmenge eines Zielframeworks handelt.

  • Wenn ein Service Pack für die aktuelle Version von .NET Framework veröffentlicht wird, können Sie es als Ziel festlegen.

  • Multitargeting garantiert, dass eine Anwendung nur die Funktionalität verwendet, die im Zielframework und auf der Zielplattform verfügbar ist.

Weitere Informationen finden Sie unter Multitargeting (Festlegen von Zielversionen).

Anpassen des Builds

MSBuild bietet Unterstützung für eine vielzahl von benutzerdefinierten Buildszenarien. Die meisten integrierten Funktionen können außer Kraft gesetzt oder erweitert werden. Weitere Informationen finden Sie unter Anpassen Ihres Builds.

Programmgesteuerter Zugriff auf MSBuild

Wenn Sie ein Buildtool entwickeln, möchten Sie MSBuild möglicherweise programmgesteuert aus einer .NET-Anwendung aufrufen. Mithilfe der MSBuild-API können Sie den gesamten Aspekt eines komplexen Buildsystems steuern. MSBuild stellt ein NuGet-Paket mit einer vollständigen API (dem Microsoft.Build-Namespace) bereit, die Sie aus einer .NET-Anwendung für diese Zwecke verwenden können. Siehe Verwenden der MSBuild-API.

MSBuild ist Open Source

MSBuild ist ein Open-Source-Projekt, das Benutzerbeiträge am MSBuild GitHub-Repositoryakzeptiert.

Siehe auch

Titel Beschreibung
Exemplarische Vorgehensweise: Erstellen einer MSBuild-Projektdatei von Grund auf neu Zeigt, wie Sie eine einfache Projektdatei inkrementell erstellen, indem Sie nur einen Text-Editor verwenden.
Exemplarische Vorgehensweise: Verwenden von MSBuild Führt die Bausteine von MSBuild ein und zeigt, wie MSBuild-Projekte geschrieben, bearbeitet und gedebuggt werden, ohne die Visual Studio-IDE zu schließen.
MSBuild-Konzepte Stellt die vier Bausteine von MSBuild dar: Eigenschaften, Elemente, Ziele und Aufgaben.
Elemente Beschreibt die allgemeinen Konzepte hinter dem MSBuild-Dateiformat und die Zusammenpassung der Teile.
MSBuild-Eigenschaften Hierin werden Eigenschaften und Eigenschaftenauflistungen eingeführt. Eigenschaften sind Schlüssel-Wert-Paare, die zum Konfigurieren von Builds verwendet werden können.
Ziele Erläutert, wie Sie Aufgaben in einer bestimmten Reihenfolge gruppieren und Abschnitte des Buildprozesses aktivieren, die in der Befehlszeile aufgerufen werden.
Aufgaben Zeigt, wie Sie eine Einheit mit ausführbarem Code erstellen, die von MSBuild zum Ausführen von Atombuildvorgängen verwendet werden kann.
Bedingungen Erläutert, wie das Condition-Attribut in einem MSBuild-Element verwendet wird.
Batchverarbeitung Erläutert, wie MSBuild Elementlisten nach Metadaten für die Ausführung in Aufgaben und Zielen kategorisiert.
Festlegen von Zielversionen Zeigt, wie man mehrere .NET-Versionen und/oder Plattformen anvisiert.
Erhalten von Buildprotokollen Beschreibt, wie Buildereignisse, Nachrichten und Fehler protokolliert werden.
Wie MSBuild Projekte erstellt Beschreibt den internen Buildprozess, der in MSBuild verwendet wird.
Bewährte Methoden für sichere MSBuild-Verwendung Beschreibt die bewährten Methoden zum Konfigurieren und Ausführen Ihrer Builds mit MSBuild
Erstellen einer benutzerdefinierten Aufgabe für die Codegenerierung Zeigt, wie Sie eine benutzerdefinierte Aufgabe mit einem Codebeispiel erstellen.
Verwenden von MSBuild zum Generieren eines REST-API-Clients Zeigt, wie Sie den Build erweitern, um die REST-API-Clientgenerierung mit einem Codebeispiel zu behandeln.
Zusätzliche Ressourcen Listet Community- und Supportressourcen auf, um weitere Informationen zu MSBuild zu finden.

Referenz

  • MSBuild-Referenz
    Links zu Themen, die Referenzinformationen enthalten.

  • Glossar-
    Definiert allgemeine MSBuild-Ausdrücke.