Настройки Build Action в Visual Studio: Полное руководство

The Build Action property in Visual Studio determines how each file in your project is handled during the build process, controlling whether files are compiled, copied, embedded, or ignored entirely. This setting is crucial for managing different types of files in your project, from source code and XAML files to resources, content, and documentation.

Contents

• Что такое Build Action?
• Общие типы Build Action
• Специализированные Build Action
• Практические примеры и варианты использования
• Лучшие практики
• Устранение неполадок Build Action

Что такое Build Action?

Build Action property specifies what Visual Studio does with a file during a build process. According to Microsoft’s documentation, all files in a Visual Studio project have a build action that controls what happens to the file when the project is compiled.

This property can be found in the file properties window when you select a file in Solution Explorer. It’s stored in the project file (like .csproj or .vbproj) and affects how the file is processed during compilation and deployment.

Ключевой вывод: Настройка Build Action работает в сочетании с свойством «Copy to Output Directory», но они служат разным целям. Как отмечено в обсуждениях Stack Overflow, даже файлы с Build Action «None» могут быть скопированы в каталог сборки, если свойство копирования установлено соответствующим образом.

Общие типы Build Action

Compile

Compile – самый распространённый и простой вариант. Файлы с этим действием компилируются в выходной файл вместе с вашим исходным кодом. Обычно это устанавливается для:

• C# (.cs), VB.NET (.vb) исходных файлов
• XAML файлов в проектах WPF, UWP и MAUI
• TypeScript (.ts) файлов при использовании проектов TypeScript

Согласно объяснению Coder Cream, «Файл компилируется в выходной файл» – то есть он проходит через компилятор и становится частью вашего приложения.

Content

Content указывает, что файл не компилируется, но включается в группу выходных файлов Content. Это идеально подходит для:

• HTML файлов, изображений и других веб-ресурсов
• Конфигурационных файлов, которые должны быть внешними от исполняемого файла
• Медиа файлов и документов, которые должны оставаться отдельными от скомпилированного кода

Как объясняется в обсуждениях Stack Overflow, «Файл не компилируется, но включается в группу выходных файлов Content. Например, это значение по умолчанию для .htm или другого типа веб-файла».

Embedded Resource

Embedded Resource встраивает файл напрямую в результирующую сборку как ресурс манифеста. Это полезно для:

• Файлов ресурсов, которые необходимо получать программно
• Локализованных файлов контента
• Конфигурационных шаблонов, которые должны быть частью исполняемого файла

Блог Ivan Krivyakov уточняет, что «оба вида ресурсов фактически встраиваются в исполняемый файл. Файлы EmbeddedResource размещаются напрямую в исполняемом файле как ресурсы манифеста».

Resource

Resource похож на Embedded Resource, но с некоторыми отличиями в том, как ресурсы доступны и управляются. Ресурсы с этим действием:

• Компилируются в спутниковые сборки для локализации
• Могут быть доступны через строго типизированные классы ресурсов
• Обычно используются для таблиц строк и другого локализуемого контента

None

None означает, что файл не включается в группу выходных файлов проекта и не компилируется в процессе сборки. Это подходит для:

• Документационных файлов, таких как README.txt
• Временных или заглушечных файлов
• Файлов, которые обрабатываются пользовательскими шагами сборки

Как отмечено в объяснении Coder Cream, «Примером является текстовый файл, содержащий документацию, такой как файл Readme».

Специализированные Build Action

ApplicationDefinition

ApplicationDefinition специфичен для проектов WPF и Silverlight и отмечает XAML файл, который определяет ваше приложение. При первом создании проекта обычно это App.xaml. Согласно документации Microsoft, «Этот файл определяет ваше приложение».

Page

Page используется для XAML файлов, которые определяют пользовательские интерфейсы, такие как Window.xaml, UserControl.xaml и Page.xaml. Эти файлы компилируются в BAML (Binary Application Markup Language) и включаются в сборку.

CodeAnalysisDictionary

CodeAnalysisDictionary указывает XML файл, содержащий пользовательские словари слов, используемые Code Analysis для проверки правописания. Как объясняет Microsoft, «Пользовательский словарь слов, используемый Code Analysis для проверки правописания».

DesignDataWithDesignTimeCreatableTypes

Этот специализированный Build Action используется для данных времени дизайна WPF. Согласно нескольким источникам, включая Stack Overflow и CopyProgramming, этот Build Action «Компилирует XAML viewmodels, чтобы пользовательские элементы управления могли быть предпросмотрены с примерными данными в Visual Studio (использует реальные типы)».

EntityDeploy

EntityDeploy специфичен для проектов Entity Framework и используется для развертывания артефактов Entity Framework, таких как определения модели и скрипты базы данных.

AdditionalFiles

AdditionalFiles отмечает файлы, которые напрямую не участвуют в компиляции, но используются другими инструментами, такими как:

• Файлы конфигурации анализаторов
• Спецификации OpenAPI/Swagger
• Пользовательские генераторы документации

SplashScreen

