MSBuild

  • Artikel

Die Microsoft-Build-Engine ist eine Plattform zum Erstellen von Anwendungen. Diese Engine, die auch als MSBuild bezeichnet wird, stellt ein XML-Schema für Projektdateien bereit, mit dem sich steuern lässt, wie die Buildplattform Software und Prozesse erstellt und verarbeitet. Visual Studio verwendet MSBuild, MSBuild ist jedoch nicht von Visual Studio abhängig. Wenn Sie msbuild.exe oder dotnet build im Projekt oder in der Projektmappendatei aufrufen, können Sie Produkte in Umgebungen orchestrieren und erstellen, in denen Visual Studio nicht installiert ist.

Visual Studio verwendet MSBuild, um verwaltete Projekte zu laden und zu erstellen. Die Projektdateien in Visual Studio (CSPROJ-, VBPROJ-, VCXPROJ-Dateien und andere) enthalten MSBuild-XML-Code, der ausgeführt wird, wenn Sie ein Projekt mithilfe der IDE erstellen. Alle erforderlichen Einstellungen und Buildprozesse werden für die reguläre Entwicklungsarbeit in Visual Studio-Projekte importiert. Sie können diese jedoch in Visual Studio oder mithilfe eine XML-Editors erweitern oder ändern.

Um MSBuild auf einem Windows-System zu installieren, auf dem Visual Studio nicht installiert ist, wechseln Sie zum Abschnitt mit den Buildtools für Visual Studio 2022 auf der Downloadseite. Wenn Sie MSBuild mit dieser Methode installieren, erhalten Sie MSBuild.exe.

Für .NET Core und .NET 5 oder höher besteht eine andere Möglichkeit zum Abrufen des Äquivalents zu MSBuild in der Installation des .NET SDK. Der .NET-Buildbefehl dotnet build ist mit dem .NET SDK unter macOS, Windows oder Linux verfügbar. Der .NET-Buildbefehl dotnet build ist ein Thin-Wrapper für die .NET Core-Version von MSBuild.exe. Sie können Projekte für .NET Core sowie .NET 5 und höher mithilfe der .NET Core-Befehlszeilenschnittstelle (Command-Line Interface, CLI), die MSBuild verwendet, erstellen.

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

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

Die folgenden Beispiele veranschaulichen, wann es sich anbietet, MSBuild zum Auszuführen von Builds über die Befehlszeile anstatt über die Visual Studio-IDE aufzurufen.

  • 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 normalerweise nicht erforderlich, ermöglicht MSBuild jedoch den Zugriff auf mehr Arbeitsspeicher.

  • Sie möchten einen Build in mehreren Prozessen ausführen. Sie können die IDE jedoch verwenden, um die gleichen Ergebnisse in Projekten in C++ und C# zu erzielen.

  • Sie möchten das Buildsystem ändern. Möglicherweise möchten Sie z. B. die folgenden Aktionen aktivieren:

    • Dateien vorverarbeiten, bevor sie den Compiler erreichen.

    • Kopieren Sie die Buildausgaben an eine andere Stelle.

    • Erstellen Sie komprimierte Dateien aus den Buildausgaben.

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

Sie können Code in der Visual Studio-IDE schreiben, aber Builds mit MSBuild ausführen. Alternativ können Sie Code in der integrierten Entwicklungsumgebung (Integrated Development Environment, IDE) auf einem Entwicklungscomputer schreiben, MSBuild aber über die Befehlszeile ausführen, um Code zu erstellen, der in Zusammenarbeit mehrerer Entwickler*innen aus einem Quellrepository integriert wird.

Hinweis

Mit Azure Pipelines lassen sich Anwendungen automatisch kompilieren, testen und bereitstellen. Das Buildsystem kann Builds automatisch ausführen, wenn Entwickler Code z. B. als Teil einer fortlaufenden Integrationsstrategie oder gemäß einem Zeitplan (z. B. bei einem Build für einen nächtlichen Buildüberprüfungstest) einchecken. Azure Pipelines kompiliert Code mithilfe von MSBuild. Weitere Informationen finden Sie unter Azure Pipelines.

Ein Einführungstutorial zu MSBuild unter Windows finden Sie unter Exemplarische Vorgehensweise: Verwenden von MSBuild.

Verwenden von MSBuild an einer Eingabeaufforderung

