Opcje kompilatora języka C# kontrolujące dane wyjściowe kompilatora

Następujące opcje kontrolują generowanie danych wyjściowych kompilatora.

MSBuild	csc.exe	opis
DocumentationFile	-doc:	Wygeneruj plik dokumentu XML na podstawie /// komentarzy.
OutputAssembly	-out:	Określ wyjściowy plik zestawu.
PlatformaTarget	-platform:	Określ docelowy procesor CPU platformy.
ProduceReferenceAssembly	-refout:	Generowanie zestawu referencyjnego.
TargetType	-target:	Określ typ zestawu wyjściowego.

Uwaga

Aby uzyskać więcej informacji na temat konfigurowania tych opcji dla projektu, zobacz Opcje kompilatora.

DocumentationFile

Opcja DocumentationFile umożliwia umieszczenie komentarzy dokumentacji w pliku XML. Aby dowiedzieć się więcej na temat dokumentowania kodu, zobacz Zalecane tagi komentarzy dokumentacji. Wartość określa ścieżkę do wyjściowego pliku XML. Plik XML zawiera komentarze w plikach kodu źródłowego kompilacji.

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

Plik kodu źródłowego, który zawiera instrukcje Main lub najwyższego poziomu, jest najpierw wyjściowy do kodu XML. Często chcesz użyć wygenerowanego pliku .xml z funkcją IntelliSense. Nazwa pliku .xml musi być taka sama jak nazwa zestawu. Plik .xml musi znajdować się w tym samym katalogu co zestaw. Po odwołaniu się do zestawu w projekcie programu Visual Studio zostanie również znaleziony plik .xml . Aby uzyskać więcej informacji na temat generowania komentarzy do kodu, zobacz Dostarczanie komentarzy do kodu. O ile nie skompilujesz <TargetType:Module>elementu , file będzie zawierać <assembly> tagi i </assembly> określać nazwę pliku zawierającego manifest zestawu dla pliku wyjściowego. Przykłady można znaleźć w temacie How to use the XML documentation features (Jak używać funkcji dokumentacji XML).

Uwaga

Opcja DocumentationFile ma zastosowanie do wszystkich plików w projekcie. Aby wyłączyć ostrzeżenia związane z komentarzami dokumentacji dla określonego pliku lub sekcji kodu, użyj ostrzeżenia #pragma.

Tej opcji można używać w dowolnym projekcie w stylu zestawu SDK platformy .NET. Aby uzyskać więcej informacji, zobacz właściwość DocumentationFile.

OutputAssembly

Opcja OutputAssembly określa nazwę pliku wyjściowego. Ścieżka wyjściowa określa folder, w którym są umieszczane dane wyjściowe kompilatora.

<OutputAssembly>folder</OutputAssembly>

Określ pełną nazwę i rozszerzenie pliku, który chcesz utworzyć. Jeśli nie określisz nazwy pliku wyjściowego, program MSBuild używa nazwy projektu do określenia nazwy zestawu wyjściowego. Stare projekty stylów używają następujących reguł:

• .exe będzie przyjmować jego nazwę z pliku kodu źródłowego, który zawiera Main instrukcje metody lub najwyższego poziomu.
• .dll lub .netmodule będzie przyjmować jego nazwę z pierwszego pliku kodu źródłowego.

Wszystkie moduły utworzone w ramach kompilacji stają się plikami skojarzonymi z dowolnym zestawem utworzonym również w kompilacji. Użyj ildasm.exe , aby wyświetlić manifest zestawu, aby wyświetlić skojarzone pliki.

Opcja kompilatora OutputAssembly jest wymagana, aby plik exe był elementem docelowym zestawu znajomego.

PlatformaTarget

Określa, która wersja środowiska CLR może uruchomić zestaw.

<PlatformTarget>anycpu</PlatformTarget>

• anycpu (ustawienie domyślne) kompiluje zestaw do uruchamiania na dowolnej platformie. Aplikacja działa jako proces 64-bitowy, gdy jest to możliwe i wraca do 32-bitowego, gdy tylko ten tryb jest dostępny.
• anycpu32bitpreferred kompiluje zestaw do uruchamiania na dowolnej platformie. Aplikacja działa w trybie 32-bitowym w systemach obsługujących zarówno aplikacje 64-bitowe, jak i 32-bitowe. Tę opcję można określić tylko dla projektów przeznaczonych dla programu .NET Framework 4.5 lub nowszego.
• Usługa ARM kompiluje zestaw do uruchamiania na komputerze z procesorem Advanced RISC Machine (ARM).
• Arm64 kompiluje zestaw do uruchamiania przez 64-bitową clR na komputerze z procesorem Advanced RISC Machine (ARM), który obsługuje zestaw instrukcji A64.
• X64 kompiluje zestaw do uruchomienia przez 64-bitową clR na komputerze obsługującym zestaw instrukcji AMD64 lub EM64T.
• X86 kompiluje zestaw do uruchomienia przez 32-bitowy, x86-zgodny CLR.
• Itanium kompiluje zestaw do uruchomienia przez 64-bitową CLR na komputerze z procesorem Itanium.

