Angeben von Buildereignissen (C#)

Verwenden Sie Buildereignisse, um Befehle festzulegen, die vor Beginn oder nach Beenden des Builds ausgeführt werden.

Angeben eines Buildereignisses

1. Klicken Sie im Projektmappen-Explorer auf das Projekt, für das Sie das Buildereignis angeben möchten.

2. Klicken Sie im Menü Projekt auf {Projektname}-Eigenschaften (oder drücken Sie im Projektmappen-Explorer auf ALT+EINGABETASTE).

3. Wählen Sie Build > Ereignisse aus.

   

4. Geben Sie im Abschnitt Präbuildereignis die Syntax des Buildereignisses an.

   Hinweis

   Präbuildereignisse werden nicht ausgeführt, wenn das Projekt auf dem neuesten Stand ist, und es wird kein Build gestartet.

5. Geben Sie im Abschnitt Postbuildereignis die Syntax des Buildereignisses an.

   Hinweis

   Fügen Sie allen Postbuildbefehlen, die BAT-Dateien ausführen, eine call-Anweisung hinzu. Beispielsweise call MyFile.bat oder call MyFile.bat call MyFile2.bat. Pfade können absolut oder relativ zum Projektordner sein.

6. Geben Sie im Abschnitt Wann das Postbuildereignis ausgeführt werden soll an, unter welchen Bedingungen das Postbuildereignis ausgeführt werden soll.

Erstellen der Buildereignisbefehle

Die Buildereignisbefehle können beliebige Befehle enthalten, die für eine Eingabeaufforderung oder eine BAT-Datei zulässig sind. Verfügbare Befehle sind in der Windows-Befehlsreferenz dokumentiert. Dem Namen der Batchdatei sollte ein call vorangestellt sein, um sicherzustellen, dass alle nachfolgenden Befehle ausgeführt werden. Die Batchdatei selbst wird aus dem Ausgabeordner ausgeführt, z. B. bin/Debug. Wenn Sie dieselbe Batchdatei für alle Konfigurationen benötigen, können Sie sie im selben Ordner wie die Projektdatei speichern und mit einem relativen Pfad darauf verweisen, z. B. mit call ../../prebuild.bat.

Sie können PowerShell-Skripts ausführen, indem Sie einen Befehl wie PowerShell MyPowerShellScript.ps1 eingeben. Der Pfad zum PowerShell-Skript kann absolut oder relativ zum Projektverzeichnis sein. Stellen Sie sicher, dass die Ausführungsrichtlinie für PowerShell-Skripts in Ihrem Betriebssystem entsprechend festgelegt ist, damit das Skript ausgeführt wird. Siehe Informationen zu Ausführungsrichtlinien.

Wenn Sie eine andere Shell wie Bash verwenden möchten, verwenden Sie üblicherweise die gleiche Befehlssyntax wie zum Starten eines Shellskripts über die Windows-Eingabeaufforderung. Die Verwendung von Drittanbietershells liegt außerhalb des Rahmens dieser Dokumentation, aber Websites wie Stack Overflow können hilfreich sein.

In der Projektdatei

Wenn Sie die vorherigen Schritte ausführen, ändert Visual Studio Ihre Projektdatei, indem das Ziel PreBuild oder PostBuild und der erforderliche MSBuild-Code hinzugefügt werden, um die von Ihnen angegebenen Schritte auszuführen. Sie können die Projektdatei öffnen und die Schritte anzeigen. Das Ändern der Schritte in der Projektdatei ist in Ordnung. Ihre Änderungen werden im Abschnitt Buildereignisse > der Projekteigenschaften angezeigt, nachdem Sie die Änderungen gespeichert haben.

<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
  <Exec Command="call prebuild.bat" />
</Target>

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="call postbuild.bat" />
</Target>

Das Element Exec bezieht sich auf die Aufgabe Exec von MSBuild. Informationen zu anderen Parametern, mit deren Hilfe Sie die Ausführung anpassen können, finden Sie unter Exec-Aufgabe. Sie können z. B. mit WorkingDirectory den Ordner festlegen, in dem die ausführbare Datei ausgeführt wird. Standardmäßig ist es das Verzeichnis, das die Projektdatei enthält.

<Exec Command="call prebuild.bat" WorkingDirectory="$(OutDir)">

Sie können MSBuild-Eigenschaften (Makros) verwenden, wie z. B. OutDir im vorherigen Beispiel. Dies wird weiter unten in diesem Artikel unter Makros erläutert.

Fehler und andere Ausgaben

Die Ausgabe Ihrer Buildereignisse wird in den Abschnitt Build des Ausgabefensters geschrieben. Um es zu öffnen, wählen Sie Ansicht>Andere Fenster, Ausgabefenster aus, oder drücken Sie STRG+ALT+O. Wählen Sie in der Dropdownliste Ausgabe anzeigen aus die Option Build aus.

Wenn Ihr Prä- oder Postbuildereignis nicht erfolgreich abgeschlossen wird, können Sie den Build abschließen, indem Sie Ihre Ereignisaktion mit einem Code, der nicht 0 (null) ist, beenden. Dies zeigt eine erfolgreiche Aktion an. Jeder andere Exitcode wird als Fehler betrachtet.

Wenn ihr Präbuildereignis fehlschlägt, wird möglicherweise ein Fehler wie dieser im Fenster Fehlerliste angezeigt:

MSB3073    The command "call c:\source\repos\prebuild.bat" exited with code 1.

Wenn im Fenster Fehlerliste nicht genügend Informationen vorhanden sind, können Sie versuchen, das Ausgabefenster zu verwenden, um die vollständige Buildausgabe einschließlich aller Ausgaben aus Batchdateien anzuzeigen.

Tipp

Das Fenster Fehlerliste ist auf nur eine Ausgabezeile beschränkt, die erste Zeile, die Sie für das Ereignis eingegeben haben. Wenn die Fensterausgabe der Fehlerliste für Sie wichtig ist, vermeiden Sie, mehr als eine Zeile in das Ereignis einzufügen. Erstellen Sie eine Batchdatei an der Windows-Eingabeaufforderung oder im Betriebssystem, und verwenden Sie call mybatchfile.bat dann einfach für das Ereignis. Fügen Sie die Befehle in die eigentliche Batchdatei ein.

Anleitungen zu den Befehlen, die Sie in Batchdateien verwenden können, finden Sie unter Windows-Befehle.

Makros

Allgemein verfügbare „Makros“ (eigentlich MSBuild-Eigenschaften) werden unter Allgemeine MSBuild-Eigenschaften aufgeführt. Für .NET SDK-Projekte (.NET Core oder .NET 5 und höher) werden zusätzliche Eigenschaften unter MSBuild-Eigenschaften für Microsoft .NET.Sdk aufgeführt.

In Ihren Skripts für Buildereignisse möchten Sie möglicherweise auf die Werte einiger Variablen auf Projektebene verweisen, z. B. auf den Namen des Projekts oder den Speicherort des Ausgabeordners. In früheren Versionen von Visual Studio wurden diese als Makros bezeichnet. Das Äquivalent zu Makros in aktuellen Versionen von Visual Studio sind MSBuild-Eigenschaften. MSBuild ist die Build-Engine, die Visual Studio verwendet, um Ihre Projektdatei zu verarbeiten, wenn ein Build ausgeführt wird. Ein Buildereignis in der IDE führt zu einem MSBuild-Ziel in der Projektdatei. Sie können jede MSBuild-Eigenschaft verwenden, die im Ziel in Ihrer Projektdatei verfügbar ist (z. B. $(OutDir) oder $(Configuration)). Die MSBuild-Eigenschaften, die Ihnen in diesen Ereignissen zur Verfügung stehen, hängen von den Dateien ab, die implizit oder explizit in eine Projektdatei importiert werden (z. B. .props- und .targets-Dateien), sowie von Eigenschaften, die in Ihrer Projektdatei festgelegt sind (z. B. PropertyGroup-Elemente). Achten Sie darauf, dass Sie die genaue Schreibweise jeder Eigenschaft verwenden. Es wird kein Fehler gemeldet, wenn Sie eine Eigenschaft falsch eingeben. Stattdessen wird eine nicht definierte Eigenschaft in eine leere Zeichenfolge ausgewertet.

Angenommen, Sie geben ein Ereignis vor dem Buildvorgang wie folgt an:

Dieses Ereignis vor dem Buildvorgang führt zu dem folgenden Eintrag, der in Ihrer Projektdatei als Target bezeichnet wird:

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="echo Configuration: $(Configuration)&#xD;&#xA;echo DevEnvDir: $(DevEnvDir)&#xD;&#xA;echo OutDir: $(OutDir)&#xD;&#xA;echo ProjectDir: $(ProjectDir)&#xD;&#xA;echo VisualStudioVersion: $(VisualStudioVersion)&#xD;&#xA;echo AssemblySearchPaths: $(AssemblySearchPaths)&#xD;&#xA;echo AssemblyName: $(AssemblyName)&#xD;&#xA;echo BaseIntermediateOutputPath: $(BaseIntermediateOutputPath)&#xD;&#xA;echo CscToolPath: $(CscToolPath)" />
  </Target>

Das Buildereignis wird als Ziel angezeigt, das den Exec-Task mit der Eingabe enthält, die Sie als Command angegeben haben. Zeilenvorschübe werden im XML codiert.

Wenn Sie das Projekt in diesem Beispiel erstellen, gibt das Ereignis vor dem Buildvorgang die Werte einiger Eigenschaften aus. In diesem Beispiel generiert $(CscToolPath) keine Ausgabe, da diese Eigenschaft nicht definiert ist. Es handelt sich um eine optionale Eigenschaft, die Sie in Ihrer Projektdatei definieren können, um den Pfad zu einer angepassten Instanz des C#-Compilers anzugeben (beispielsweise, wenn Sie eine andere Version von csc.exe oder einen experimentellen Compiler testen).

Die Ausgabe aus Ihren Buildereignissen wird in die Buildausgabe geschrieben, die Sie im Ausgabefenster finden. Wählen Sie in der Dropdownliste Ausgabe anzeigen aus die Option Build aus.

Build started...
1>------ Build started: Project: ConsoleApp4, Configuration: Debug Any CPU ------
1>You are using a preview version of .NET. See: https://aka.ms/dotnet-core-preview
1>Configuration: Debug
1>DevEnvDir: C:\Program Files\Microsoft Visual Studio\2022\Preview\Common7\IDE\
1>OutDir: bin\Debug\net6.0\
1>ProjectDir: C:\source\repos\ConsoleApp4\ConsoleApp4\
1>VisualStudioVersion: 17.0
1>ALToolsPath:
1>AssemblySearchPaths: {CandidateAssemblyFiles};{HintPathFromItem};{TargetFrameworkDirectory};{RawFileName}
1>AssemblyName: ConsoleApp4
1>BaseIntermediateOutputPath: obj\
1>CscToolsPath:
1>Skipping analyzers to speed up the build. You can execute 'Build' or 'Rebuild' command to run analyzers.
1>ConsoleApp4 -> C:\source\repos\ConsoleApp4\ConsoleApp4\bin\Debug\net6.0\ConsoleApp4.dll

Hinweis

Einige Szenarien erfordern möglicherweise komplexere Buildaktionen, als mit den Buildereignissen möglich sind. In vielen gängigen Szenarien der Codegenerierung müssen Sie z. B. Bereinigungs- und Neuerstellungsvorgänge behandeln, und Sie möchten möglicherweise den inkrementellen Build für Codegenerierungsschritte aktivieren, damit der Schritt nur ausgeführt wird, wenn die Ausgabe in Bezug auf die Eingaben veraltet ist. MSBuild ist für die intelligente Verarbeitung all dieser Szenarien konzipiert. Erwägen Sie die Erstellung eines benutzerdefinierten Ziels, das AfterTargets oder BeforeTargets zur Ausführung während eines bestimmten Punkts im Buildprozess festlegt. Erwägen Sie zudem für eine weitere Steuerung in erweiterten Szenarien die Erstellung einer benutzerdefinierten Aufgabe, oder prüfen Sie die verschiedenen Möglichkeiten, wie Sie Ihren Build anpassen können.

Beispiel

1. Erstellen Sie im Projektordner eine Batchdatei namens postbuild.bat mit dem folgenden Inhalt:

   echo Copying output file %1 to %1.copy
   copy %1 %1.copy
   

   Denken Sie daran, dass sich %1 in einer Batchdatei auf das erste übergebene Argument bezieht.

2. Rufen Sie die Batchdatei im Abschnitt Postbuildereignis der Projekteigenschaften auf, und übergeben Sie ein Argument mithilfe der MSBuild-Eigenschaft $(TargetPath).

   call postbuild.bat $(TargetPath)
   

3. Erstellen Sie Ihr Projekt, und überprüfen Sie den Ausgabeordner. Die kopierte Datei sollte neben der erstellten Assembly angezeigt werden. Im Ausgabefenster sollte im Abschnitt Build die Batchdateiausgabe angezeigt werden:

   1>Output file is C:\source\repos\ConsoleApp-BuildEvents\ConsoleApp-BuildEvents\bin\Debug\net6.0\ConsoleApp-BuildEvents.dll
   1>        1 file(s) copied.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   ========== Build started at 12:00 PM and took 00.723 seconds ==========
   

Zugehöriger Inhalt

• Seite „Buildereignisse“, Projekt-Designer (C#)
• Pre-build Event/Post-build Event command line dialog box (Dialogfelder „Befehlszeile für Präbuildereignis“ und „Befehlszeile für Postbuildereignis“)
• Vorgehensweise: Angeben von Buildereignissen (Visual Basic)
• Kompilieren und Erstellen