Freigeben über


Tutorial: Verwenden von MSBuild

MSBuild ist die Buildplattform für Microsoft und Visual Studio. In diesem Tutorial machen Sie sich mit den Bausteinen von MSBuild vertraut. Zudem wird erläutert, wie Sie MSBuild-Projekte erstellen, bearbeiten und debuggen. Sie erhalten Informationen zu folgenden Themen:

  • Erstellen und Bearbeiten einer Projektdatei.

  • Verwenden von Buildeigenschaften.

  • Verwenden von Buildelementen

Sie können MSBuild in Visual Studio oder im Befehlsfenster ausführen. In diesem Tutorial erstellen Sie mithilfe von Visual Studio eine MSBuild-Projektdatei. Sie bearbeiten die Projektdatei in Visual Studio, und im Befehlsfenster erstellen Sie das Projekt und untersuchen die Ergebnisse.

Installieren von MSBuild

Wenn Sie über Visual Studio verfügen, ist MSBuild bereits installiert. Bei Visual Studio 2019 und höher erfolgt die Installation im Installationsordner von Visual Studio. Bei einer typischen Standardinstallation unter Windows 10 befindet sich MSBuild.exe im Installationsordner MSBuild\Current\Bin.

Stellen Sie im Installationsprogramm sicher, dass die MSBuild-Tools für die verwendeten Arbeitsauslastungen ausgewählt sind, und klicken Sie auf Installieren.

Installing MSBuild

Um MSBuild auf einem System ohne Visual Studio zu installieren, wechseln Sie zu Buildtools für Visual Studio 2019, oder installieren Sie das .NET SDK.

Wenn Sie über Visual Studio verfügen, ist MSBuild bereits installiert. Bei Visual Studio 2022 erfolgt die Installation im Installationsordner von Visual Studio. Bei einer typischen Standardinstallation unter Windows 10 befindet sich MSBuild.exe im Installationsordner MSBuild\Current\Bin.

Navigieren Sie im Visual Studio-Installationsprogramm zu Einzelne Komponenten und dann zum Kontrollkästchen für MSBuild. Es wird automatisch aktiviert, wenn Sie eine der anderen zu installierenden Workloads auswählen.

Um MSBuild auf einem System ohne Visual Studio zu installieren, wechseln Sie zum Abschnitt mit den Buildtools für Visual Studio 2022 auf der Downloadseite. Eine weitere Möglichkeit zum Abrufen von MSBuild ist die Installation des .NET SDK.

Erstellen eines MSBuild-Projekts

Das Visual Studio-Projektsystem beruht auf MSBuild. Die Erstellung einer neuen Projektdatei in Visual Studio ist ganz einfach. In diesem Abschnitt erstellen Sie eine C#-Projektdatei. Stattdessen können Sie auch eine Visual Basic-Projektdatei erstellen. Im Kontext dieses Tutorials ist der Unterschied zwischen den zwei Projektdateien marginal.

So erstellen Sie eine neue Projektdatei

  1. Öffnen Sie Visual Studio, und erstellen Sie ein Projekt:

    Geben Sie im Suchfeld winforms ein, und wählen Sie dann Neue Windows Forms-App (.NET Framework) erstellen aus. Wählen Sie im angezeigten Dialogfeld Erstellen aus.

    Geben Sie im Feld Projektname die Zeichenfolge BuildApp ein. Geben Sie einen Speicherort für die Lösung ein, z.B. D:\.

  2. Klicken Sie auf OK oder Erstellen, um die Projektdatei zu erstellen.

Überprüfen der Projektdatei

Im vorherigen Abschnitt haben Sie mit Visual Studio eine C#-Projektdatei erstellt. Die Projektdatei wird im Projektmappen-Explorer durch den Projektknoten „BuildApp“ dargestellt. Sie können die Projektdatei im Visual Studio Code-Editor untersuchen.

So überprüfen Sie die Projektdatei

  1. Klicken Sie im Projektmappen-Explorer auf den Projektknoten BuildApp.

  2. Im Eigenschaftenbrowser wird als Projektdatei-Eigenschaft BuildApp.csproj angezeigt. Alle Projektdateien werden mit dem Suffix PROJ benannt. Wenn Sie ein Visual Basic-Projekt erstellt hätten, wäre der Projektdateiname BuildApp.vbproj.

  3. Klicken Sie erneut mit der rechten Maustaste auf den Projektknoten, klicken Sie dann auf BuildApp.csproj bearbeiten.

    Die Projektdatei wird im Code-Editor angezeigt.