W 64-bitowym systemie operacyjnym Windows:

• Zestawy skompilowane przy użyciu środowiska x86 są wykonywane w 32-bitowym środowisku CLR działającym w systemie WOW64.
• Biblioteka DLL skompilowana z dowolnym procesorem jest wykonywana na tym samym clR co proces, do którego jest ładowany.
• Pliki wykonywalne skompilowane przy użyciu instrukcji anycpu są wykonywane w 64-bitowej clR.
• Pliki wykonywalne skompilowane za pomocą polecenia anycpu32bitpreferred wykonywane w 32-bitowej clR.

Ustawienie anycpu32bitpreferred jest prawidłowe tylko dla plików wykonywalnych (.EXE) i wymaga programu .NET Framework 4.5 lub nowszego. Aby uzyskać więcej informacji na temat tworzenia aplikacji do uruchamiania w systemie operacyjnym Windows 64-bitowym, zobacz 64-bitowe aplikacje.

Należy ustawić opcję PlatformTarget na stronie Właściwości kompilacji dla projektu w programie Visual Studio.

Zachowanie dowolnego procesora ma pewne dodatkowe niuanse w wersjach .NET Core i .NET 5 i nowszych. Po ustawieniu platformy anycpu opublikuj aplikację i wykonaj ją przy użyciu architektury x86 dotnet.exe lub x64 dotnet.exe. W przypadku aplikacji dotnet publish samodzielnie krok pakuje plik wykonywalny dla skonfigurowanego identyfikatora RID.

ProduceReferenceAssembly

Opcja ProduceReferenceAssembly określa, czy kompilator tworzy zestawy odwołań.

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

Zestawy referencyjne to specjalny typ zestawu, który zawiera tylko minimalną ilość metadanych wymaganych do reprezentowania publicznej powierzchni interfejsu API biblioteki. Zawierają deklaracje dla wszystkich elementów członkowskich, które są istotne podczas odwoływania się do zestawu w narzędziach kompilacji. Zestawy odwołań wykluczają wszystkie implementacje składowych i deklaracje składowych prywatnych. Ci członkowie nie mają zauważalnego wpływu na kontrakt interfejsu API. Aby uzyskać więcej informacji, zobacz Dokumentacja zestawów w przewodniku platformy .NET.

Opcje ProduceReferenceAssembly i ProduceOnlyReferenceAssembly wzajemnie się wykluczają.

Zazwyczaj nie trzeba pracować bezpośrednio z plikami zestawów odwołań. Domyślnie zestawy odwołań są generowane w ref podfolderze ścieżki pośredniej (tj. obj/ref/). Aby wygenerować je w katalogu wyjściowym zamiast (tj. bin/ref/) ustawiono ProduceReferenceAssemblyInOutDir na true wartość w projekcie.

Zestaw .NET SDK 6.0.200 wprowadził zmianę, która domyślnie przeniosła zestawy odwołań z katalogu wyjściowego do katalogu pośredniego.

TargetType

Opcję kompilatora TargetType można określić w jednej z następujących formularzy:

• biblioteka: aby utworzyć bibliotekę kodu. biblioteka jest wartością domyślną.
• exe: aby utworzyć plik .exe.
• moduł do utworzenia modułu.
• winexe w celu utworzenia programu systemu Windows.
• winmdobj , aby utworzyć pośredni plik winmdobj .
• appcontainerexe , aby utworzyć plik .exe dla aplikacji ze Sklepu Windows 8.x.

Uwaga

W przypadku obiektów docelowych programu .NET Framework, chyba że określono moduł, ta opcja powoduje umieszczenie manifestu zestawu .NET Framework w pliku wyjściowym. Aby uzyskać więcej informacji, zobacz Zestawy na platformie .NET i typowe atrybuty.

<TargetType>library</TargetType>

Kompilator tworzy tylko jeden manifest zestawu na kompilację. Informacje o wszystkich plikach w kompilacji są umieszczane w manifeście zestawu. Podczas tworzenia wielu plików wyjściowych w wierszu polecenia można utworzyć tylko jeden manifest zestawu i przejść do pierwszego pliku wyjściowego określonego w wierszu polecenia.

Jeśli tworzysz zestaw, możesz wskazać, że wszystkie lub część kodu są zgodne ze specyfikacją CLSCompliantAttribute CLS.

biblioteka

