Exemplarische Vorgehensweise: Erstellen einer neuen MSBuild-Projektdatei

Artikel
06/19/2023

Programmiersprachen für das .NET Framework verwenden MSBuild-Projektdateien zum Beschreiben und Steuern des Anwendungsbuildprozesses. Wenn Sie in Visual Studio eine MSBuild-Projektdatei erstellen, wird der Datei automatisch das entsprechende XML hinzugefügt. Ein Grundverständnis der Organisation des XML und der Änderungsmöglichkeiten zum Steuern eines Builds ist jedoch empfehlenswert.

Hinweis

Dieser Artikel ist geeignet, wenn Sie die Grundlagen der Funktionsweise von MSBuild unabhängig von SDKs kennenlernen möchten. Das Erstellen mit einem SDK, z. B. die Verwendung von dotnet build oder das Hinzufügen des Sdk-Attributs zum Stammprojektelement, wird in diesem Artikel nicht behandelt. Weitere Informationen finden Sie unter .NET SDKs für Projekte.

Weitere Informationen zum Erstellen einer Projektdatei für ein C++-Projekt finden Sie unter MSBuild (C++).

In dieser exemplarischen Vorgehensweise wird das inkrementelle Erstellen einer einfachen Projektdatei nur mit einem Texteditor veranschaulicht. In der exemplarischen Vorgehensweise werden die nachfolgenden Schritte ausgeführt:

Erweitern Sie die PATH-Umgebungsvariable.
Erstellen einer minimalen Anwendungsquelldatei
Erstellen einer minimalen MSBuild-Projektdatei
Erstellen der Anwendung mit der Projektdatei
Hinzufügen von Eigenschaften zum Steuern des Builds
Steuern des Builds durch Ändern von Eigenschaftswerten
Hinzufügen von Zielen zum Build
Steuern des Build durch Hinzufügen von Zielen
Inkrementeller Build

In dieser exemplarischen Vorgehensweise werden das Erstellen des Projekts an der Eingabeaufforderung und das Untersuchen der Ergebnisse veranschaulicht. Weitere Informationen zu MSBuild und zum Ausführen von MSBuild an der Eingabeaufforderung finden Sie unter Exemplarische Vorgehensweise: Verwenden von MSBuild.

Sie können die exemplarische Vorgehensweise nur ausführen, wenn Sie Visual Studio installiert haben, da darin MSBuild und der C#-Compiler enthalten sind, die für die exemplarische Vorgehensweise erforderlich sind.

Erweitern des Pfads

Bevor Sie MSBuild verwenden können, müssen Sie die PATH-Umgebungsvariable so erweitern, dass Sie alle erforderlichen Tools enthält. Sie können die Developer-Eingabeaufforderung für Visual Studio verwenden. Suchen Sie unter Windows 10 im Suchfeld auf der Windows-Taskleiste danach. Wenn Sie die Umgebung in einer gewöhnlichen Eingabeaufforderung oder in einer Skriptumgebung einrichten möchten, führen Sie VSDevCmd.bat im Unterordner Common7/Tools einer Visual Studio-Installation aus.

Erstellen einer minimalen Anwendung

In diesem Abschnitt wird veranschaulicht, wie Sie eine minimale Visual C#-Anwendungsquelldatei mithilfe eines Text-Editors erstellen.

Wechseln Sie an der Eingabeaufforderung zu dem Ordner, in dem Sie die Anwendung erstellen möchten, z.B. \Eigene Dateien oder \Desktop\.
Erstellen Sie einen Unterordner namens \HelloWorld\, und öffnen Sie diesen.

Erstellen Sie in einem Text-Editor eine neue Datei HelloWorld.cs, und fügen Sie dann den folgenden Code ein:

using System;

class HelloWorld
{
    static void Main()
    {
#if DebugConfig
        Console.WriteLine("WE ARE IN THE DEBUG CONFIGURATION");
#endif

        Console.WriteLine("Hello, world!");
    }
}

Erstellen Sie die Anwendung, indem Sie an der Eingabeaufforderung csc helloworld.cs eingeben.
Testen Sie die Anwendung, indem Sie an der Eingabeaufforderung helloworld eingeben.

Die Meldung Hello, World! sollte angezeigt werden.
Löschen Sie die ausführbare Datei.

Erstellen einer minimalen MSBuild-Projektdatei

Da Sie nun über eine minimale Anwendungsquelldatei verfügen, können Sie eine minimale Projektdatei für den Build der Anwendung erstellen. Diese Projektdatei enthält die folgenden Elemente:

Erforderlicher Project-Stammknoten
ItemGroup-Knoten mit Elementelementen
Elementelement, das auf die Anwendungsquelldatei verweist
Target-Knoten mit Aufgaben, die für den Build der Anwendung erforderlich sind.
Ein Task-Element, mit dem der C#-Compiler für den Build der Anwendung gestartet wird.