Um MSBuild an einer Eingabeaufforderung auszuführen, übergeben Sie eine Projektdatei mit den entsprechenden Befehlszeilenoptionen an MSBuild.exe. Über Befehlszeilenoptionen können Sie Eigenschaften festlegen, bestimmte Ziele ausführen und weitere Optionen für die Steuerung des Buildprozesses festlegen. Beispielsweise verwenden Sie die folgende Befehlszeilensyntax zum Erstellen der Datei MyProj.proj, deren Configuration-Eigenschaft auf Debug festgelegt ist.

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

MSBuild ändert sein Verhalten nicht auf der Grundlage der Dateierweiterung, aber die Konvention ist es, Erweiterungen zu verwenden, die auf proj enden, wie .csproj, .vcxproj der .vbproj für die MSBuild-Haupteingabedatei, die so genannte „Projektdatei“.

Weitere Informationen zu MSBuild-Befehlszeilenoptionen finden Sie in der 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, verwenden Sie MSBuild nur über dotnet build.

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

Projektdatei

MSBuild verwendet ein einfaches und erweiterbares XML-basiertes Projektdateiformat. Mithilfe des MSBuild-Projektdateiformats können Entwickler die zu erstellenden Elemente beschreiben und angeben, wie diese Elemente für verschiedene Betriebssysteme und Konfigurationen erstellt werden müssen. Zusätzlich können Entwickler im Projektdateiformat wiederverwendbare Buildregeln erstellen, die in separate Dateien unterteilt werden können, um Builds im Produkt über verschiedene Projekte hinweg konsistent auszuführen.

Das Visual Studio Build-System speichert projektspezifische Logik in der Projektdatei und verwendet importierte MSBuild-XML-Dateien mit Erweiterungen wie .props und .targets, um die Standardbuildlogik zu definieren. Die .props-Dateien definieren MSBuild-Eigenschaften, und die .targets-Dateien definieren MSBuild-Ziele. Diese Importe sind manchmal in der Visual Studio-Projektdatei sichtbar. In neueren Projekten, wie .NET Core-, .NET 5- und .NET 6-Projekten, hingegen werden die Importe in der Projektdatei nicht angezeigt. Stattdessen werden Sie eine SDK-Referenz ähnlich der folgenden sehen:

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

Diese werden als SDK-ähnliche Projekte 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 Grundelemente 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 zur Konfiguration von Builds verwendet werden können. Eigenschaften werden deklariert, indem ein Element mit dem Namen der jeweiligen Eigenschaft als untergeordnetes Element eines PropertyGroup-Elements erstellt wird. Durch den folgenden Code wird beispielsweise die Eigenschaft BuildDir mit dem Wert Build erstellt.

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

Sie können eine Eigenschaft bedingt definieren, indem Sie ein Condition-Attribut im Element platzieren. Sofern wenn die Bedingung nicht true ergibt, wird der Inhalt bedingter Elemente ignoriert. Im folgenden Beispiel wird die Eigenschaft Configuration definiert, wenn sie noch nicht definiert wurde.

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

In der gesamten Projektdatei kann mithilfe der Syntax $(<PropertyName>) auf Eigenschaften verweisen werden. Beispielsweise wird mit $(BuildDir) und $(Configuration) auf die Eigenschaft in den vorangehenden Beispielen verwiesen.

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

Elemente

Elemente sind Eingaben in das Buildsystem und stellen in der Regel Dateien dar. Elemente werden auf Grundlage von benutzerdefinierten Elementnamen in Elementtypen gruppiert. Diese Elementtypen können als Parameter für Aufgaben verwendet werden, die mithilfe der einzelnen Elemente die Schritte des Buildprozesses ausführen.

In der Projektdatei werden Elemente deklariert, indem ein Element mit dem Namen des jeweiligen Elementtyps als untergeordnetes Element eines ItemGroup-Elements erstellt wird. Im folgenden Code wird z. B. der Elementtyp Compile mit zwei Dateien erstellt.

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

In der gesamten Projektdatei kann mithilfe der Syntax @(<ItemType>) auf Elementtypen verwiesen werden. Auf den Elementtyp im Beispiel wird beispielsweise mit @(Compile) 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 mit Platzhalterzeichen deklariert werden und zusätzliche Metadaten für erweiterte Buildszenarios enthalten. Weitere Informationen zu Elementen finden Sie unter Items (MSBuild-Elemente).