Hinweis

Für einige Projekttypen, z. B. für C++-Projekte, müssen Sie das Projekt entladen, indem Sie mit der rechten Maustaste auf die Projektdatei klicken und Projekt entladen auswählen, bevor Sie die Projektdatei öffnen und bearbeiten können.

Ziele und Aufgaben

Projektdateien sind Dateien im XML-Format und dem Stammknoten Project.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0"  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

Die meisten .NET-Projekte umfassen ein Sdk-Attribut. Diese Projekte werden als SDK-ähnliche Projekte bezeichnet.

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

Es gibt zahlreiche unterschiedliche .NET SDKs für spezielle Zwecke. Diese werden unter .NET SDKs für Projekte beschrieben.

Das Erstellen einer Anwendung wird mit dem Target-Element und dem Task-Element ausgeführt.

  • Eine Aufgabe bildet die kleinste Arbeitseinheit, d. h. das „Atom“ eines Builds. Aufgaben sind unabhängige ausführbare Komponenten, die über Eingaben und Ausgaben verfügen können. Derzeit wird in der Projektdatei nicht auf Aufgaben verwiesen, und solche wurden nicht definiert. In den folgenden Abschnitten fügen Sie der Projektdatei Aufgaben hinzu. Weitere Informationen finden Sie unter MSBuild-Aufgaben.

  • Als Ziel wird eine benannte Sequenz von Aufgaben bezeichnet. Dabei kann es sich um eine benannte Tasksequenz handeln, aber im Wesentlichen ist es ein Element, das kompiliert oder fertiggestellt werden muss. Sie sollten es also zielorientiert definieren. Weitere Informationen finden Sie unter Ziele.

Das Standardziel ist nicht in der Projektdatei definiert. Stattdessen wird es in importierten Projekten angegeben. Das Import-Element gibt importierte Projekte an. Beispielsweise wird in einem C#-Projekt das Standardziel aus der Datei Microsoft.CSharp.targets importiert.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Importierte Dateien werden letztlich dort in die Projektdatei eingefügt, wo auf sie verwiesen wird.

Bei Projekten im SDK-Format wird dieses Importelement nicht angezeigt, da das SDK-Attribut bewirkt, dass diese Datei implizit importiert wird.

MSBuild verfolgt die Ziele eines Builds nach und garantiert, dass jedes Ziel nicht mehr als einmal erstellt wird.

Hinzufügen eines Ziels und einer Aufgabe

Fügen Sie der Projektdatei ein Ziel hinzu. Fügen Sie dem Ziel eine Aufgabe hinzu, mit der eine Meldung ausgegeben wird.

So fügen Sie ein Ziel und eine Aufgabe hinzu

  1. Fügen Sie diese Zeilen in der Projektdatei direkt nach der Importanweisung oder dem Element zum Öffnen des Projekts hinzu.

    <Target Name="HelloWorld">
    </Target>
    

    Mit diesem Code wird ein Ziel namens „HelloWorld“ erstellt. Beachten Sie, dass beim Bearbeiten der Projektdatei IntelliSense unterstützt wird.

  2. Fügen Sie dem Ziel HelloWorld Zeilen hinzu, sodass der daraufhin angezeigte Abschnitt wie folgt aussieht:

    <Target Name="HelloWorld">
      <Message Text="Hello"></Message>  <Message Text="World"></Message>
    </Target>
    
  3. Speichern Sie die Projektdatei.

Message ist eine der vielen Aufgaben, die im Lieferumfang von MSBuild enthalten sind. Eine vollständige Liste der verfügbaren Aufgaben sowie Nutzungsinformationen finden Sie unter Aufgabenreferenz.

Die Message-Aufgabe akzeptiert den Zeichenfolgenwert des Text-Attributs als Eingabe und zeigt diesen auf dem Ausgabegerät an (oder schreibt ihn ggf. in ein Protokoll). Das HelloWorld-Ziel führt die Message-Aufgabe zweimal aus: Zuerst wird „Hello“ angezeigt, dann „World“.

Erstellen des Ziels

Wenn Sie versuchen, dieses Projekt über Visual Studio zu kompilieren, wird das definierte Ziel nicht erstellt. Das liegt daran, dass Visual Studio das Standardziel auswählt, bei dem es sich weiterhin um das Ziel in der importierten Datei vom Typ .targets handelt.