So erstellen Sie eine minimale MSBuild-Projektdatei

Erstellen Sie im Text-Editor eine neue Datei HelloWorld.csproj, und geben Sie den folgenden Code ein:
```
<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
</Project>
```
Diese ItemGroup enthält ein Element Compile und gibt eine Quelldatei als Element an.
Fügen Sie einen Target-Knoten als untergeordnetes Element des Project-Knotens ein. Benennen Sie den Knoten mit Build.
```
<Target Name="Build">
</Target>
```
Fügen Sie dieses Aufgabenelement als untergeordnetes Element des Target-Knotens ein:
```
<Csc Sources="@(Compile)"/>
```
Speichern Sie diese Projektdatei, und nennen Sie sie Helloworld.csproj.

Die minimale Projektdatei sollte dem folgenden Code ähneln:

<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs"/>
  </ItemGroup>
  <Target Name="Build">
    <Csc Sources="@(Compile)"/>
  </Target>
</Project>

Aufgaben im Build-Ziel werden sequenziell ausgeführt. In diesem Fall ist der Csc-Task des C#-Compilers der einzige Task. Erwartet wird eine Liste zu kompilierender Quelldateien, angegeben durch den Wert des Compile-Elements. Das Compile-Element verweist nur auf eine einzelne Quelldatei, Helloworld.cs.

Hinweis

Im Element item können Sie das Platzhalterzeichen (*) verwenden, um auf alle Dateien mit der Dateinamenerweiterung .cs zu verweisen, wie folgt:

<Compile Include="*.cs" />

Erstellen der Anwendung

Für den Build der Anwendung verwenden Sie nun die Projektdatei, die Sie eben erstellt haben.

Geben Sie an der Eingabeaufforderung msbuild helloworld.csproj -t:Build ein.

Damit wird das Buildziel der Helloworld-Projektdatei erstellt, da der C#-Compiler aufgerufen wird, um die Helloworld-Anwendung zu erstellen.
Testen Sie die Anwendung, indem Sie helloworld eingeben.

Die Meldung Hello, World! sollte angezeigt werden.

Hinweis

Weitere Details zum Build werden angezeigt, wenn Sie den Ausführlichkeitsgrad erhöhen. Um den Ausführlichkeitsgrad auf „Detailliert“ festzulegen, geben Sie diesen Befehl an der Eingabeaufforderung ein:

msbuild helloworld.csproj -t:Build -verbosity:detailed

Hinzufügen der Buildeigenschaften

Sie können der Projektdatei Buildeigenschaften hinzufügen, um den Build genauer steuern zu können. Fügen Sie jetzt die folgenden Eigenschaften hinzu:

Eine AssemblyName-Eigenschaft, mit der der Name der Anwendung angegeben wird
Eine OutputPath-Eigenschaft, mit der ein Ordner für die Anwendung angegeben wird

So fügen Sie Buildeigenschaften hinzu

Löschen Sie die vorhandene ausführbare Anwendung (später fügen Sie ein Clean-Ziel hinzu, um das Löschen alter Ausgabedateien zu verarbeiten).

Fügen Sie in der Projektdatei nach dem ersten PropertyGroup-Element das folgende Project-Element ein:

<PropertyGroup>
  <AssemblyName>MSBuildSample</AssemblyName>
  <OutputPath>Bin\</OutputPath>
</PropertyGroup>

Fügen Sie dem Build-Ziel direkt vor der Csc-Aufgabe die folgende Aufgabe hinzu:
```
<MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
```
Mit der MakeDir-Aufgabe wird ein Ordner erstellt, der nach der OutputPath-Eigenschaft benannt wird, sofern noch kein Ordner mit diesem Namen vorhanden ist.
Fügen Sie der OutputAssembly-Aufgabe das folgende Csc-Attribut hinzu:
```
<Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
```
Damit wird der C#-Compiler angewiesen, eine nach der AssemblyName-Eigenschaft benannte Assembly zu generieren und diese in den nach der OutputPath-Eigenschaft benannten Ordner einzufügen.
Speichern Sie die Änderungen.

Die Projektdatei sollte nun dem folgenden Code ähneln:

<Project>
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
</Project>

Hinweis

Es wird empfohlen, den umgekehrten Schrägstrich (\) als Pfadtrennzeichen am Ende des Ordnernamens bei der Angabe im OutputPath Element anzufügen und nicht im OutputAssembly Attribut Csc der Aufgabe. Daher eignet sich

<OutputPath>Bin\</OutputPath>

OutputAssembly="$(OutputPath)$(AssemblyName).exe" />

besser als

<OutputPath>Bin</OutputPath>

OutputAssembly="$(OutputPath)\$(AssemblyName).exe" />

Testen der Buildeigenschaften

