Параметры компилятора C#, которые управляют выводом компилятора

  • Статья

Следующие параметры управляют созданием выходных данных компилятора.

MSBuild csc.exe Description
DocumentationFile -doc: Создание XML-файла документации из комментариев ///.
OutputAssembly -out: Указание выходного файла сборки.
PlatformTarget -platform: Указание разрядности ЦП целевой платформы.
ProduceReferenceAssembly -refout: Создание базовой сборки.
TargetType -target: Указание типа выходной сборки.

DocumentationFile

Параметр DocumentationFile позволяет поместить комментарии из документации в XML-файл. Дополнительные сведения о документировании кода см. в статье Рекомендуемые теги для комментариев документации. Значение указывает путь к выходному XML-файлу. XML-файл содержит комментарии в файлах исходного кода компиляции.

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

Файл исходного кода, содержащий метод Main или инструкции верхнего уровня, выводится в XML первым. Часто вы предпочтете использовать созданный XML-файл с IntelliSense. Имя XML-файла должно совпадать с именем сборки. XML-файл должен находиться в том же каталоге, что и сборка. Если в проект Visual Studio добавляется ссылка на сборку, XML-файл также будет найден. Дополнительные сведения о создании комментариев к коду см. в статье Вставка XML-комментариев для создания документации. Если при компиляции не используется параметр <TargetType:Module>, file будет содержать теги <assembly> и </assembly>, которые указывают имя файла, содержащего манифест сборки для выходного файла. Примеры см. в статье Практическое руководство. Использование XML-документации.

Примечание.

Параметр DocumentationFile применяется ко всем файлам в проекте. Чтобы отключить предупреждения, связанные с комментариями документации для определенного файла или раздела кода, используйте директиву #pragma warning.

Этот параметр можно использовать в любом проекте в стиле пакета SDK для .NET. Дополнительные сведения см. в разделе о свойстве DocumentationFile.

OutputAssembly

Параметр OutputAssembly позволяет задать имя выходного файла. Выходной путь указывает на папку, куда помещаются выходные данные компилятора.

<OutputAssembly>folder</OutputAssembly>

Укажите полное имя и расширение файла, который требуется создать. Если не указать имя выходного файла, MSBuild использует имя проекта для указания имени выходной сборки. К проектам со старым стилем применяются следующие правила:

  • EXE-файлу будет присвоено имя файла исходного кода, который содержит метод Main или инструкции верхнего уровня.
  • DLL-файлы и NETMODULE-файлы берут имя из первого файла исходного кода.

Все модули, созданные в процессе компиляции, будут связаны со сборкой, полученной в результате этого процесса. С помощью ildasm.exe можно просмотреть связанные файлы в манифесте сборки.

Параметр компилятора OutputAssembly обязателен, если требуется установить EXE-файл в качестве целевого для дружественной сборки.

PlatformTarget

Указывает, в какой версии среды CLR может запускаться сборка.

<PlatformTarget>anycpu</PlatformTarget>
  • anycpu (по умолчанию) позволяет компилировать сборку для запуска на любой платформе. Если возможно, приложение выполняется как 64-разрядный процесс, а если доступен только 32-разрядный режим, переключается на него.
  • anycpu32bitpreferred (по умолчанию) позволяет компилировать сборку для запуска на любой платформе. Приложение выполняется в 32-разрядном режиме в системах, поддерживающих и 64-разрядные, и 32-разрядные приложения. Можно задать этот параметр только для проектов, предназначенных для .NET Framework 4.5 и выше.
  • ARM компилирует сборку для выполнения на компьютере с процессором Advanced RISC Machine (ARM).
  • ARM64 компилирует сборку для выполнения 64-разрядной средой CLR на компьютере с процессором Advanced RISC Machine (ARM) с поддержкой набора инструкций А64.
  • x64 компилирует сборку для запуска в 64-разрядной среде CLR на компьютере, поддерживающем набор инструкций AMD64 или EM64T.
  • x86 компилирует сборку для запуска в 32-разрядной среде CLR с архитектурой x86.
  • Itanium компилирует сборку для запуска в 64-разрядной среде CLR на компьютере с процессором Itanium.

В 64-разрядной ОС Windows:

  • Сборки, скомпилированные с параметром x86, будут выполняться в 32-разрядной среде CLR в подсистеме WOW64.
  • Библиотеки DLL, скомпилированные с использованием параметра anycpu, выполняются в той же среде CLR, в которую загружается процесс.
  • Исполняемые файлы, скомпилированные с использованием параметра anycpu, выполняются в 64-разрядной среде CLR.
  • Исполняемые файлы, скомпилированные с использованием параметра anycpu32bitpreferred, выполняются в 32-разрядной среде CLR.

Параметр anycpu32bitpreferred является допустимым только для исполняемых файлов (.exe). Он используется только с .NET Framework 4.5 и выше. Дополнительные сведения о разработке приложений для запуска в 64-разрядной операционной системе Windows см. в разделе 64-разрядные приложения.

Параметр PlatformTarget можно задать на странице свойств сборки для проекта в Visual Studio.

В .NET Core, .NET 5 и более поздних выпусках параметр anycpu имеет некоторые особенности. Если вы указали параметр anycpu, опубликуйте приложение и выполняйте его только с dotnet.exe x86 или только с dotnet.exe x64. Если вы используете автономные приложения, на этапе dotnet publish упаковывается исполняемый файл для настройки RID.

ProduceReferenceAssembly

Параметр ProduceReferenceAssembly определяет, создает ли компилятор ссылочные сборки.

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