Führen Sie MSBuild über die Developer-Eingabeaufforderung für Visual Studio aus, um das zuvor definierte Ziel „HelloWorld“ zu erstellen. Verwenden Sie den Befehlszeilenparameter -target oder -t, um das Ziel auszuwählen.

Hinweis

In den folgenden Abschnitten wird die Developer-Eingabeaufforderung als Befehlsfenster bezeichnet.

So erstellen Sie das Ziel:

  1. Öffnen Sie das Befehlsfenster.

    Geben Sie den Namen des Tools im Suchfeld auf der Taskleiste ein, z.B. dev oder developer command prompt. Dadurch wird eine Liste der installierten Apps angezeigt, die Ihrem Suchmuster entsprechen.

    Wenn Sie die Datei LaunchDevCmd.bat manuell suchen müssen, finden Sie sie im Ordner {Visual Studio-Installationsordner}\Common7\Tools.

  2. Navigieren Sie im Befehlsfenster zum Ordner mit der Projektdatei, in diesem Fall D:\BuildApp\BuildApp.

  3. Führen Sie MSBuild mit dem Befehlsparameter -t:HelloWorld aus. Mit diesem Befehl wird das Ziel „HelloWorld“ ausgewählt und erstellt:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Untersuchen Sie die Ausgabe im Befehlsfenster. Die beiden Zeilen "Hello" und "World" sollten angezeigt werden:

    Hello
    World
    

Hinweis

Wenn stattdessen The target "HelloWorld" does not exist in the project angezeigt wird, haben Sie wahrscheinlich vergessen, die Projektdatei im Code-Editor zu speichern. Speichern Sie die Datei, und versuchen Sie es erneut.

Durch Wechsel zwischen Code-Editor und dem Befehlsfenster können Sie die Projektdatei ändern und die Ergebnisse schnell anzeigen.

Buildeigenschaften

Buildeigenschaften sind Name-Wert-Paare, anhand derer der Build ausgeführt wird. Am Anfang der Projektdatei sind bereits mehrere Buildeigenschaften definiert:

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Alle Eigenschaften sind untergeordnete Elemente von PropertyGroup-Elementen. Der Name der Eigenschaft entspricht dem Namen des untergeordneten Elements, und der Wert der Eigenschaft entspricht dem Textelement des untergeordneten Elements. Ein auf ein Objekt angewendeter

<TargetFrameworkVersion>v4.5</TargetFrameworkVersion>

definiert die Eigenschaft „TargetFrameworkVersion“ und weist dieser den Zeichenfolgenwert „v4.5“ zu.

Buildeigenschaften können jederzeit neu definiert werden. If

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

später in der Projektdatei oder in einer später in die Projektdatei importierten Datei angegeben ist, nimmt TargetFrameworkVersion den neuen Wert „v3.5“ an.

Untersuchen eines Eigenschaftswerts

Den Wert einer Eigenschaft rufen Sie mit der folgenden Syntax ab, wobei PropertyName den Namen der Eigenschaft darstellt:

$(PropertyName)

Verwenden Sie die folgende Syntax, um einige Eigenschaften in der Projektdatei zu untersuchen.

So untersuchen Sie einen Eigenschaftswert

  1. Ersetzen Sie im Code-Editor das Ziel HelloWorld durch den folgenden Code:

    <Target Name="HelloWorld">
      <Message Text="Configuration is $(Configuration)" />
      <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
    </Target>
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgenden beiden Zeilen sollten angezeigt werden (Ihre Ausgabe weicht möglicherweise davon ab):

    Configuration is Debug
    MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
    
    Configuration is Debug
    MSBuildToolsPath is C:\Program Files (x86)\Microsoft Visual Studio\2019\MSBuild\16.0\Bin
    

Bedingte Eigenschaften

Viele Eigenschaften, z. B. Configuration, werden bedingt definiert, das heißt, dass im Eigenschaftenelement das Condition-Attribut angezeigt wird. Bedingte Eigenschaften werden nur definiert oder erneut definiert, wenn die Bedingung „true“ ergibt. Nicht definierten Eigenschaften wird der Standardwert (eine leere Zeichenfolge) zugewiesen. Ein auf ein Objekt angewendeter

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

bedeutet: „Wenn die Configuration-Eigenschaft noch nicht definiert wurde, definieren Sie diese, und weisen Sie ihr den Wert 'Debug' zu.“