Nun können Sie die Anwendung mithilfe der Projektdatei erstellen, in der Sie über Buildeigenschaften den Ausgabeordner und den Anwendungsnamen angegeben haben.

Geben Sie an der Eingabeaufforderung msbuild helloworld.csproj -t:Build ein.

Damit wird der Ordner \Bin erstellt und anschließend der C#-Compiler aufgerufen, um die Anwendung MSBuildSample zu erstellen und in den Ordner \Bin einzufügen.
Wenn Sie überprüfen möchten, ob der Ordner \Bin\ erstellt wurde und die Anwendung MSBuildSample enthält, geben Sie dir Bin ein.
Testen Sie die Anwendung, indem Sie Bin\MSBuildSample eingeben, um die ausführbare Datei auszuführen.

Die Meldung Hello, World! sollte angezeigt werden.

Hinzufügen von Buildzielen

Fügen Sie der Projektdatei anschließend wie folgt zwei weitere Ziele hinzu:

Ein Clean-Ziel, mit dem alte Dateien gelöscht werden.
Ein Rebuild-Ziel, das über das DependsOnTargets-Attribut die Ausführung der Clean-Aufgabe erzwingt, bevor die Build-Aufgabe ausgeführt wird.

Da Sie nun über mehrere Ziele verfügen, können Sie das Build-Ziel als Standardziel festlegen.

So fügen Sie Build-Ziele hinzu

Fügen Sie in der Projektdatei direkt nach dem Build-Ziel die folgenden beiden Ziele hinzu:
```
<Target Name="Clean" >
  <Delete Files="$(OutputPath)$(AssemblyName).exe" />
</Target>
<Target Name="Rebuild" DependsOnTargets="Clean;Build" />
```
Das Clean-Ziel ruft die Delete-Aufgabe auf, die Anwendung zu löschen. Das Rebuild-Ziel wird erst ausgeführt, nachdem das Clean-Ziel und das Build-Ziel ausgeführt wurden. Zwar weist das Rebuild-Ziel keine Aufgaben auf, doch führt es dazu, dass das Clean-Ziel vor dem Build-Ziel ausgeführt wird.
Fügen Sie dem ersten DefaultTargets-Element das folgende Project-Attribut hinzu:
```
<Project DefaultTargets="Build">
```
Damit wird das Build-Ziel als Standardziel festgelegt.

Die Projektdatei sollte nun dem folgenden Code ähneln:

<Project DefaultTargets="Build">
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Clean" >
    <Delete Files="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Rebuild" DependsOnTargets="Clean;Build" />
</Project>

Testen der Buildziele

Mit den neuen Build-Zielen können Sie die folgenden Funktionen der Projektdatei testen:

Erstellen des Standardbuilds
Festlegen des Anwendungsnamens an der Eingabeaufforderung
Löschen der Anwendung, bevor eine andere Anwendung erstellt wird
Löschen der Anwendung, ohne eine andere Anwendung zu erstellen

So testen Sie die Build-Ziele

Geben Sie an der Eingabeaufforderung msbuild helloworld.csproj -p:AssemblyName=Greetings ein.

Da Sie das Ziel nicht explizit mit dem Schalter -t festgelegt haben, führt MSBuild das Build-Standardziel aus. Der Schalter -p überschreibt die Eigenschaft AssemblyName und gibt dieser den neuen Wert Greetings. Dies führt zum Erstellen der neuen Anwendung Greetings.exe im Ordner \Bin\.
Wenn Sie überprüfen möchten, ob der Ordner \Bin\ die Anwendung MSBuildSample und die neue Anwendung Greetings enthält, geben Sie dir Bin ein.
Testen Sie die Greetings-Anwendung (z. B. durch Eingeben von Bin\Greetings unter Windows).

Die Meldung Hello, World! sollte angezeigt werden.
Löschen Sie die Anwendung MSBuildSample, indem Sie msbuild helloworld.csproj -t:clean eingeben.

Dadurch wird die Clean-Aufgabe ausgeführt, um die Anwendung mit dem AssemblyName-Standardeigenschaftswert MSBuildSample zu entfernen.
Löschen Sie die Anwendung Greetings, indem Sie msbuild helloworld.csproj -t:clean -p:AssemblyName=Greetings eingeben.

Dadurch wird die Clean-Aufgabe ausgeführt, um die Anwendung mit dem angegebenen AssemblyName-Eigenschaftswert Greetings zu entfernen.
Wenn Sie überprüfen möchten, ob der Ordner \Bin\ jetzt leer ist, geben Sie dir Bin ein.
Typ msbuild.

Zwar ist keine Projektdatei angegeben, doch erstellt MSBuild die Datei helloworld.csproj, da der aktuelle Ordner nur eine Projektdatei enthält. Auf diese Weise wird die Anwendung MSBuildSample im Ordner \Bin\ erstellt.

