Wie MSBuild die Projekte baut

MSBuild ist das Buildmodul von Microsoft, das zum Erstellen der meisten Visual Studio-Projekte verwendet wird. MSBuild ruft Compiler und andere Tools auf, um Ihren Code zu erstellen, umfasst aber auch flexible Konfigurations- und Anpassungsoptionen sowie Infrastruktur zum Erstellen nicht nur kompilierter Binärdateien, sondern auch eine vielzahl anderer Ausgabeartefakte. MSBuild ist sehr konfigurierbar und anpassbar, aber um diese Anpassbarkeit optimal zu erreichen, ist es wichtig zu verstehen, wie MSBuild funktioniert. In diesem Artikel erfahren Sie, wie MSBuild Ihre Projektdateien verarbeitet, unabhängig davon, ob sie von Visual Studio aufgerufen werden, oder über eine Befehlszeile oder ein Skript. Wenn Sie wissen, wie MSBuild funktioniert, können Sie Probleme besser diagnostizieren und Ihren Buildprozess besser anpassen. In diesem Artikel wird der Buildprozess beschrieben und gilt weitgehend für alle Projekttypen.

Der vollständige Buildprozess besteht aus

• Anfänglicher Start : Die Verarbeitung von Befehlszeilenoptionen.
• evaluation - die Interpretation und Verarbeitung des Texts der MSBuild-Projektdatei.
• Ausführung : Führt die Ziele und Aufgaben aus, die das Projekt erstellen.

Zusätzlich zu den Quelldateien und anderen Eingabeartefakten definieren externe Importe die Details des Buildprozesses, einschließlich standardimporte wie Microsoft.Common.targets und benutzerkonfigurierbare Importe auf Lösungs- oder Projektebene.

Unternehmensgründung

MSBuild kann von Visual Studio über das MSBuild-Objektmodell in Microsoft.Build.dlloder durch Aufrufen der ausführbaren Datei (MSBuild.exe oder dotnet build) direkt auf der Befehlszeile oder in einem Skript, z. B. in CI-Systemen, aufgerufen werden. In beiden Fällen umfassen Eingaben, die sich auf den Buildprozess auswirken, die Projektdatei (oder das Projektobjekt intern in Visual Studio), möglicherweise eine Lösungsdatei, Umgebungsvariablen und Befehlszeilenoptionen oder deren Objektmodellentsprechungen. Während der Startphase werden die Befehlszeilenoptionen oder Objektmodellentsprechungen verwendet, um MSBuild-Einstellungen wie das Konfigurieren von Loggern zu konfigurieren. Eigenschaften, die mithilfe der Befehlszeile oder des -property-p Schalters festgelegt werden, werden als globale Eigenschaften festgelegt, die alle Werte überschreiben, die in den Projektdateien festgelegt würden, auch wenn Projektdateien später gelesen werden.

Die nächsten Abschnitte beziehen sich auf die Eingabedateien, z. B. Lösungsdateien oder Projektdateien.

Lösungen und Projekte

MSBuild-Instanzen können aus einem Projekt oder vielen Projekten als Teil einer Lösung bestehen. Lösungsdateien im .slnx Format oder im .sln Format werden unterstützt (in MSBuild 17.12 und höher). Die Lösungsdatei (.sln) ist keine MSBuild-XML-Datei, aber MSBuild interpretiert sie, um alle Projekte zu kennen, die für die angegebenen Konfigurations- und Plattformeinstellungen erstellt werden müssen. Wenn MSBuild diese Eingabe verarbeitet, wird sie als Lösungsbuild bezeichnet. Es gibt einige erweiterbare Punkte, mit denen Sie bei jedem Lösungsbuild etwas ausführen können, da dieser Build jedoch eine separate Ausführung von den einzelnen Projektbuilds ist, sind keine Einstellungen von Eigenschaften oder Zieldefinitionen aus dem Lösungsbuild für jeden Projektbuild relevant.

Unter "Anpassen des Lösungsbuilds" erfahren Sie, wie Sie den Lösungsbuild erweitern.

