C#-Compileroptionen, die die Compilerausgabe steuern

  • Artikel

Die folgenden Optionen steuern die Generierung von Compilerausgaben.

MSBuild csc.exe Beschreibung
DocumentationFile -doc: Generiert eine XML-DOC-Datei aus ///-Kommentaren.
OutputAssembly -out: Gibt die Ausgabeassemblydatei an.
PlatformTarget -platform: Gibt die Zielplattform-CPU an.
ProduceReferenceAssembly -refout: Generiert eine Referenzassembly.
TargetType -target: Gibt den Typ der Ausgabeassembly an.

DocumentationFile

Mit der Option DocumentationFile können Sie Dokumentationskommentare in eine XML-Datei einfügen. Weitere Informationen zum Dokumentieren Ihres Codes finden Sie unter Empfohlene Tags für Dokumentationskommentare. Der Wert gibt den Pfad zur XML-Ausgabedatei an. Die XML-Datei enthält die Kommentare in den Quellcodedateien der Kompilierung.

<DocumentationFile>path/to/file.xml</DocumentationFile>

Die Quellcodedatei, die die Main-Anweisungen oder die Anweisungen auf oberster Ebene enthält, wird zuerst in die XML-Datei ausgegeben. Sie werden die generierte XML-Datei häufig mit IntelliSense verwenden wollen. Der Name der XML-Datei muss mit dem Assemblynamen identisch sein. Die XML-Datei muss sich im selben Verzeichnis wie die Assembly befinden. Wenn in einem Visual Studio-Projekt auf die Assembly verwiesen wird, wird auch die XML-Datei gefunden. Weitere Informationen zum Generieren von Codekommentaren finden Sie unter Bereitstellen von Codekommentaren. Wenn Sie nicht mit <TargetType:Module> kompilieren, enthält file die Tags <assembly> und </assembly>, die den Namen der Datei mit dem Assemblymanifest für die Ausgabedatei angeben. Beispiele dazu finden Sie unter Verwenden der XML-Dokumentationsfeatures.

Hinweis

Die Option DocumentationFile gilt für alle Dateien im Projekt. Verwenden Sie zum Deaktivieren von Warnungen im Zusammenhang mit Dokumentationskommentare für eine bestimmte Datei oder einen Codeabschnitt #pragma warning.

Diese Option kann in jedem Projekt im .NET SDK-Stil verwendet werden. Weitere Informationen finden Sie unter der DocumentationFile-Eigenschaft.

OutputAssembly

Die Option OutputAssembly gibt den Namen der Ausgabedatei an. Der Ausgabepfad gibt den Ordner an, in dem die Compilerausgabe platziert wird.

<OutputAssembly>folder</OutputAssembly>

Geben Sie den vollständigen Namen und die Erweiterung der Datei an, die Sie erstellen möchten. Wenn Sie den Namen der Ausgabedatei nicht angeben, verwendet MSBuild den Namen des Projekts, um den Namen der Ausgabeassembly anzugeben. Projekte im alten Stil verwenden die folgenden Regeln:

  • Eine EXE-Datei übernimmt den Namen aus der Quellcodedatei, die die Main-Methode oder Anweisungen auf oberster Ebene enthält.
  • Eine DLL- oder NETMODULE-Datei übernimmt den Namen aus der ersten Quellcodedatei.

Alle Module, die als Teil einer Kompilierung erstellt werden, werden Dateien, die jeder Assembly zugeordnet sind, die auch bei der Kompilierung erstellt werden. Verwenden Sie ildasm.exe, um das Assemblymanifest mit den zugehörigen Dateien anzuzeigen.

Die Compileroption OutputAssembly ist erforderlich, damit eine EXE-Datei das Ziel einer Friend-Assembly sein kann.

PlatformTarget

Gibt an, welche Version der CLR die Assembly ausführen kann.

<PlatformTarget>anycpu</PlatformTarget>
  • anycpu (Standard) kompiliert die Assembly für die Ausführung auf einer beliebigen Plattform. Ihre Anwendung wird nach Möglichkeit als 64-Bit-Prozess ausgeführt und wechselt zurück zu 32-Bit, wenn nur dieser Modus verfügbar ist.
  • anycpu32bitpreferred kompiliert die Assembly für die Ausführung auf einer beliebigen Plattform. Die Anwendung wird auf Systemen, die sowohl 64-Bit- als auch 32-Bit-Anwendungen unterstützen, im 32-Bit-Modus ausgeführt. Sie können diese Option nur für Projekte angeben, die auf .NET Framework 4.5 oder höher ausgerichtet sind.
  • ARM kompiliert Ihre Assembly für die Ausführung auf einem Computer mit einem ARM-Prozessor (Advanced RISC-Computer).
  • ARM64 kompiliert Ihre Assembly für die Ausführung durch die 64-Bit-CLR auf einem Computer mit einem Advanced RISC Machine-Prozessor (ARM), der den A64-Anweisungssatz unterstützt.
  • x64 kompiliert Ihre Assembly für die 64-Bit-CLR auf einem Computer, der den AMD64- oder EM64T-Befehlssatz unterstützt.
  • x86 kompiliert die Assembly für die 32-Bit-CLR (Common Language Runtime), die mit x86 kompatibel ist.
  • Itanium kompiliert Ihre Assembly für die Ausführung durch die 64-Bit-CLR auf einem Computer mit einem Itanium-Prozessor.