Базовые сборки являются особым типом сборки, которая содержит только минимальный объем метаданных, необходимый для представления общедоступного API-интерфейса библиотеки. Такие сборки включают в себя объявления для всех элементов, которые важны при указании ссылки на сборку в средствах сборки. Базовые сборки исключают все реализации элементов, а также объявления закрытых элементов, не имеющих наблюдаемого влияния на их контракт API. Дополнительные сведения см. в статье Базовые сборки в руководстве по .NET.

Параметры ProduceReferenceAssembly и ProduceOnlyReferenceAssembly являются взаимоисключающими.

Как правило, вам не нужно работать напрямую с файлами эталонной сборки. По умолчанию эталонные сборки создаются в вложенной ref папке промежуточного пути (т. е. obj/ref/). Чтобы создать их в выходном каталоге (т. е. bin/ref/) в ProduceReferenceAssemblyInOutDirtrue проекте.

Пакет SDK для .NET 6.0.200 по умолчанию изменил ссылочные сборки из выходного каталога в промежуточный каталог.

TargetType

Параметр компилятора TargetType можно задать в одной из следующих форм:

  • library: для создания библиотеки кода. library — это значение по умолчанию.
  • exe: для создания EXE-файла.
  • module: для создания модуля.
  • winexe: для создания программы Windows.
  • winmdobj: для создания промежуточного файла .winmdobj.
  • appcontainerexe: для создания EXE-файла для приложений Магазина Windows 8.x.

Примечание.

Если вы создаете приложения для .NET Framework и не указываете значение module, этот параметр приводит к помещению манифеста сборки .NET Framework в выходной файл. Дополнительные сведения см. в разделах Сборки в .NET и Общие атрибуты.

<TargetType>library</TargetType>

При каждой компиляции компилятор создает только один манифест сборки. В манифест сборки добавляются сведения обо всех файлах в компиляции. При создании нескольких выходных файлов в командной строке может быть создан только один манифест сборки, который добавляется в первый выходной файл, указанный в командной строке.

При создании сборки можно указать, что код полностью или частично CLS-совместим с атрибутом CLSCompliantAttribute.

библиотека

Параметр library указывает компилятору создавать библиотеку динамической компоновки (DLL), а не исполняемый файл (EXE). Библиотека DLL создается с расширением .dll. Выходной файл получает имя первого входного файла, если только с помощью параметра OutputAssembly не указано иное. При сборке DLL-файла метод Main не требуется.

exe

Параметр exe указывает компилятору создать исполняемое (EXE) консольное приложение. Исполняемый файл создается с расширением ЕХЕ. Используйте параметр winexe для создания исполняемого файла программы Windows. Если не указано иное с помощью параметра OutputAssembly, имя выходного файла совпадает с именем входного файла, который содержит точку входа (метод Main или инструкции верхнего уровня). В файлах исходного кода, который компилируется в EXE-файл, должна содержаться только одна точка входа. Если код содержит несколько классов с методом Main, указать, какой класс содержит метод Main, можно с помощью параметра компилятора StartupObject.

модуль

Этот параметр указывает компилятору не создавать манифест сборки. По умолчанию выходной файл, созданный при компиляции с этим параметром, имеет расширение .netmodule. Файл без манифеста сборки не может быть загружен в среду выполнения .NET. Но его можно включить в манифест сборки с помощью параметра AddModules. Если в рамках одной процедуры компиляции создается несколько модулей, типы internal из одного модуля будут доступны для других модулей, компилируемых вместе с ним. Если код одного модуля ссылается на типы internal в другом модуле, оба модуля нужно включить в манифест сборки с помощью параметра AddModules. Создание модуля в среде разработки Visual Studio не поддерживается.

winexe

Параметр winexe указывает компилятору создать исполняемый файл (EXE) программы Windows. Исполняемый файл создается с расширением ЕХЕ. Программа Windows предоставляет пользовательский интерфейс либо из библиотеки .NET, либо с помощью API-интерфейсов Windows. Воспользуйтесь параметром exe, чтобы создать консольное приложение. Если не указано иное с помощью параметра OutputAssembly, имя выходного файла совпадает с именем входного файла, который содержит метод Main. Один и только один Main метод требуется в файлах исходного кода, скомпилированных в файл .exe. Если код содержит несколько классов с методом Main, указать, какой класс содержит метод Main, можно с помощью параметра StartupObject.

winmdobj

Если используется параметр winmdobj, компилятор создает промежуточный WINMDOBJ-файл, который можно преобразовать в двоичный WINMD-файл среды выполнения Windows. Затем WINMD-файл можно использовать в программах на языках JavaScript и C++ в дополнение к программам, использующим управляемые языки.

Параметр winmdobj сигнализирует компилятору, что необходим промежуточный модуль. Затем WINMDOBJ-файл можно передать с помощью инструмента экспорта WinMDExp для создания файла метаданных Windows (WINCMD-файл). WINMD-файл содержит код из исходной библиотеки и метаданные WinMD, используемые JavaScript, C++ и средой выполнения Windows. Выходные данные файла, скомпилированного с помощью параметра компилятора winmdobj, используются только в качестве входных данных инструментом экспорта WimMDExp (на WINMDOBJ-файл нет прямой ссылки). Выходной файл получает имя первого входного файла, если только не используется параметр OutputAssembly. Метод Main не требуется.

appcontainerexe

Если используется параметр компилятора appcontainerexe, компилятор создает исполняемый файл Windows (EXE-файл), который должен запускаться в контейнере приложения. Этот параметр аналогичен -target:winexe, но предназначен для приложений Магазина Windows 8.x.

Этот параметр устанавливает бит в переносимом исполняемом файле (PE), чтобы обеспечить запуск приложения в контейнере. Если он установлен, при попытке запустить исполняемый файл вне контейнера приложения методом CreateProcess будет возникать ошибка. Выходной файл получает имя входного файла, содержащего метод Main, если только с помощью параметра OutputAssembly не указано иное.