Visual Studio-Builds im Vergleich zu MSBuild.exe Builds

Es gibt einige wesentliche Unterschiede zwischen dem Erstellen von Projekten in Visual Studio im Vergleich zum direkten Aufrufen von MSBuild, entweder über die ausführbare DATEI MSBuild, oder wenn Sie das MSBuild-Objektmodell verwenden, um einen Build zu starten. Visual Studio verwaltet die Projektbuildreihenfolge für Visual Studio-Builds; es ruft nur MSBuild auf der einzelnen Projektebene auf, und wenn dies der Fall ist, werden einige boolesche Eigenschaften (BuildingInsideVisualStudio, ) festgelegt, BuildProjectReferencesdie sich erheblich auf die Funktionsweise von MSBuild auswirken. Innerhalb jedes Projekts erfolgt die Ausführung genauso wie beim Aufrufen über MSBuild, aber der Unterschied entsteht bei referenzierten Projekten. Wenn in MSBuild referenzierte Projekte erforderlich sind, wird tatsächlich ein Build ausgeführt; das heißt, MSBuild führt Aufgaben und Tools aus und generiert die Ausgabe. Wenn ein Visual Studio-Build ein referenziertes Projekt findet, gibt MSBuild nur die erwarteten Ausgaben aus dem referenzierten Projekt zurück. Es ermöglicht Visual Studio das Erstellen dieser anderen Projekte zu steuern. Visual Studio bestimmt die Build-Reihenfolge und ruft bei Bedarf separat in MSBuild auf, alles vollständig unter der Kontrolle von Visual Studio.

Ein weiterer Unterschied tritt auf, wenn MSBuild mit einer Lösungsdatei aufgerufen wird, analysiert MSBuild die Lösungsdatei, erstellt eine XML-Standardeingabedatei, wertet sie aus und führt sie als Projekt aus. Der Lösungsbuild wird vor jedem Projekt ausgeführt. Beim Erstellen von Visual Studio geschieht keines davon; MSBuild sieht die Lösungsdatei nie. Dies hat zur Folge, dass die Anpassung des Lösungsbuilds (unter Verwendung der before.SolutionName.sln.targets und after.SolutionName.sln.targets) nur für MSBuild.exedotnet build, oder objektmodellgesteuerte Builds gilt, nicht für Visual Studio-Builds.

Projekt-SDKs

Das SDK-Feature für MSBuild-Projektdateien ist relativ neu. Vor dieser Änderung importierten Projektdateien explizit die .targets - und PROP-Dateien , die den Buildprozess für einen bestimmten Projekttyp definiert haben.

.NET Core-Projekte importieren die entsprechende Version des .NET SDK. In der Übersicht finden Sie die .NET Core-Projekt-SDKs und den Verweis auf die Eigenschaften.

Evaluierungsphase

In diesem Abschnitt wird erläutert, wie diese Eingabedateien verarbeitet und analysiert werden, um In-Memory-Objekte zu erzeugen, die bestimmen, was erstellt wird.

Der Zweck der Auswertungsphase besteht darin, die Objektstrukturen im Arbeitsspeicher basierend auf den Eingabe-XML-Dateien und der lokalen Umgebung zu erstellen. Die Auswertungsphase besteht aus sechs Durchläufen, die die Eingabedateien verarbeiten, z. B. die Projekt-XML-Dateien oder die importierten XML-Dateien, die in der Regel als PROPS - oder ZIELdateien bezeichnet werden, je nachdem, ob sie in erster Linie Eigenschaften festlegen oder Buildziele definieren. Jeder Durchlauf erstellt einen Teil der In-Memory-Objekte, die später in der Ausführungsphase zum Erstellen der Projekte verwendet werden, während der Auswertungsphase treten jedoch keine tatsächlichen Buildaktionen auf. Innerhalb jedes Durchlaufs werden Elemente in der Reihenfolge verarbeitet, in der sie angezeigt werden.

Die Pässe in der Auswertungsphase sind wie folgt:

• Auswerten von Umgebungsvariablen
• Bewertung von Importen und Eigenschaften
• Auswerten von Elementdefinitionen
• Elemente auswerten
• Auswerten von UsingTask-Elementen
• Zielvorgaben evaluieren

Importe und Eigenschaften werden in der Reihenfolge ihres Auftretens in einem einzigen Durchgang ausgewertet, als ob Importe direkt in den Code eingefügt wären. Daher sind Eigenschafteneinstellungen in zuvor importierten Dateien in später importierten Dateien verfügbar.

Die Reihenfolge dieser Durchläufe hat erhebliche Auswirkungen und ist wichtig, wenn die Projektdatei angepasst wird. Siehe Eigenschafts- und Elementauswertungsreihenfolge.

Auswerten von Umgebungsvariablen

In dieser Phase werden Umgebungsvariablen verwendet, um gleichwertige Eigenschaften festzulegen. Die PATH-Umgebungsvariable wird z. B. als Eigenschaft $(PATH)verfügbar gemacht. Wenn der Befehl über die Befehlszeile oder ein Skript ausgeführt wird, wird die Befehlsumgebung normal verwendet. Und wenn er aus Visual Studio heraus ausgeführt wird, gilt die Umgebung, die beim Start von Visual Studio aktiv ist.

Bewertung von Importen und Eigenschaften

In dieser Phase wird der gesamte Eingabe-XML-Code gelesen, einschließlich der Projektdateien und der gesamten Importkette. MSBuild erstellt eine XML-Struktur im Arbeitsspeicher, die den XML-Code des Projekts und alle importierten Dateien darstellt. Derzeit werden Eigenschaften, die sich nicht in Zielen befinden, ausgewertet und festgelegt.

Da MSBuild alle XML-Eingabedateien frühzeitig während des Prozesses liest, wirken sich alle Änderungen an diesen Eingaben während des Buildvorgangs nicht auf den aktuellen Build aus.

Eigenschaften außerhalb eines Ziels werden von Eigenschaften innerhalb von Zielen anders behandelt. In dieser Phase werden nur die außerhalb eines Ziels definierten Eigenschaften ausgewertet.

Da Eigenschaften in der Reihenfolge des Eigenschaftendurchlaufs verarbeitet werden, kann eine Eigenschaft an einem beliebigen Punkt in der Eingabe auf Eigenschaftswerte zugreifen, die weiter oben in der Eingabe angezeigt werden, jedoch nicht auf Eigenschaften, die später angezeigt werden.

Da die Eigenschaften vor der Auswertung der Elemente verarbeitet werden, können Sie während irgendeines Teils des Eigenschaften-Durchgangs nicht auf den Wert eines Elements zugreifen.

Auswerten von Elementdefinitionen

In dieser Phase werden Elementdefinitionen interpretiert und eine Im-Memory-Darstellung dieser Definitionen erstellt.

Elemente auswerten

Elemente, die innerhalb eines Ziels definiert sind, werden von Elementen außerhalb eines Ziels anders behandelt. In dieser Phase werden Elemente außerhalb eines Ziels und der zugehörigen Metadaten verarbeitet. Metadaten, die durch Elementdefinitionen festgelegt werden, werden von Metadaten überschrieben, die auf Elementobjekte festgelegt sind. Da Elemente in der Reihenfolge verarbeitet werden, in der sie angezeigt werden, können Sie auf Elemente verweisen, die zuvor definiert wurden, jedoch nicht auf Elemente, die später angezeigt werden. Da der Elementdurchlauf nach dem Eigenschaftsdurchlauf erfolgt, können Elemente auf jede Eigenschaft zugreifen, wenn diese außerhalb von Zielen definiert wurde, unabhängig davon, ob die Eigenschaftsdefinition später erfolgt.

Auswerten von UsingTask Elementen

In dieser Phase werden UsingTask-Elemente gelesen, und die Aufgaben werden für die spätere Verwendung während der Ausführungsphase deklariert.

Ziele auswerten

