Общие сведения о файле проекта

Джейсон Ли

Файлы проекта 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 автоматически.

Соглашения об именовании файлов проекта

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

• Используйте расширение .proj при создании файла проекта, который создает проекты.
• Используйте расширение .targets при создании повторно используемого файла проекта для импорта в другие файлы проекта. Файлы с расширением .targets обычно не создают ничего самостоятельно, они просто содержат инструкции, которые можно импортировать в proj-файлы.

Интеграция с технологиями развертывания

Если вы работали с проектами веб-приложений в Visual Studio 2010, например ASP.NET веб-приложениями и ASP.NET веб-приложениями MVC, вы узнаете, что эти проекты включают встроенную поддержку упаковки и развертывания веб-приложения в целевой среде. Страницы свойств для этих проектов включают вкладки Package/Publish Web and Package/Publish SQL , которые можно использовать для настройки того, как компоненты приложения упаковываются и развертываются. На этой вкладке показана вкладка "Пакет и публикация веб-сайта ":

Базовая технология, лежащая в основе этих возможностей, называется конвейером веб-публикации (WPP). WPP по сути объединяет MSBuild и веб-развертывание , чтобы обеспечить полный процесс сборки, пакета и развертывания для веб-приложений.

Хорошая новость заключается в том, что вы можете воспользоваться преимуществами точек интеграции, которые WPP предоставляет при создании пользовательских файлов проектов для веб-проектов. Инструкции по развертыванию можно включить в файл проекта, который позволяет создавать проекты, создавать пакеты веб-развертывания и устанавливать эти пакеты на удаленных серверах с помощью одного файла проекта и одного вызова MSBuild. Вы также можете вызвать любые другие исполняемые файлы в рамках процесса сборки. Например, можно запустить средство командной строки VSDBCMD.exe для развертывания базы данных из файла схемы. В рамках этого раздела вы узнаете, как воспользоваться преимуществами этих возможностей для удовлетворения требований сценариев корпоративного развертывания.

Анатомия файла проекта

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

• Как использовать свойства для управления переменными для процесса сборки.
• Как использовать элементы для идентификации входных данных процесса сборки, таких как файлы кода.
• Использование целевых объектов и задач для предоставления инструкций по выполнению MSBuild с помощью свойств и элементов, определенных в другом месте файла проекта.

Это показывает связь между ключевыми элементами в файле проекта MSBuild:

Элемент проекта

Элемент 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

Вы можете использовать тот же синтаксис свойств для получения значений переменных среды и встроенных свойств проекта. Для вас определены множество часто используемых свойств, и их можно использовать в файлах проекта, включив соответствующее имя параметра. Например, чтобы получить текущую платформу проекта (например, 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 в примере решения содержит множество групп элементов, каждый из которых имеет несколько идентичных именованных элементов.

<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 создавать списки файлов, которые должны обрабатываться таким же образом. Список ссылок включает сборки, которые должны быть на месте для успешной сборки, список компиляции включает файлы кода, которые должны быть скомпилированы, а список содержимого включает ресурсы, которые должны быть скопированы без изменений. Мы рассмотрим, как процесс сборки ссылается на эти элементы и использует их в дальнейшем в этом разделе.

Элементы могут также включать дочерние элементы ItemMetadata. Это пары "ключ-значение", определяемые пользователем, и, по сути, представляют свойства, относящиеся к этому элементу. Например, многие элементы Compile в файле проекта, включают дочерние элементы DependentUpon.

<Compile Include="Global.asax.cs">
   <DependentUpon>Global.asax</DependentUpon>
</Compile>

Элементы ItemGroup можно создать в элементе Project корневого уровня или в определенных элементах Target . Элементы ItemGroup также поддерживают атрибуты условия, которые позволяют настраивать входные данные в процессе сборки в соответствии с условиями, такими как конфигурация проекта или платформа.

Целевые объекты и задачи

В схеме MSBuild элемент Task представляет отдельную инструкцию сборки (или задачу). MSBuild включает множество предопределенных задач. Рассмотрим пример.

• Задача Copy копирует файлы в новое место.
• Задача Csc вызывает компилятор Visual C#.
• Задача Vbc вызывает компилятор Visual Basic.
• Задача Exec выполняет указанную программу.
• Задача "Сообщение" записывает сообщение в средство ведения журнала.

Задачи всегда должны содержаться в элементах Target . Элемент 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

Как целевые объекты, так и задачи могут включать атрибуты условия . Таким образом, можно исключить все целевые объекты или отдельные задачи, если выполнены определенные условия.

Как правило, при создании полезных задач и целевых объектов необходимо ссылаться на свойства и элементы, определенные в другом месте файла проекта:

• Чтобы использовать значение свойства, введите $(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 позволяет разделить конфигурацию сборки по нескольким файлам проекта. Чтобы узнать, как это работает, в примере решения обратите внимание, что существует два пользовательских файла проекта:

• 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

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

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

Conclusion

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

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

Дальнейшее чтение

Более полное введение в файлы проектов и WPP смотрите в книге "Внутри ядра сборки Microsoft: использование MSBuild и Team Foundation Build", авторы Сайед Ибрагим Хашими и Уильям Бартоломью, ISBN: 978-0-7356-4524-0.