Opcja biblioteki powoduje, że kompilator tworzy bibliotekę łącza dynamicznego (DLL), a nie plik wykonywalny (EXE). Biblioteka DLL zostanie utworzona przy użyciu rozszerzenia .dll . O ile nie określono inaczej z opcją OutputAssembly , nazwa pliku wyjściowego przyjmuje nazwę pierwszego pliku wejściowego. Podczas tworzenia pliku .dll metoda nie jest wymagana Main .

exe

Opcja exe powoduje, że kompilator tworzy plik wykonywalny (EXE), aplikację konsolową. Plik wykonywalny zostanie utworzony za pomocą rozszerzenia .exe. Użyj winexe , aby utworzyć plik wykonywalny programu systemu Windows. O ile nie określono inaczej z opcją OutputAssembly , nazwa pliku wyjściowego przyjmuje nazwę pliku wejściowego, który zawiera punkt wejścia (metoda Main lub instrukcje najwyższego poziomu). Jeden i tylko jeden punkt wejścia jest wymagany w plikach kodu źródłowego, które są kompilowane w pliku .exe. Opcja kompilatora StartupObject umożliwia określenie, która klasa zawiera Main metodę, w przypadkach, gdy kod ma więcej niż jedną klasę Main z metodą.

moduł

Ta opcja powoduje, że kompilator nie generuje manifestu zestawu. Domyślnie plik wyjściowy utworzony przez kompilowanie za pomocą tej opcji będzie miał rozszerzenie .netmodule. Nie można załadować pliku, który nie ma manifestu zestawu przez środowisko uruchomieniowe platformy .NET. Jednak taki plik można włączyć do manifestu zestawu za pomocą funkcji AddModules. Jeśli w jednej kompilacji zostanie utworzony więcej niż jeden moduł, typy wewnętrzne w jednym module będą dostępne dla innych modułów w kompilacji. Gdy kod w jednym module odwołuje się do internal typów w innym module, oba moduły muszą zostać włączone do manifestu zestawu z dodatkiem AddModules. Tworzenie modułu nie jest obsługiwane w środowisku programistycznym programu Visual Studio.

winexe

Opcja winexe powoduje, że kompilator tworzy plik wykonywalny (EXE), program systemu Windows. Plik wykonywalny zostanie utworzony za pomocą rozszerzenia .exe. Program systemu Windows to taki, który udostępnia interfejs użytkownika z biblioteki .NET lub z interfejsami API systemu Windows. Użyj narzędzia exe , aby utworzyć aplikację konsolową. Jeśli nie określono inaczej z opcją OutputAssembly, nazwa pliku wyjściowego przyjmuje nazwę pliku wejściowego, który zawiera metodęMain. Jedna i jedna Main metoda jest wymagana w plikach kodu źródłowego, które są kompilowane w pliku .exe. Opcja StartupObject umożliwia określenie, która klasa zawiera metodę Main , w przypadkach, gdy kod ma więcej niż jedną klasę Main z metodą.

winmdobj

Jeśli używasz opcji winmdobj, kompilator tworzy pośredni plik winmdobj, który można przekonwertować na plik binarny środowisko wykonawcze systemu Windows (winmd). Plik winmd może być następnie używany przez programy JavaScript i C++, oprócz programów językowych zarządzanych.

Ustawienie winmdobj sygnalizuje kompilatorowi, że wymagany jest moduł pośredni. Plik .winmdobj można następnie karmić za pomocą WinMDExp narzędzia eksportu w celu utworzenia pliku metadanych systemu Windows (winmd). Plik winmd zawiera zarówno kod z oryginalnej biblioteki, jak i metadanych WinMD używanych przez język JavaScript lub C++ oraz przez środowisko wykonawcze systemu Windows. Dane wyjściowe pliku skompilowanego przy użyciu opcji kompilatora winmdobj są używane tylko jako dane wejściowe dla narzędzia eksportu WimMDExp. Sam plik winmdobj nie jest bezpośrednio przywoływalny. Jeśli nie używasz opcji OutputAssembly , nazwa pliku wyjściowego przyjmuje nazwę pierwszego pliku wejściowego. Main Metoda nie jest wymagana.

appcontainerexe

Jeśli używasz opcji kompilatora appcontainerexe , kompilator tworzy plik wykonywalny systemu Windows (.exe), który musi być uruchamiany w kontenerze aplikacji. Ta opcja jest odpowiednikiem -target:winexe , ale jest przeznaczona dla aplikacji ze Sklepu Windows 8.x.

Aby wymagać uruchomienia aplikacji w kontenerze aplikacji, ta opcja ustawia bit w pliku przenośnym wykonywalnym (PE). Po ustawieniu tego bitu wystąpi błąd, jeśli metoda CreateProcess próbuje uruchomić plik wykonywalny poza kontenerem aplikacji. Jeśli nie używasz opcji OutputAssembly , nazwa pliku wyjściowego przyjmuje nazwę pliku wejściowego, który zawiera metodę Main .