Aufgaben

Aufgaben sind Einheiten ausführbaren Codes, die in MSBuild-Projekten zum Ausführen von Buildvorgängen verwendet werden. Eine Aufgabe kann beispielsweise Eingabedateien kompilieren oder ein externes Tool ausführen. Aufgaben können wiederverwendet werden, auch von verschiedenen Entwicklern in unterschiedlichen Projekten.

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

MSBuild umfasst allgemeine Aufgaben, die Sie an Ihre jeweiligen Anforderungen anpassen können. Beispiele hierfür sind Copy zum Kopieren von Dateien, MakeDir zum Erstellen von Verzeichnissen und Csc zum Kompilieren von Visual C#-Quellcodedateien. Eine Liste der verfügbaren Aufgaben sowie Informationen zu ihrer jeweiligen Verwendung finden Sie unter MSBuild-Aufgabenreferenz.

Eine Aufgabe wird in einer MSBuild-Projektdatei ausgeführt, indem ein Element mit dem Namen der Aufgabe als untergeordnetes Element eines Target-Elements erstellt wird. Die meisten Aufgaben akzeptieren Parameter, die als Attribute des Elements übergeben werden. Als Parameter können Eigenschaften und Elemente von MSBuild verwendet werden. Der folgende Code ruft z.B. die MakeDir-Aufgabe auf und übergibt ihr den im vorangehenden Beispiel deklarierten Wert der Eigenschaft BuildDir.

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

Weitere Informationen zu Aufgaben finden Sie unter Aufgaben.

Ziele

Durch Ziele werden Aufgaben in einer bestimmten Reihenfolge gruppiert und Abschnitte der Projektdatei als Einstiegspunkte in den Buildprozess verfügbar gemacht. Ziele werden oft in logischen Abschnitten gruppiert, um ihre Lesbarkeit zu erhöhen und Erweiterungen zu ermöglichen. Wenn die Buildschritte in Ziele unterteilt werden, können Sie einen Teil des Buildprozesses in anderen Zielen aufrufen, ohne diesen Codeabschnitt in jedes Ziel kopieren zu müssen. Wenn mehrere Einstiegspunkte in den Buildprozess die Erstellung von Verweisen erfordern, können Sie beispielsweise ein Ziel erstellen, durch das Verweise erstellt werden, und dieses Ziel anschließend über jeden Einstiegspunkt ausführen, für den es erforderlich ist.

Ziele werden in der Projektdatei mithilfe des Target-Elements deklariert. Der folgende Code erstellt z.B. ein Ziel mit dem Namen Compile, das anschließend die Csc-Aufgabe mit der im vorangehenden Beispiel deklarierten Elementliste aufruft.

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

In fortgeschritteneren Szenarios können Ziele die zwischen verschiedenen Zielen bestehenden Beziehungen beschreiben und Abhängigkeitsanalysen durchführen. Wenn das jeweilige Ziel aktuell ist, können daher ganze Bereiche des Buildprozesses übersprungen werden. Weitere Informationen zu Zielen finden Sie unter Targets (MSBuild-Ziele).

Buildprotokolle

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

Verwenden von MSBuild in Visual Studio

Visual Studio verwendet das MSBuild-Projektdateiformat zum Speichern von Erstellungsinformationen zu verwalteten Projekten. Die Projekteinstellungen, die mithilfe der Visual Studio-Schnittstelle hinzugefügt oder geändert werden, werden in der .proj-Datei gespeichert, die für das jeweilige Projekt generiert wird. Visual Studio erstellt verwaltete Projekte mithilfe einer gehosteten Instanz von MSBuild. Das bedeutet, dass ein verwaltetes Projekt mit demselben Ergebnis entweder in Visual Studio oder über eine Befehlszeile erstellt werden kann (auch wenn Visual Studio nicht installiert ist).

Ein Tutorial zur Verwendung von MSBuild in Visual Studio finden Sie unter Exemplarische Vorgehensweise: Verwenden von MSBuild.

Festlegung von Zielversionen

Mithilfe von Visual Studio können Sie eine Anwendung kompilieren, die mit einer von mehreren Versionen von .NET Framework oder .NET Core ausgeführt werden kann, einschließlich .NET 5 und höher. Sie können eine Anwendung z. B. zweimal kompilieren: einmal so, dass sie unter .NET Framework 4 auf einer 32-Bit-Plattform ausgeführt werden kann, und einmal so, dass sie auf .NET Framework 4.8 auf einer 64-Bit-Plattform ausgerichtet ist. Die Möglichkeit, für mehr als ein Framework zu kompilieren, wird Festlegung von Zielversionen genannt.