In dieser Phase werden alle Zielobjektstrukturen im Arbeitsspeicher erstellt, zur Vorbereitung auf die Ausführung. Es findet keine tatsächliche Ausführung statt.

Ausführungsphase

In der Ausführungsphase werden die Ziele sortiert und ausgeführt, und alle Aufgaben werden ausgeführt. Zuerst werden Eigenschaften und Elemente, die innerhalb von Zielen definiert sind, in einer einzigen Phase in der Reihenfolge ausgewertet, in der sie angezeigt werden. Die Reihenfolge der Verarbeitung unterscheidet sich insbesondere davon, wie Eigenschaften und Elemente, die sich nicht in einem Ziel befinden, verarbeitet werden: zuerst alle Eigenschaften und dann alle Elemente in separaten Durchläufen. Änderungen an Eigenschaften und Elementen innerhalb eines Ziels können nach dem Ziel beobachtet werden, an dem sie geändert wurden.

Zielerstellungsreihenfolge

In einem Projekt werden Ziele seriell ausgeführt. Das zentrale Problem besteht darin, zu bestimmen, in welcher Reihenfolge alles erstellt werden soll, damit Abhängigkeiten verwendet werden, um die Ziele in der richtigen Reihenfolge zu erstellen.

Die Kompilierungsreihenfolge der Ziele wird durch die Verwendung der Attribute BeforeTargets, DependsOnTargets und AfterTargets bei jedem Ziel bestimmt. Die Reihenfolge späterer Ziele kann während der Ausführung eines früheren Ziels beeinflusst werden, wenn das frühere Ziel eine Eigenschaft ändert, auf die in diesen Attributen verwiesen wird.

Die Regeln für die Anordnung sind in Bestimmen der Ziel-Build-Reihenfolge beschrieben. Der Prozess wird durch eine Stapelstruktur bestimmt, die Ziele enthält, die erstellt werden sollen. Das Ziel oben in diesem Stapel beginnt mit der Ausführung, und wenn es von etwas anderem abhängt, werden diese Ziele an den Anfang des Stapels verschoben, und sie beginnen mit der Ausführung. Wenn ein Ziel ohne Abhängigkeiten vorhanden ist, wird es vollständig ausgeführt, und das übergeordnete Ziel wird wieder aufgenommen.

Projektverweise

Es gibt zwei Codepfade, die MSBuild annehmen kann, die normale, hier beschriebene und die diagrammoption, die im nächsten Abschnitt beschrieben wird.

Einzelne Projekte geben ihre Abhängigkeit von anderen Projekten durch ProjectReference Elemente an. Wenn ein Projekt oben im Stapel mit dem Erstellen beginnt, erreicht es den Punkt, an dem das ResolveProjectReferences Ziel ausgeführt wird, ein Standardziel, das in den gemeinsamen Zieldateien definiert ist.

ResolveProjectReferences ruft die MSBuild-Aufgabe mit Eingaben der ProjectReference Elemente auf, um die Ausgaben abzurufen. Die ProjectReference Elemente werden in lokale Elemente transformiert, z. B. Reference. Die MSBuild-Ausführungsphase für das aktuelle Projekt wird angehalten, während die Ausführungsphase beginnt, das referenzierte Projekt zu verarbeiten (die Auswertungsphase erfolgt zuerst bei Bedarf). Das referenzierte Projekt wird erst dann gebaut, wenn Sie mit dem Bau des abhängigen Projekts begonnen haben, wodurch eine Baumstruktur aus Projekten entsteht.

Visual Studio ermöglicht das Erstellen von Projektabhängigkeiten in Lösungsdateien (.sln). Die Abhängigkeiten werden in der Lösungsdatei angegeben und werden nur beim Erstellen einer Lösung oder beim Erstellen in Visual Studio beachtet. Wenn Sie ein einzelnes Projekt erstellen, wird dieser Abhängigkeitstyp ignoriert. Lösungsverweise werden von MSBuild in ProjectReference Elemente transformiert und danach auf die gleiche Weise behandelt.