Wenn Sie überprüfen möchten, ob der Ordner \Bin\ die Anwendung MSBuildSample enthält, geben Sie dir Bin ein.

Inkrementelles Erstellen

Sie können MSBuild anweisen, ein Ziel nur zu erstellen, wenn die Quelldateien oder Zieldateien, von denen das Ziel abhängig ist, geändert wurden. MSBuild bestimmt anhand des Zeitstempels einer Datei, ob diese geändert wurde.

So nehmen Sie einen inkrementellen Build vor

Fügen Sie in der Projektdatei dem ersten Build-Ziel die folgenden Attribute hinzu:
```
Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"
```
Damit wird festgelegt, dass das Build-Ziel von den in der Compile-Elementgruppe angegebenen Eingabedateien abhängt und dass als Ausgabeziel die Anwendungsdatei verwendet wird.

Das resultierende Build-Ziel sollte dem folgenden Code ähneln:
```
<Target Name="Build" Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe">
  <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
  <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
</Target>
```
Testen Sie das Build-Ziel, indem Sie an der Eingabeaufforderung msbuild -v:d eingeben.

Vergessen Sie nicht, dass helloworld.csproj die Standardprojektdatei und „Build“ das Standardziel darstellt.

Der Schalter -v:d ist eine Abkürzung der zuvor verwendeten Anweisung -verbosity:detailed.

Wenn Sie die Ausgabe bereits erstellt haben, sollten die folgenden Zeilen angezeigt werden:

Das Ziel „Build“ wird übersprungen, da alle Ausgabedateien hinsichtlich der Eingabedateien aktuell sind.

MSBuild überspringt das Build-Ziel, da seit dem letzten Build der Anwendung keine der Quelldateien geändert wurde.

Beispiel für C#

Das folgende Beispiel enthält eine Projektdatei, durch die eine C#-Anwendung kompiliert und eine Meldung mit dem Namen der Ausgabedatei protokolliert wird.

Code

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldCS</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <CSFile Include = "*.cs"/>
    </ItemGroup>

    <Target Name="Compile">
        <!-- Run the C# compilation using input files of type CSFile -->
        <CSC
            Sources = "@(CSFile)"
            OutputAssembly = "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the CSC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </CSC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Beispiel für Visual Basic

Das folgende Beispiel enthält eine Projektdatei, durch die eine Visual Basic-Anwendung kompiliert und eine Meldung mit dem Namen der Ausgabedatei protokolliert wird.

Code

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldVB</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <VBFile Include = "consolehwvb1.vb"/>
    </ItemGroup>

    <Target Name = "Compile">
        <!-- Run the Visual Basic compilation using input files of type VBFile -->
        <VBC
            Sources = "@(VBFile)"
            OutputAssembly= "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the VBC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </VBC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Ausblick

Visual Studio kann einen großen Teil der in dieser exemplarischen Vorgehensweise gezeigten Aktionen automatisch übernehmen. Informationen zum Erstellen und Bearbeiten sowie zum Build und zu Tests von MSBuild-Projektdateien in Visual Studio finden Sie unter Exemplarische Vorgehensweise: Verwenden von MSBuild.

Exemplarische Vorgehensweise: Erstellen einer neuen MSBuild-Projektdatei

Erweitern des Pfads

Erstellen einer minimalen Anwendung

Erstellen einer minimalen MSBuild-Projektdatei

So erstellen Sie eine minimale MSBuild-Projektdatei

Erstellen der Anwendung

Hinzufügen der Buildeigenschaften

So fügen Sie Buildeigenschaften hinzu

Testen der Buildeigenschaften

Hinzufügen von Buildzielen

So fügen Sie Build-Ziele hinzu

Testen der Buildziele

So testen Sie die Build-Ziele

Inkrementelles Erstellen

So nehmen Sie einen inkrementellen Build vor

Beispiel für C#

Code

Beispiel für Visual Basic

Code

Ausblick

Feedback

Feedback

Zusätzliche Ressourcen

Exemplarische Vorgehensweise: Erstellen einer neuen MSBuild-Projektdatei

Erweitern des Pfads

Erstellen einer minimalen Anwendung

Erstellen einer minimalen MSBuild-Projektdatei

So erstellen Sie eine minimale MSBuild-Projektdatei

Erstellen der Anwendung

Hinzufügen der Buildeigenschaften

So fügen Sie Buildeigenschaften hinzu

Testen der Buildeigenschaften

Hinzufügen von Buildzielen

So fügen Sie Build-Ziele hinzu

Testen der Buildziele

So testen Sie die Build-Ziele

Inkrementelles Erstellen

So nehmen Sie einen inkrementellen Build vor

Beispiel für C#

Code

Beispiel für Visual Basic

Code

Ausblick

Zugehöriger Inhalt

Feedback

Feedback

Zusätzliche Ressourcen