In Folgenden sind einige Vorteile der Festlegung auf mehrere Zielversionen aufgeführt:

  • Sie können Anwendungen für frühere Versionen von .NET Framework entwickeln, z. B. für die Version 3.5 und 4.7.2.

  • Sie können auf ein Frameworkprofil abzielen, das einer vordefinierten Teilmenge eines Zielframeworks entspricht.

  • Wenn ein neues Service Pack für die aktuelle .NET Framework-Version veröffentlicht wird, können Sie auch dafür Software schreiben.

  • Durch die Festlegung von Zielversionen wird garantiert, dass von einer Anwendung nur die im Zielframework und die auf der Zielplattform verfügbaren Funktionen verwendet werden.

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 über eine .NET-Anwendung aufrufen. Mithilfe der MSBuild-API können Sie alle Aspekte eines komplexen Buildsystems steuern. MSBuild stellt ein NuGet-Paket mit einer vollständigen API (Microsoft.Build-Namespace) bereit, die Sie in einer .NET-Anwendung für diese Zwecke verwenden können. Weitere Informationen finden Sie unter Verwenden der MSBuild-API.

MSBuild ist ein Open-Source-Angebot

MSBuild ist ein Open-Source-Projekt, das wie das gesamte .NET-Ökosystem Beiträge von Benutzer*innen akzeptiert. Das Repository, das die MSBuild-Quelle enthält, ist auf GitHub im MSBuild-GitHub-Repository verfügbar.

Siehe auch

Titel Beschreibung
Exemplarische Vorgehensweise: Erstellen einer neuen MSBuild-Projektdatei Hier wird veranschaulicht, wie eine Projektbasisdatei nur mit einem Texteditor inkrementell erstellt wird.
Exemplarische Vorgehensweise: Verwenden von MSBuild Die Bausteine von MSBuild werden eingeführt, und es wird gezeigt, wie MSBuild-Projekte erstellt, bearbeitet und debuggt werden, ohne die Visual Studio-IDE zu schließen.
MSBuild-Grundlagen Stellt die vier Bausteine von MSBuild dar: Eigenschaften, Elemente, Ziele und Aufgaben.
Elemente Beschreibt die allgemeinen Konzepte hinter dem MSBuild-Dateiformat sowie das Zusammenwirken der einzelnen Teile.
MSBuild-Eigenschaften Hierin werden Eigenschaften und Eigenschaftenauflistungen eingeführt. Eigenschaften sind Schlüssel/Wert-Paare, die zur Konfiguration von Builds verwendet werden können.
Ziele Es wird erläutert, wie Aufgaben in einer bestimmten Reihenfolge gruppiert werden und wie Sie es ermöglichen, dass Abschnitte des Buildprozesses über die Befehlszeile aufgerufen werden.
Aufgaben Zeigt, wie eine Einheit von ausführbarem Code erstellt wird, die von MSBuild zum Ausführen unteilbarer Buildvorgänge verwendet werden kann.
Conditions (MSBuild-Bedingungen) Hier wird 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 mehrere .NET-Versionen und/oder mehrere Plattformen als Ziel verwendet werden.
Erhalten von Buildprotokollen Hier wird erläutert, wie Buildereignisse, Meldungen, Fehler protokolliert werden.
So erstellt MSBuild Projekte Beschreibt den internen Buildprozess, der in MSBuild verwendet wird.
Erstellen eines benutzerdefinierten Tasks für Codegenerierung Zeigt, wie ein benutzerdefinierter Task erstellt wird (mit Codebeispiel).
Verwenden von MSBuild zum Generieren eines REST-API-Clients Zeigt, wie der Build erweitert wird, um die REST-API-Clientgenerierung zu verarbeiten (mit Codebeispiel).
Zusätzliche Ressourcen Hierin werden Community- und Unterstützungsressourcen für weitere Informationen zu MSBuild aufgeführt.

Referenz

  • MSBuild-Referenz
    Links zu Themen mit Referenzinformationen.

  • Glossar
    Hier werden allgemeine Begriffe zu MSBuild definiert.