Diagrammoption

Wenn Sie den Graph Build Switch (-graphBuild oder -graph) angeben, wird ProjectReference zu einem erstklassigen Konzept, das von MSBuild verwendet wird. MSBuild analysiert alle Projekte und erstellt das Buildreihenfolgendiagramm, ein tatsächliches Abhängigkeitsdiagramm von Projekten, das dann durchlaufen wird, um die Buildreihenfolge zu bestimmen. Wie bei Zielen in einzelnen Projekten stellt MSBuild sicher, dass referenzierte Projekte nach den Projekten erstellt werden, von denen sie abhängen.

Parallele Ausführung

Bei Verwendung von Multiprozessorunterstützung (-maxCpuCount oder -m Switch) erstellt MSBuild Knoten, bei denen es sich um MSBuild-Prozesse handelt, die die verfügbaren CPU-Kerne verwenden. Jedes Projekt wird an einen verfügbaren Knoten übermittelt. Innerhalb eines Knotens werden einzelne Projektbuilds seriell ausgeführt.

Aufgaben können für die parallele Ausführung aktiviert werden, indem eine boolesche Variable BuildInParallelfestgelegt wird, die gemäß dem Wert der $(BuildInParallel) Eigenschaft in MSBuild festgelegt wird. Für Aufgaben, die für die parallele Ausführung aktiviert sind, verwaltet ein Arbeitsplaner Knoten und weist Knoten Arbeit zu.

Siehe Erstellen mehrerer Projekte parallel mit MSBuild

Standardimporte

Microsoft.Common.props und Microsoft.Common.targets werden von .NET-Projektdateien (explizit oder implizit in SDK-Formatprojekten) importiert und befinden sich im Ordner "MSBuild\Current\bin" in einer Visual Studio-Installation. C++-Projekte haben eine eigene Hierarchie von Importen; siehe MSBuild Internals für C++-Projekte.

Die Datei "Microsoft.Common.props " legt die Standardwerte fest, die Sie überschreiben können. Sie wird am Anfang einer Projektdatei (explizit oder implizit) importiert. Auf diese Weise werden die Einstellungen Ihres Projekts nach den Standardwerten angezeigt, sodass sie sie überschreiben.

Die Datei "Microsoft.Common.targets " und die importierten Zieldateien definieren den Standardmäßigen Buildprozess für .NET-Projekte. Außerdem werden Erweiterungspunkte bereitgestellt, mit deren Hilfe Sie den Build anpassen können.

Bei der Implementierung ist Microsoft.Common.targets ein dünner Wrapper, der Microsoft.Common.CurrentVersion.targets importiert. Diese Datei enthält Einstellungen für Standardeigenschaften und definiert die tatsächlichen Ziele, die den Buildprozess definieren. Das Build Ziel wird hier definiert, ist aber eigentlich leer. Das Build Ziel enthält jedoch das DependsOnTargets Attribut, das die einzelnen Ziele angibt, aus denen die tatsächlichen Buildschritte bestehen, die BeforeBuild, CoreBuildund AfterBuild. Das Build Ziel wird wie folgt definiert:

  <PropertyGroup>
    <BuildDependsOn>
      BeforeBuild;
      CoreBuild;
      AfterBuild
    </BuildDependsOn>
  </PropertyGroup>

  <Target
      Name="Build"
      Condition=" '$(_InvalidConfigurationWarning)' != 'true' "
      DependsOnTargets="$(BuildDependsOn)"
      Returns="@(TargetPathWithTargetPlatformMoniker)" />

BeforeBuild und AfterBuild sind Erweiterungspunkte. Sie sind in der Datei "Microsoft.Common.CurrentVersion.targets " leer, aber Projekte können ihre eigenen BeforeBuild Und AfterBuild Ziele mit Aufgaben bereitstellen, die vor oder nach dem Hauptbuildprozess ausgeführt werden müssen. AfterBuild wird vor dem No-Op-Ziel Build ausgeführt, da es im DependsOnTargets-Attribut des Build-Ziels erscheint, aber nach CoreBuild auftritt.