Fast alle MSBuild-Elemente können ein Condition-Attribut besitzen. Die Verwendung des Condition-Attributs wird unter Bedingungen näher besprochen.

Reservierte Eigenschaften

Einige Eigenschaftennamen werden von MSBuild reserviert, um Informationen zur Projektdatei und zu den Binärdateien von MSBuild zu speichern. Ein Beispiel für eine reservierte Eigenschaft ist "MSBuildToolsPath". Auf reservierte Eigenschaften wird wie auf jede andere Eigenschaft mit der $-Notation verwiesen. Weitere Informationen finden Sie unter Vorgehensweise: Verweisen auf den Namen oder Speicherort der Projektdatei und Reservierte und bekannte Eigenschaften für MSBuild.

Umgebungsvariablen

Auf Umgebungsvariablen in Projektdateien kann auf die gleiche Weise verwiesen werden wie auf Buildeigenschaften. Um die PATH-Umgebungsvariable in der Projektdatei zu verwenden, verwenden Sie beispielsweise $(Path). Wenn das Projekt eine Eigenschaftendefinition enthält, die denselben Namen wie eine Umgebungsvariable hat, wird der Wert der Umgebungsvariablen von der Eigenschaft im Projekt überschrieben. Weitere Informationen finden Sie unter Vorgehensweise: Verwenden von Umgebungsvariablen in einem Build.

Festlegen von Eigenschaften in der Befehlszeile

Eigenschaften können an der Befehlszeile mit dem Befehlszeilenschalter „-property“ oder „-p“ definiert werden. Die in der Projektdatei und in Umgebungsvariablen festgelegten Eigenschaftswerte werden durch die Eigenschaftswerte überschrieben, die von der Befehlszeile empfangen werden.

So legen Sie einen Eigenschaftswert über die Befehlszeile fest:

  1. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release
    
  2. Prüfen Sie die Ausgabe. Die folgende Zeile sollte angezeigt werden:

    Configuration is Release.
    

MSBuild erstellt die Configuration-Eigenschaft und weist dieser den Wert „Release“ zu.

Sonderzeichen

Bestimmte Zeichen haben in MSBuild-Projektdateien eine besondere Bedeutung. Beispiele für solche Zeichen sind Semikolons (;) und Sternchen (*). Um diese Sonderzeichen als Literale in einer Projektdatei zu verwenden, müssen sie mit der Syntax %<xx> angegeben werden, wobei <xx> den ASCII-Hexadezimalwert des Zeichens darstellt.

Ändern Sie die Message-Aufgabe, um den Wert der Configuration-Eigenschaft mit Sonderzeichen anzuzeigen, um sie besser lesbar zu machen.

So verwenden Sie Sonderzeichen im Message-Task:

  1. Ersetzen Sie im Code-Editor beide Message-Aufgaben durch folgende Zeile:

    <Message Text="%24(Configuration) is %22$(Configuration)%22" />
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgende Zeile sollte angezeigt werden:

    $(Configuration) is "Debug"
    

Weitere Informationen finden Sie unter MSBuild-Sonderzeichen.

Buildelemente

Als Element wird eine Information, in der Regel ein Dateiname, bezeichnet, die als Eingabe für das Buildsystem verwendet wird. Eine Auflistung von Elementen, die Quelldateien darstellen, kann beispielsweise an die Aufgabe Compile übergeben werden, um sie zu einer Assembly zu kompilieren.

Alle Elemente sind untergeordnete Elemente von ItemGroup-Elementen. Der Elementname entspricht dem Namen des untergeordneten Elements, und der Elementwert entspricht dem Wert des Include-Attributs für das untergeordnete Element. Die Werte von Elementen mit gleichem Namen werden in Elementtypen dieses Namens erfasst. Ein auf ein Objekt angewendeter

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

definiert eine Elementgruppe mit zwei Elementen. Der Elementtyp „Compile“ verfügt über zwei Werte: Program.cs und Properties\AssemblyInfo.cs.

Mit dem folgenden Code wird der gleiche Elementtyp erstellt, indem die beiden durch ein Semikolon getrennten Dateien in einem Include-Attribut deklariert werden.

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

Weitere Informationen finden Sie unter Elemente.

Hinweis

Dateipfade sind relativ zum Ordner, der die MSBuild-Projektdatei enthält, auch wenn es sich bei der Projektdatei um eine importierte Projektdatei handelt. Es gibt einige Ausnahmen, z. B. bei Verwendung der Elemente Import und UsingTask.