Auf einem 64-Bit-Windows-Betriebssystem:

  • Mit x86 kompilierte Assemblys werden in der 32-Bit-CLR unter WOW64 ausgeführt.
  • Eine mit anycpu kompilierte DLL wird in derselben CLR wie der Prozess ausgeführt, in den sie geladen wurde.
  • Ausführbare Dateien, die mit anycpu kompiliert werden, werden in der 64-Bit-CLR ausgeführt.
  • Ausführbare Dateien, die mit anycpu32bitpreferred kompiliert werden, werden in der 32-Bit-CLR ausgeführt.

Die Einstellung anycpu32bitpreferred gilt nur für ausführbare Dateien (.exe) und erfordert .NET Framework 4.5 oder höher. Weitere Informationen zum Entwickeln einer Anwendung, die auf einem 64-Bit-Windows-Betriebssystem ausgeführt werden soll, finden Sie unter 64-Bit-Anwendungen.

Sie legen die Option PlatformTarget auf der Seite Buildeigenschaften für Ihr Projekt in Visual Studio fest.

Das Verhalten von anycpu weist einige zusätzliche Aspekte für .NET Core und .NET 5 sowie neuere Releases auf. Wenn Sie anycpu festlegen, veröffentlichen Sie Ihre App und führen sie entweder mit x86-dotnet.exe oder x64-dotnet.exe aus. Bei eigenständigen Apps verpackt der Schritt dotnet publish die ausführbare Datei für die RID-Konfiguration.

ProduceReferenceAssembly

Die Option ProduceReferenceAssembly steuert, ob der Compiler Referenzassembly erzeugt.

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

Verweisassemblys sind eine besondere Art von Assembly, die nur die Mindestmenge an Metadaten enthalten, die zum Darstellen der öffentlichen API-Oberfläche der Bibliothek erforderlich sind. Sie beinhalten Deklarationen für alle Member, die beim Verweis auf eine Assembly in Buildtools von Bedeutung sind. Verweisassemblys schließen alle Memberimplementierungen und Deklarationen privater Member aus. Diese Member besitzen keine beobachtbaren Auswirkungen auf ihren API-Vertrag. Weitere Informationen finden Sie unter Verweisassemblys im .NET-Leitfaden.

Die Optionen ProduceReferenceAssembly und ProduceOnlyReferenceAssembly schließen sich gegenseitig aus.

In der Regel müssen Sie nicht direkt mit Referenzassemblydateien arbeiten. Standardmäßig werden Referenzassemblys in einem ref-Unterordner des Zwischenpfads (d. h. obj/ref/) generiert. Um sie stattdessen im dem Ausgabeverzeichnis (d. h. bin/ref/) zu generieren, müssen Sie ProduceReferenceAssemblyInOutDir in Ihrem Projekt auf true festlegen.

In .NET SDK 6.0.200 wurde eine Änderung vorgenommen, durch die Referenzassemblys standardmäßig aus dem Ausgabeverzeichnis in das Zwischenverzeichnis verschoben wurden.

TargetType

Die Compileroption TargetType kann in einem der folgenden Formate angegeben werden:

  • library zum Erstellen einer Codebibliothek. library ist der Standardwert.
  • exe zum Erstellen einer EXE-Datei.
  • module zum Erstellen eines Moduls.
  • winex zum Erstellen eines Windows-Programms.
  • winmdobj zum Erstellen einer WINMDOBJ-Zwischendatei.
  • appcontainerexe zum Erstellen einer EXE-Datei für Windows 8.x Store-Apps.

Hinweis

Bei .NET Framework-Zielen bewirkt diese Option (sofern Sie nicht module angeben), dass ein .NET Framework-Assemblymanifest in einer Ausgabedatei platziert wird. Weitere Informationen finden Sie unter Assemblys in .NET und Häufig verwendete Attribute.

<TargetType>library</TargetType>

Der Compiler erstellt nur ein Assemblymanifest pro Kompilierung. Informationen über alle Dateien in einer Kompilierung werden im Assemblymanifest platziert. Wenn mehrere Ausgabedateien in der Befehlszeile erstellt werden, kann nur ein Assemblymanifest erstellt werden, und es muss in die erste Ausgabedatei gehen, die in der Befehlszeile angegeben wurde.

Wenn Sie eine Assembly erstellen, können Sie angeben, dass der ganze oder ein Teil des Codes mit dem CLSCompliantAttribute-Attribut CLS-kompatibel ist.

Bibliothek