Das CoreBuild Ziel enthält die Aufrufe der Build-Tools wie folgt:

  <PropertyGroup>
    <CoreBuildDependsOn>
      BuildOnlySettings;
      PrepareForBuild;
      PreBuildEvent;
      ResolveReferences;
      PrepareResources;
      ResolveKeySource;
      Compile;
      ExportWindowsMDFile;
      UnmanagedUnregistration;
      GenerateSerializationAssemblies;
      CreateSatelliteAssemblies;
      GenerateManifests;
      GetTargetPath;
      PrepareForRun;
      UnmanagedRegistration;
      IncrementalClean;
      PostBuildEvent
    </CoreBuildDependsOn>
  </PropertyGroup>
  <Target
      Name="CoreBuild"
      DependsOnTargets="$(CoreBuildDependsOn)">

    <OnError ExecuteTargets="_TimeStampAfterCompile;PostBuildEvent" Condition="'$(RunPostBuildEvent)'=='Always' or '$(RunPostBuildEvent)'=='OnOutputUpdated'"/>
    <OnError ExecuteTargets="_CleanRecordFileWrites"/>

  </Target>

In der folgenden Tabelle werden diese Ziele beschrieben; Einige Ziele gelten nur für bestimmte Projekttypen.

Viele der Ziele in der vorherigen Tabelle befinden sich in sprachspezifischen Importen, z. B. Microsoft.CSharp.targets. Diese Datei definiert die Schritte im Standardbuildprozess speziell für C#.NET-Projekte. Beispielsweise enthält es das Compile Ziel, das tatsächlich den C#-Compiler aufruft.

Vom Benutzer konfigurierbare Importe

Zusätzlich zu den Standardimporten gibt es mehrere Importe, die Sie zum Anpassen des Buildprozesses hinzufügen können.

• Directory.Build.props
• Directory.Build.targets

Diese Dateien werden von den Standardimportverfahren für jedes Projekt in den dazugehörigen Unterordnern verarbeitet. Dies befindet sich in der Regel auf der Lösungsebene, um Einstellungen für alle Projekte in der Lösung zu steuern, kann sich aber auch weiter oben im Dateisystem befinden, bis hin zum Stammverzeichnis des Laufwerks.

Die Datei "Directory.Build.props" wird von Microsoft.Common.props importiert, sodass die dort definierten Eigenschaften in der Projektdatei verfügbar sind. Sie können in der Projektdatei neu definiert werden, um die Werte pro Projekt anzupassen. Die Datei "Directory.Build.targets " wird nach der Projektdatei gelesen. Sie enthält in der Regel Ziele, aber hier können Sie auch Eigenschaften definieren, die nicht von einzelnen Projekten neu definiert werden sollen.

Anpassungen in einer Projektdatei

Visual Studio aktualisiert Ihre Projektdateien, während Sie Änderungen im Projektmappen-Explorer, im Eigenschaftenfenster oder in Project-Eigenschaften vornehmen, aber Sie können auch eigene Änderungen vornehmen, indem Sie die Projektdatei direkt bearbeiten.

Viele Buildverhaltensweisen können durch Festlegen von MSBuild-Eigenschaften konfiguriert werden, entweder in der Projektdatei für lokale Einstellungen für ein Projekt oder wie im vorherigen Abschnitt erwähnt, indem eine Directory.Build.props-Datei erstellt wird, um Eigenschaften global für ganze Ordner von Projekten und Lösungen festzulegen. Bei Ad-hoc-Builds auf der Befehlszeile oder Skripts können Sie auch die /p Option in der Befehlszeile verwenden, um Eigenschaften für einen bestimmten Aufruf von MSBuild festzulegen. Informationen zu Eigenschaften, die Sie festlegen können, finden Sie unter "Common MSBuild"-Projekteigenschaften .

Verwandte Inhalte

• Passen Sie Ihren Build an
• So erweitern Sie den Visual Studio-Buildprozess.
• MSBuild