Untersuchen der Elementtypwerte

Zum Abrufen der Werte eines Elementtyps verwenden Sie die folgende Syntax, wobei ItemType für den Namen des Elementtyps steht:

@(ItemType)

Verwenden Sie diese Syntax, um den Elementtyp Compile in der Projektdatei zu untersuchen.

So untersuchen Sie Elementtypwerte:

  1. Ersetzen Sie im Code-Editor die Aufgabe für das Ziel HelloWorld durch den folgenden Code:

    <Target Name="HelloWorld">
      <Message Text="Compile item type contains @(Compile)" />
    </Target>
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgende lange Zeile sollte angezeigt werden:

    Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
    

Die Werte eines Elementtyps werden standardmäßig durch Semikolons getrennt.

Wenn Sie das Trennzeichen für einen Elementtyp ändern möchten, verwenden Sie die folgende Syntax, wobei ItemType den Elementtyp und Separator eine Zeichenfolge aus einem oder mehreren Trennzeichen darstellt:

@(ItemType, Separator)

Ändern Sie die Message-Aufgabe, um Compile-Elemente mithilfe von Wagenrückläufen und Zeilenvorschüben (%0A%0D) auf jeweils eigenen Zeilen anzuzeigen.

So zeigen Sie Elementtypwerte auf jeweils eigenen Zeilen an

  1. Ersetzen Sie die Message-Aufgabe im Code-Editor durch diese Zeile:

    <Message Text="Compile item type contains @(Compile, '%0A%0D')" />
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgenden Zeilen sollten angezeigt werden:

    Compile item type contains Form1.cs
    Form1.Designer.cs
    Program.cs
    Properties\AssemblyInfo.cs
    Properties\Resources.Designer.cs
    Properties\Settings.Designer.cs
    

Include, Exclude und Platzhalter

Sie können mit dem Include-Attribut die Platzhalter "*", "**" und "?" verwenden, um einem Elementtyp Elemente hinzuzufügen. Ein auf ein Objekt angewendeter

<Photos Include="images\*.jpeg" />

fügt alle Dateien mit der Dateierweiterung JPEG im Ordner images dem Photos-Elementtyp hinzu, während

<Photos Include="images\**\*.jpeg" />

alle Dateien mit der Dateierweiterung JPEG im Ordner images und allen Unterordnern dem Photos-Elementtyp hinzufügt. Weitere Beispiele finden Sie unter Vorgehensweise: Auswählen von Dateien für den Buildvorgang.

Beachten Sie, dass deklarierte Elemente sofort dem jeweiligen Elementtyp hinzugefügt werden. Ein auf ein Objekt angewendeter

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

erstellt den Elementtyp „Photo“ mit allen Dateien im Ordner images, die die Dateierweiterung .jpeg oder .gif aufweisen. Diese Zeilen sind mit der nachfolgenden Zeile identisch:

<Photos Include="images\*.jpeg;images\*.gif" />

Mit dem Exclude-Attribut können Sie ein Element aus einem Elementtyp ausschließen. Ein auf ein Objekt angewendeter

<Compile Include="*.cs" Exclude="*Designer*">

fügt dem Compile-Elementtyp alle Dateien mit der Dateierweiterung CS hinzu, mit Ausnahme von Dateien, deren Namen die Zeichenfolge Designer enthalten. Weitere Beispiele finden Sie unter Vorgehensweise: Ausschließen von Dateien aus dem Buildvorgang.

Das Exclude-Attribut wirkt sich nur auf die Elemente aus, die über das Include-Attribut in dem Elementelement hinzugefügt wurden, das beide enthält. Ein auf ein Objekt angewendeter

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

In diesem Beispiel wird die Datei Form1.cs, die im vorherigen Elementelement hinzugefügt wurde, nicht ausgeschlossen.

So schließen Sie Elemente ein oder aus

  1. Ersetzen Sie die Message-Aufgabe im Code-Editor durch diese Zeile:

    <Message Text="XFiles item type contains @(XFiles)" />
    
  2. Fügen Sie diese Elementgruppe genau nach dem Import-Element hinzu:

    <ItemGroup>
       <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
    </ItemGroup>
    
  3. Speichern Sie die Projektdatei.

  4. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  5. Prüfen Sie die Ausgabe. Die folgende Zeile sollte angezeigt werden:

    XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx
    

Elementmetadaten