Die Option library veranlasst den Compiler, eine Dynamic Link Library (DLL) statt einer ausführbaren Datei (EXE) zu erstellen. Die DLL wird mit der Erweiterung .dll erstellt. Wenn nichts anderes mit der Option OutputAssembly angegeben, übernimmt der Ausgabedateiname den Namen der ersten Eingabedatei. Beim Erstellen einer DLL-Datei ist keine Main-Methode erforderlich.

exe

Die Option exe bewirkt, dass der Compiler eine ausführbare Konsolenanwendung (EXE-Datei) erstellt. Die ausführbare Datei wird mit der Dateiendung „.exe“ erstellt. Verwenden Sie winexe, um ein ausführbares Windows-Programm zu erstellen. Wenn nichts anderes mit der Option OutputAssembly angegeben, übernimmt der Ausgabedateiname den Namen der Eingabedatei, die den Einstiegspunkt (Main-Methode oder Anweisungen der obersten Ebene) enthält. In den Quellcodedateien, die in eine EXE-Datei kompiliert werden, ist ein und nur ein Einstiegspunkt erforderlich. Mit der Compileroption StartupObject können Sie angeben, welche Klasse die Main-Methode enthält, falls Ihr Code mehr als eine Klasse mit einer Main-Methode enthält.

module

Diese Option bewirkt, dass der Compiler kein Assemblymanifest generiert. Standardmäßig weist die Ausgabedatei, die durch Kompilieren mit dieser Option erstellt wird, eine Dateierweiterung NETMODULE auf. Eine Datei ohne Assemblymanifest kann nicht von der .NET-Runtime geladen werden. Allerdings kann eine solche Datei mithilfe von AddModules in das Assemblymanifest integriert werden. Wird mehr als ein Modul in einer einzigen Kompilierung erstellt, werden interne Typen in einem Modul für andere Module in der Kompilierung verfügbar. Wenn der Code in einem Modul auf internal-Typen in einem anderen Modul verweist, dann müssen beide Module mithilfe von AddModules in ein Assemblymanifest integriert werden. Das Erstellen eines Moduls wird in der Visual Studio-Entwicklungsumgebung nicht unterstützt.

winexe

Die Option winexe bewirkt, dass der Compiler ein ausführbares Windows-Programm (EXE-Datei) erstellt. Die ausführbare Datei wird mit der Dateiendung „.exe“ erstellt. Windows-Programme stellen eine Benutzeroberfläche immer aus der .NET-Bibliothek oder mithilfe von Windows-APIs bereit. Verwenden Sie exe, um eine Konsolenanwendung zu erstellen. Wenn nichts anderes mit der Option OutputAssembly angegeben wurde, übernimmt der Name der Ausgabedatei den Namen der Eingabedatei, die die Main-Methode enthält. Nur eine Main-Methode wird in den Quellcodedateien benötigt, die in eine EXE-Datei kompiliert werden. Mit der Option StartupObject können Sie angeben, welche Klasse die Main-Methode enthält, falls Ihr Code mehr als eine Klasse mit einer Main-Methode enthält.

winmdobj

Wenn Sie die Option winmdobj verwenden, erstellt der Compiler eine WINMDOBJ-Zwischendatei, die Sie in eine Windows-Runtime-Binärdatei (WINMD-Datei) konvertieren können. Die WINMD-Datei kann dann von verwalteten Sprachprogrammen sowie von JavaScript- und C++-Programmen verwendet werden.

Die Einstellung winmdobj signalisiert dem Compiler, dass ein Zwischenmodul erforderlich ist. Die WINMDOBJ-Datei kann dann durch das WinMDExp-Exporttool Eingaben erhalten, um eine Windows-Metadatendatei (WINMD-Datei) zu generieren. Die WINMD-Datei enthält sowohl den Code aus der ursprünglichen Bibliothek sowie die WinMD-Metadaten, die von JavaScript oder C++ und von der Windows-Runtime verwendet werden. Die Ausgabe einer Datei, die mit der Compileroption winmdobj kompiliert wurde, wird nur als Eingabe für das WimMDExp-Exporttool verwendet. Auf die WINMDOBJ-Datei selbst wird nicht direkt verwiesen. Sofern Sie nicht die Option OutputAssembly verwenden, übernimmt die Ausgabedatei den Namen der ersten Eingabedatei. Eine Main-Methode ist nicht erforderlich.

appcontainerexe

Wenn Sie die Compileroption appcontainerexe verwenden, erstellt der Compiler eine ausführbare Windows-Datei (EXE-Datei), die in einem App-Container ausgeführt werden muss. Diese Option entspricht -target:winexe, ist jedoch für Windows 8.x Store-Apps vorgesehen.

Diese Option legt ein Bit in der portierbaren ausführbaren Datei (Portable Executable, PE) fest, damit die App in einem App-Container ausgeführt werden muss. Wenn dieses Bit festgelegt ist, tritt ein Fehler auf, wenn die CreateProcess-Methode versucht, die ausführbare Datei außerhalb eines App-Containers zu starten. Sofern Sie nicht die Option OutputAssembly verwenden, erhält der Name der Ausgabedatei den Namen der Eingabedatei, die die Main-Methode enthält.