Общие сведения о файле проекта
файлы проекта Microsoft Build Engine (MSBuild) лежат в основе процесса сборки и развертывания. Этот раздел начинается с концептуального обзора MSBuild и файла проекта. В ней описываются ключевые компоненты, с которыми вы столкнулись при работе с файлами проекта, а также пример использования файлов проекта для развертывания реальных приложений.
Из этого руководства вы узнаете, как выполнять такие задачи:
- Как MSBuild использует файлы проекта MSBuild для сборки проектов.
- Интеграция MSBuild с технологиями развертывания, такими как средство веб-развертывания служб IIS (веб-развертывание).
- Сведения о ключевых компонентах файла проекта.
- Как можно использовать файлы проекта для сборки и развертывания сложных приложений.
MSBuild и файл проекта
При создании и сборке решений в Visual Studio Visual Studio использует MSBuild для сборки каждого проекта в решении. Каждый проект Visual Studio включает файл проекта MSBuild с расширением, которое отражает тип проекта, например проект C# (CSPROJ), проект Visual Basic.NET (VBPROJ) или проект базы данных (DBPROJ). Чтобы создать проект, MSBuild должен обработать файл проекта, связанный с проектом. Файл проекта — это XML-документ, содержащий все сведения и инструкции, необходимые MSBuild для сборки проекта, например содержимое для включения, требования к платформе, сведения о версиях, параметры веб-сервера или сервера базы данных, а также задачи, которые необходимо выполнить.
Файлы проекта MSBuild основаны на xml-схеме MSBuild, поэтому процесс сборки полностью открыт и прозрачен. Кроме того, вам не нужно устанавливать Visual Studio для использования подсистемы MSBuild— исполняемый файл MSBuild.exe является частью платформа .NET Framework, и его можно запустить из командной строки. Как разработчик вы можете создавать собственные файлы проекта MSBuild, используя xml-схему MSBuild, чтобы обеспечить сложный и детализированный контроль над тем, как создаются и развертываются проекты. Эти пользовательские файлы проекта работают точно так же, как файлы проекта, создаваемые Visual Studio автоматически.
Примечание
Вы также можете использовать файлы проекта MSBuild со службой Team Build в Team Foundation Server (TFS). Например, файлы проекта можно использовать в сценариях непрерывной интеграции (CI), чтобы автоматизировать развертывание в тестовой среде при извлечении нового кода. Дополнительные сведения см. в разделе Настройка Team Foundation Server для автоматического веб-развертывания.
Соглашения об именовании файлов проекта
При создании собственных файлов проекта можно использовать любое расширение файла. Однако, чтобы упростить понимание решений для других пользователей, следует использовать следующие распространенные соглашения:
- Используйте расширение .proj при создании файла проекта, который создает проекты.
- Используйте расширение TARGETS при создании повторно используемого файла проекта для импорта в другие файлы проекта. Файлы с расширением TARGETS обычно ничего не создают сами, они просто содержат инструкции, которые можно импортировать в файлы .proj.
Интеграция с технологиями развертывания
Если вы работали с проектами веб-приложений в Visual Studio 2010, такими как ASP.NET веб-приложения и ASP.NET веб-приложения MVC, вы будете знать, что эти проекты включают встроенную поддержку упаковки и развертывания веб-приложения в целевой среде. Страницы Свойств для этих проектов включают вкладки Пакет/Публикация в Интернете и Пакет/Публикация SQL, которые можно использовать для настройки способа упаковки и развертывания компонентов приложения. На ней отображается вкладка "Веб-пакет/публикация ":
Базовая технология, лежащая в основе этих возможностей, называется конвейером веб-публикации (WPP). WPP, по сути, объединяет MSBuild и веб-развертывание , чтобы обеспечить полный процесс сборки, пакета и развертывания для веб-приложений.
Хорошей новостью является то, что вы можете воспользоваться преимуществами точек интеграции, которые предоставляет WPP при создании пользовательских файлов проекта для веб-проектов. Вы можете включить инструкции по развертыванию в файл проекта, который позволяет создавать проекты, создавать пакеты веб-развертывания и устанавливать эти пакеты на удаленных серверах с помощью одного файла проекта и одного вызова MSBuild. Вы также можете вызывать любые другие исполняемые файлы в процессе сборки. Например, можно запустить программу командной строки VSDBCMD.exe для развертывания базы данных из файла схемы. В ходе работы с этим разделом вы узнаете, как использовать эти возможности для удовлетворения требований корпоративных сценариев развертывания.
Примечание
Дополнительные сведения о том, как работает процесс развертывания веб-приложения, см. в разделе Общие сведения о развертывании проекта веб-приложения ASP.NET.
Структура файла проекта
Прежде чем более подробно взглянуть на процесс сборки, стоит провести несколько минут, чтобы ознакомиться с базовой структурой файла проекта MSBuild. В этом разделе представлен обзор наиболее распространенных элементов, которые будут встречаться при просмотре, изменении или создании файла проекта. В частности, вы узнаете:
- Использование свойств для управления переменными для процесса сборки.
- Использование элементов для идентификации входных данных процесса сборки, таких как файлы кода.
- Использование целевых объектов и задач для предоставления инструкций по выполнению в MSBuild с помощью свойств и элементов , определенных в другом месте файла проекта.
Здесь показана связь между ключевыми элементами в файле проекта MSBuild:
Элемент Project
Элемент Project является корневым элементом каждого файла проекта. Помимо определения схемы XML для файла проекта, элемент Project может включать атрибуты для указания точек входа для процесса сборки. Например, в примере решения Диспетчера контактов файл Publish.proj указывает, что сборка должна начинаться с вызова целевого объекта с именем FullPublish.
<Project ToolsVersion="4.0" DefaultTargets="FullPublish"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
</Project>
Свойства и условия
Для успешной сборки и развертывания проектов файл проекта обычно должен предоставлять множество различных сведений. Эти сведения могут включать имена серверов, строки подключения, учетные данные, конфигурации сборки, пути к исходным и целевым файлам, а также любые другие сведения, которые вы хотите включить для поддержки настройки. В файле проекта свойства должны быть определены в элементе PropertyGroup . Свойства MSBuild состоят из пар "ключ-значение". В элементе PropertyGroup имя элемента определяет ключ свойства, а содержимое элемента определяет значение свойства. Например, можно определить свойства с именами ServerName и ConnectionString для хранения имени статического сервера и строка подключения.
<PropertyGroup>
<ServerName>FABRIKAM\TEST1</ServerName>
<ConnectionString>
Data Source=FABRIKAM\TESTDB;InitialCatalog=ContactManager,...
</ConnectionString>
</PropertyGroup>
Чтобы получить значение свойства, используйте формат $(PropertyName). Например, чтобы получить значение свойства ServerName , введите:
$(ServerName)
Примечание
Вы увидите примеры того, как и когда использовать значения свойств далее в этом разделе.
Внедрение сведений в виде статических свойств в файл проекта не всегда является идеальным подходом к управлению процессом сборки. Во многих сценариях требуется получить информацию из других источников или предоставить пользователю возможность предоставлять информацию из командной строки. MSBuild позволяет указать любое значение свойства в качестве параметра командной строки. Например, пользователь может указать значение serverName при запуске MSBuild.exe из командной строки.
msbuild.exe Publish.proj /p:ServerName=FABRIKAM\TESTWEB1
Примечание
Дополнительные сведения о аргументах и параметрах, которые можно использовать с MSBuild.exe, см. в справочнике по командной строке MSBuild.
Для получения значений переменных среды и встроенных свойств проекта можно использовать тот же синтаксис свойств. Вы определяете множество часто используемых свойств, и их можно использовать в файлах проекта, включив соответствующее имя параметра. Например, чтобы получить текущую платформу проекта, например x86 или AnyCpu, можно включить ссылку на свойство $(Platform) в файл проекта. Дополнительные сведения см. в разделах Макросы для команд и свойств сборки, Общие свойства проекта MSBuild и Зарезервированные свойства.
Свойства часто используются в сочетании с условиями. Большинство элементов MSBuild поддерживают атрибут Condition , который позволяет указать критерии, по которым MSBuild должен оценивать элемент. Например, рассмотрим следующее определение свойства:
<PropertyGroup>
<OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\</OutputRoot>
...
</PropertyGroup>
Когда MSBuild обрабатывает это определение свойства, сначала проверяется, доступно ли значение свойства $(OutputRoot ). Если значение свойства пустое( другими словами, пользователь не предоставил значение для этого свойства), условие принимает значение true , а значение свойства — .. \Publish\Out. Если пользователь предоставил значение для этого свойства, условие принимает значение false , а значение статического свойства не используется.
Дополнительные сведения о различных способах указания условий см. в разделе Условия MSBuild.
Элементы и группы элементов
Одной из важных ролей файла проекта является определение входных данных для процесса сборки. Как правило, это файлы кода, файлы конфигурации, командные файлы и любые другие файлы, которые необходимо обработать или скопировать в процессе сборки. В схеме проекта MSBuild эти входные данные представлены элементами Item . В файле проекта элементы должны быть определены в элементе ItemGroup . Как и элементы Property , элементу Item можно присвоить имя. Однако необходимо указать атрибут Include , чтобы определить файл или подстановочный знак, который представляет элемент.
<ItemGroup>
<ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/>
</ItemGroup>
Указав несколько элементов Item с одинаковым именем, вы фактически создаете именованный список ресурсов. Хороший способ увидеть это в действии — заглянуть в один из файлов проекта, создаваемых Visual Studio. Например, файл ContactManager.Mvc.csproj в примере решения включает множество групп элементов, каждая из которых содержит несколько идентичных именованных элементов Item .
<ItemGroup>
<Reference Include="Microsoft.CSharp" />
<Reference Include="System.Runtime.Serialization" />
<Reference Include="System.ServiceModel" />
...
</ItemGroup>
<ItemGroup>
<Compile Include="Controllers\AccountController.cs" />
<Compile Include="Controllers\ContactsController.cs" />
<Compile Include="Controllers\HomeController.cs" />
...
</ItemGroup>
<ItemGroup>
<Content Include="Content\Custom.css" />
<Content Include="CreateDatabase.sql" />
<Content Include="DropDatabase.sql" />
...
</ItemGroup>
Таким образом, файл проекта предписывает MSBuild создавать списки файлов, которые необходимо обрабатывать аналогичным образом: список Ссылок содержит сборки, которые должны быть на месте для успешной сборки, список Компилировать содержит файлы кода, которые необходимо скомпилировать, а список Содержимое содержит ресурсы, которые должны быть скопированы без изменений. Мы рассмотрим, как процесс сборки ссылается на эти элементы и использует их далее в этом разделе.
Элементы Item также могут включать дочерние элементы ItemMetadata . Это определяемые пользователем пары "ключ-значение" и, по сути, представляют свойства, относящиеся к этому элементу. Например, многие элементы Compile в файле проекта содержат дочерние элементы DependentUpon .
<Compile Include="Global.asax.cs">
<DependentUpon>Global.asax</DependentUpon>
</Compile>
Примечание
Помимо метаданных элементов, созданных пользователем, всем элементам назначаются различные общие метаданные при создании. Дополнительные сведения см. в разделе Известные метаданные элемента.
Элементы ItemGroup можно создавать в корневом элементе Projectили в определенных целевых элементах. Элементы ItemGroup также поддерживают атрибуты Condition , что позволяет адаптировать входные данные для процесса сборки в соответствии с такими условиями, как конфигурация проекта или платформа.
Целевые объекты и задачи
В схеме MSBuild элемент Task представляет отдельную инструкцию сборки (или задачу). MSBuild включает множество предопределенных задач. Пример:
- Задача копирования копирует файлы в новое расположение.
- Задача Csc вызывает компилятор Visual C#.
- Задача Vbc вызывает компилятор Visual Basic.
- Задача Exec запускает указанную программу.
- Задача "Сообщение " записывает сообщение в средство ведения журнала.
Примечание
Полные сведения о задачах, доступных в готовых версиях, см. в справочнике по задачам MSBuild. Дополнительные сведения о задачах, в том числе о том, как создавать собственные пользовательские задачи, см. в разделе Задачи MSBuild.
Задачи всегда должны содержаться в целевых элементах. Элемент Target — это набор из одной или нескольких задач, которые выполняются последовательно, а файл проекта может содержать несколько целевых объектов. Если вы хотите выполнить задачу или набор задач, вызывается целевой объект, который их содержит. Например, предположим, что у вас есть простой файл проекта, который регистрирует сообщение в журнале.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Вы можете вызвать целевой объект из командной строки с помощью параметра /t , чтобы указать целевой объект.
msbuild.exe Publish.proj /t:LogMessage
Кроме того, можно добавить атрибут DefaultTargets в элемент Project , чтобы указать целевые объекты, которые требуется вызвать.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
DefaultTargets="FullPublish">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
В этом случае не нужно указывать целевой объект из командной строки. Можно просто указать файл проекта, и MSBuild вызовет целевой объект FullPublish .
msbuild.exe Publish.proj
Как целевые объекты, так и задачи могут включать атрибуты Condition . Таким образом, при соблюдении определенных условий можно опустить все целевые объекты или отдельные задачи.
Как правило, при создании полезных задач и целевых объектов необходимо ссылаться на свойства и элементы, определенные в другом месте файла проекта:
- Чтобы использовать значение свойства, введите $(PropertyName), где PropertyName — это имя элемента Property или имя параметра.
- Чтобы использовать элемент, введите @(ItemName), где ItemName — это имя элемента Item .
Примечание
Помните, что при создании нескольких элементов с одинаковым именем создается список. В отличие от этого, если создать несколько свойств с одинаковым именем, последнее указанное значение свойства перезапишет все предыдущие свойства с тем же именем— свойство может содержать только одно значение.
Например, в файле Publish.proj в примере решения взгляните на целевой объект BuildProjects .
<Target Name="BuildProjects" Condition=" '$(BuildingInTeamBuild)'!='true' ">
<MSBuild Projects="@(ProjectsToBuild)"
Properties="OutDir=$(OutputRoot);
Configuration=$(Configuration);
DeployOnBuild=true;
DeployTarget=Package"
Targets="Build" />
</Target>
В этом примере можно увидеть следующие ключевые моменты:
Если указан параметр BuildingInTeamBuild и имеет значение true, ни одна из задач в этом целевом объекте не будет выполнена.
Целевой объект содержит один экземпляр задачи MSBuild . Эта задача позволяет создавать другие проекты MSBuild.
Элемент ProjectsToBuild передается задаче. Этот элемент может представлять список файлов проекта или решения, которые определяются элементами элементов ProjectsToBuild в группе элементов. В этом случае элемент ProjectsToBuild ссылается на один файл решения.
<ItemGroup> <ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/> </ItemGroup>Значения свойств, передаваемые задаче MSBuild , включают параметры с именами OutputRoot и Configuration. Для них заданы значения параметров, если они указаны, или статические значения свойств, если они не заданы.
<PropertyGroup> ... <Configuration Condition=" '$(Configuration)'=='' ">Release </Configuration> <OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\ </OutputRoot> ... </PropertyGroup>
Вы также можете увидеть, что задача MSBuild вызывает целевой объект с именем Build. Это один из нескольких встроенных целевых объектов, которые широко используются в файлах проекта Visual Studio и доступны в файлах пользовательских проектов, таких как сборка, очистка, перестроение и публикация. Вы узнаете больше об использовании целевых объектов и задач для управления процессом сборки, а также о задаче MSBuild , в частности, далее в этом разделе.
Примечание
Дополнительные сведения о целевых объектах см. в разделе Целевые объекты MSBuild.
Разделение файлов проекта для поддержки нескольких сред
Предположим, вы хотите развернуть решение в нескольких средах, таких как тестовые серверы, промежуточные платформы и рабочие среды. Конфигурация может существенно отличаться в разных средах не только с точки зрения имен серверов, строк подключения и т. д., но и потенциально с точки зрения учетных данных, параметров безопасности и множества других факторов. Если вам нужно регулярно делать это, не рекомендуется изменять несколько свойств в файле проекта при каждом переключении целевой среды. Это также не является идеальным решением, чтобы требовать предоставления бесконечного списка значений свойств в процессе сборки.
К счастью, есть альтернатива. MSBuild позволяет разделить конфигурацию сборки на несколько файлов проекта. Чтобы увидеть, как это работает, в примере решения обратите внимание на то, что есть два пользовательских файла проекта:
- Publish.proj, содержащий свойства, элементы и целевые объекты, общие для всех сред.
- Env-Dev.proj, содержащий свойства, относящиеся к среде разработчика.
Теперь обратите внимание, что файл Publish.proj содержит элемент Import непосредственно под открывающим тегом Project .
<Import Project="$(TargetEnvPropsFile)"/>
Элемент Import используется для импорта содержимого другого файла проекта MSBuild в текущий файл проекта MSBuild. В этом случае параметр TargetEnvPropsFile предоставляет имя файла проекта, который требуется импортировать. Вы можете указать значение для этого параметра при запуске MSBuild.
msbuild.exe Publish.proj /p:TargetEnvPropsFile=EnvConfig\Env-Dev.proj
Это эффективно объединяет содержимое двух файлов в один файл проекта. Используя этот подход, можно создать один файл проекта, содержащий универсальную конфигурацию сборки, и несколько дополнительных файлов проекта, содержащих свойства среды. В результате простое выполнение команды с другим значением параметра позволяет развернуть решение в другой среде.
Рекомендуется разделить файлы проекта таким образом. Это позволяет разработчикам выполнять развертывание в нескольких средах, выполняя одну команду, избегая при этом дублирования универсальных свойств сборки в нескольких файлах проекта.
Примечание
Инструкции по настройке файлов проекта для конкретной среды для собственных серверных сред см. в разделе Настройка свойств развертывания для целевой среды.
Заключение
В этом разделе приводятся общие сведения о файлах проекта MSBuild и объясняется, как можно создавать собственные пользовательские файлы проекта для управления процессом сборки. В ней также представлена концепция разделения файлов проекта на универсальные инструкции сборки и свойства сборки, относящиеся к среде, чтобы упростить сборку и развертывание проектов в нескольких местах назначения.
В следующем разделе, "Основные сведения о процессе сборки", содержатся дополнительные сведения о том, как использовать файлы проекта для управления сборкой и развертыванием, повествуя о развертывании решения с реалистичным уровнем сложности.
Дополнительные материалы
Более подробные сведения о файлах проекта и WPP см. в статье Inside the Microsoft Build Engine: Using MSBuild and Team Foundation Build by Sayed Ibrahim Hashimi and William Bartholomew, ISBN: 978-0-7356-4524-0.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по