Zusätzlich zu den Informationen, die von den Attributen Include und Exclude erfasst werden, können Elemente Metadaten enthalten. Aufgaben, die neben dem Elementwert weitere Informationen zu den Elementen erfordern, können diese Metadaten verwenden.

Elementmetadaten werden in der Projektdatei deklariert, indem ein Element mit dem Namen der Metadaten als untergeordnetes Element des Elements erstellt wird. Ein Element kann über 0 (null) oder mehr Metadatenwerte verfügen. Das folgende CSFile-Element weist z. B. Culture-Metadaten mit dem Wert "Fr" auf:

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Den Metadatenwert eines Elementtyps rufen Sie mit der folgenden Syntax ab, wobei ItemType für den Namen des Elementtyps steht und „MetaDataName“ den Namen der Metadaten angibt:

%(ItemType.MetaDataName)

So untersuchen Sie Elementmetadaten:

  1. Ersetzen Sie die Message-Aufgabe im Code-Editor durch diese Zeile:

    <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgenden Zeilen sollten angezeigt werden:

    Compile.DependentUpon:
    Compile.DependentUpon: Form1.cs
    Compile.DependentUpon: Resources.resx
    Compile.DependentUpon: Settings.settings
    

Der Ausdruck "Compile.DependentUpon" wird mehrmals angezeigt. In dieser Syntax führt die Verwendung von Metadaten in einem Ziel zur „Batchverarbeitung“. Batchverarbeitung bedeutet, dass die Aufgaben innerhalb des Ziels für jeden eindeutigen Metadatenwert einmal ausgeführt werden. Batchverarbeitung ist die MSBuild-Skriptentsprechung des häufig verwendeten Programmierkonstrukts „ForEach-Schleife“. Weitere Informationen finden Sie unter MSBuild Batching (Batchverarbeitung).

Bekannte Metadaten

Wenn einer Elementliste ein Element hinzugefügt wird, werden diesem Element stets bekannte Metadaten zugewiesen. Beispielsweise gibt %(Filename) den Dateinamen eines beliebigen Elements zurück. Eine vollständige Liste bekannter Metadaten finden Sie unter Bekannte Elementmetadaten.

So untersuchen Sie bekannte Metadaten:

  1. Ersetzen Sie die Message-Aufgabe im Code-Editor durch diese Zeile:

    <Message Text="Compile Filename: %(Compile.Filename)" />
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgenden Zeilen sollten angezeigt werden:

    Compile Filename: Form1
    Compile Filename: Form1.Designer
    Compile Filename: Program
    Compile Filename: AssemblyInfo
    Compile Filename: Resources.Designer
    Compile Filename: Settings.Designer
    

Der Vergleich der beiden obigen Beispiele zeigt, dass zwar nicht jedes Element im Compile-Elementtyp DependentUpon-Metadaten aufweist, doch alle Elemente die bekannten Filename-Metadaten aufweisen.

Transformationen von Metadaten

Elementlisten können in neue Elementlisten umgewandelt werden. Eine Elementliste transformieren Sie mit der folgenden Syntax, wobei <ItemType> den Namen des Elementtyps darstellt und <MetadataName> den Namen der Metadaten:

@(ItemType -> '%(MetadataName)')

Beispielsweise kann eine Elementliste von Quelldateien über einen Ausdruck, z. B. @(SourceFiles -> '%(Filename).obj'), in eine Auflistung von Objektdateien transformiert werden. Weitere Informationen finden Sie unter Transformationen.

So transformieren Sie Elemente mit Metadaten:

  1. Ersetzen Sie die Message-Aufgabe im Code-Editor durch diese Zeile:

    <Message Text="Backup files: @(Compile->'%(filename).bak')" />
    
  2. Speichern Sie die Projektdatei.

  3. Geben Sie im Befehlsfenster die folgende Zeile ein, und führen Sie diese aus:

    msbuild buildapp.csproj -t:HelloWorld
    
  4. Prüfen Sie die Ausgabe. Die folgende Zeile sollte angezeigt werden:

    Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
    

Beachten Sie, dass die in dieser Syntax ausgedrückten Metadaten keine Batchverarbeitung verursachen.

Nächste Schritte

Eine Schritt-für-Schritt-Anleitung zum Erstellen einer einfachen Projektdatei unter Windows finden Sie unter Erstellen einer neuen MSBuild-Projektdatei.

Wenn Sie hauptsächlich mit dem .NET SDK arbeiten, lesen Sie unter MSBuild-Referenz für .NET SDK-Projekte weiter.