SplashScreen указывает файл изображения, который будет использоваться в качестве заставки приложения во время запуска.

Fakes

Fakes используется с Microsoft Fakes framework для создания шимов и заглушек во время тестирования.

XamlAppDef

XamlAppDef похож на ApplicationDefinition, но используется в определенных сценариях для приложений на основе XAML.

Практические примеры и варианты использования

Структура проекта WPF

В типичном проекте WPF вы увидите:

• App.xaml – ApplicationDefinition
• MainWindow.xaml – Page
• UserControl.xaml – Page
• Styles.xaml – Resource
• Images/ – Content (с соответствующим свойством Copy to Output Directory)
• App.config – None (обрабатывается автоматически системой сборки)

Проект веб-приложения

Для веб-приложения:

• Default.aspx – Compile
• Web.config – Content
• CSS файлы – Content
• JavaScript файлы – Content
• Images/ – Content
• README.md – None

Проект библиотеки классов

В библиотеке классов:

• Class.cs – Compile
• Resources.resx – Embedded Resource
• Documentation.xml – None
• SampleData.json – Content

Лучшие практики

Когда использовать Compile

• Используйте Compile для всех файлов исходного кода
• Позвольте Visual Studio устанавливать значения по умолчанию для XAML файлов и других файлов, специфичных для проекта
• Избегайте ручной смены настроек Compile для файлов, которые управляются Visual Studio

Когда использовать Content

• Используйте Content для файлов, которые должны оставаться внешними от исполняемого файла
• Рассмотрите Content для конфигурационных файлов, шаблонов и статических ресурсов
• Установите «Copy to Output Directory» соответствующим образом (Copy if Newer vs Copy Always)

Когда использовать Embedded Resource

• Используйте Embedded Resource для файлов, которые необходимо получать программно
• Рассмотрите для локализованного контента и ресурсов, которые должны сопровождать сборку
• Убедитесь в правильном именовании ресурсов и паттернах доступа

Когда использовать None

• Используйте None для документации, временных файлов или файлов, обрабатываемых пользовательскими шагами сборки
• Имейте в виду, что файлы с None могут быть скопированы, если «Copy to Output Directory» установлен

Устранение неполадок Build Action

Файлы не копируются в выходной каталог

Если файлы не появляются в выходном каталоге сборки:

1. Проверьте как Build Action, так и «Copy to Output Directory»
2. Помните, что файлы с Build Action «None» могут быть скопированы
3. Проверьте конфигурации сборки (Debug vs Release), чтобы убедиться, что настройки одинаковы

Отсутствие ресурсов во время выполнения

Если встроенные ресурсы не найдены:

1. Убедитесь, что Build Action установлен на Embedded Resource или Resource
2. Проверьте, что имена ресурсов корректны в коде
3. Убедитесь, что Build Action подходит для вашего типа ресурса

Проблемы времени дизайна

Если дизайнер WPF не работает должным образом:

1. Проверьте, что файлы данных времени дизайна имеют соответствующие Build Action
2. Убедитесь, что DesignDataWithDesignTimeCreatableTypes установлен для примеров данных
3. Проверьте, что ссылки на типы доступны во время дизайна

Заключение

Понимание настроек Build Action в Visual Studio необходимо для правильной организации проекта и развертывания. Ключевые выводы:

1. Build Action определяет обработку: Build Action каждого файла контролирует, будет ли он компилироваться, копироваться, встраиваться или игнорироваться во время сборки.
2. Настройки по умолчанию обычно работают: Для большинства файлов вы можете полагаться на настройки Build Action, установленные Visual Studio, которые обычно подходят для каждого типа файла.
3. Комбинируйте с Copy to Output Directory: Помните, что Build Action работает совместно с «Copy to Output Directory», и оба параметра влияют на то, куда файлы попадают в выходной каталог.
4. Специализированные действия для конкретных задач: Используйте специализированные Build Actions, такие как ApplicationDefinition, CodeAnalysisDictionary или DesignDataWithDesignTimeCreatableTypes, для специфических сценариев разработки.
5. Проверяйте конфигурации сборки: Всегда проверяйте, что файлы корректно появляются в каталоге вывода как для Debug, так и для Release сборок.

Понимая эти различные настройки Build Action, вы сможете лучше организовать свои проекты, обеспечить правильное развертывание всех необходимых файлов и избежать распространённых проблем, связанных со сборкой.

Источники

1. What are the various “Build action” settings in Visual Studio project properties and what do they do? - Stack Overflow
2. Build actions for files - Visual Studio (Windows) | Microsoft Learn
3. Visual Studio - File Properties (Build Action, Copy to Output Directory) - frank_cui - Blog
4. Visual Studio Build Action - Coder Cream
5. visualstudio-docs/docs/ide/build-actions.md at main · MicrosoftDocs/visualstudio-docs
6. What is Content Build Action in Visual Studio? - Stack Overflow
7. One more time about Resource vs. EmbeddedResource – Ivan Krivyakov
8. What “Build action” settings in Visual Studio file’s do? - wankosoft.blogspot.com