Набор инструментов MSBuild (ToolsVersion)

  • Статья

Набор инструментов MSBuild включает файл microsoft.common.tasks, файл microsoft.common.targets и компиляторы, такие как csc.exe и vbc.exe. Большинство наборов инструментов можно использовать для компиляции приложений в несколько версий платформа .NET Framework и более одной системной платформы. При этом набор инструментов MSBuild 2.0 можно использовать только для платформы .NET Framework 2.0.

Атрибут MSBuild в элементе Project в Visual Studio и файлах проектов MSBuild ToolsVersion считается устаревшим в Visual Studio 2019 и более поздних версиях. Его можно безопасно удалить. В этой статье описывается его использование в более ранних версиях MSBuild или для пользовательских наборов инструментов. См . стандартные и настраиваемые конфигурации набора инструментов.

Атрибут ToolsVersion

Укажите набор инструментов в атрибуте ToolsVersion элемента Проект в файле проекта. В приведенном ниже примере показано, что сборка проекта должна быть выполнена с помощью набора инструментов MSBuild 15.0 "Текущий".

<Project ToolsVersion="Current" ... </Project>

Примечание.

Некоторые типы проектов используют атрибут sdk вместо ToolsVersion. Дополнительные сведения см. в статье Дополнения к формату CSPROJ для .NET Core.

Принцип действия атрибута ToolsVersion

При создании проекта в Visual Studio или обновлении существующего проекта атрибут с именем ToolsVersion автоматически включается в файл проекта, а его значение соответствует версии MSBuild, включенной в выпуск Visual Studio. Дополнительные сведения см. в статье Общие сведения о настройке для платформы.

Если значение ToolsVersion определено в файле проекта, MSBuild использует это значение для определения значений свойств набора инструментов, доступных для проекта. Одно из свойств набора инструментов — это $(MSBuildToolsPath). Оно определяет путь к инструментам .NET Framework. Обязательным является только это свойство набора инструментов (или $(MSBuildBinPath)).

Начиная с Visual Studio 2013, версия набора инструментов MSBuild совпадает с номером версии Visual Studio. MSBuild по умолчанию соответствует этому набору инструментов в Visual Studio и в командной строке, независимо от версии набора инструментов, указанной в файле проекта. Это поведение можно изменить с помощью флага -ToolsVersion. Дополнительные сведения см. в статье Переопределение параметров ToolsVersion.

В следующем примере MSBuild находит файл Microsoft.CSharp.targets с помощью зарезервированного свойства MSBuildToolsPath.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Значение MSBuildToolsPath можно изменить, определив пользовательский набор инструментов. Дополнительные сведения см. в статье Стандартные и настраиваемые конфигурации наборов инструментов.

Если вы компилируете решение из командной строки и указываете значение атрибута ToolsVersion для msbuild.exe, все проекты и зависимости между проектами компилируются в соответствии с этим значением ToolsVersion, даже если в каждом проекте в решении указано собственное значение ToolsVersion. Сведения об определении значения ToolsVersion для каждого проекта см. в статье Переопределение параметров ToolsVersion.

Атрибут ToolsVersion также используется для миграции проектов. Например, если открыть проект Visual Studio 2008 в Visual Studio 2010, то файл проекта обновится и получит значение ToolsVersion = "4.0". Если после этого вы попытаетесь открыть этот проект в Visual Studio 2008, он не распознает обновленное значение атрибута ToolsVersion и построит проект таким образом, как если бы этот атрибут по-прежнему имел значение 3.5.

В Visual Studio 2010 и Visual Studio 2012 используется ToolsVersion 4.0. В Visual Studio 2013 используется ToolsVersion 12.0. Visual Studio 2015 использует ToolsVersion 14.0, а Visual Studio 2017 — ToolsVersion 15.0. Во многих случаях проект можно открыть в нескольких версиях Visual Studio без внесения изменений. В Visual Studio всегда используется правильный набор инструментов, но если версия не совпадает с версией в файле проекта, вы получите уведомление. Почти всегда это предупреждение носит информационный характер, так как наборы инструментов в большинстве случаев совместимы.

Поднаборы инструментов, описываемые ниже в этом разделе, позволяют MSBuild автоматически переключаться на набор инструментов в зависимости от контекста, в котором запущено построение. Например, при запуске в Visual Studio 2012 MSBuild использует более новый набор инструментов, чем при запуске в Visual Studio 2010, но при этом не требует изменений в файле проекта.

Реализация набора инструментов

Реализация набора инструментов осуществляется с помощью выбора путей к различным инструментам, целям и задачам, из которых состоит набор инструментов. Инструменты в наборе, которые определяет MSBuild, поступают из следующих источников:

  • из папки .NET Framework;

  • из дополнительных управляемых инструментов.

    В число управляемых инструментов входят ResGen.exe и TlbImp.exe.

MSBuild предлагает два способа доступа к набору инструментов:

  • с помощью свойств набора инструментов;

  • с помощью методов ToolLocationHelper.

Свойства набора инструментов указывают на пути к инструментам. Начиная с Visual Studio 2017, система MSBuild больше не имеет фиксированного расположения. По умолчанию она находится в папке MSBuild\15.0\Bin относительно папки установки Visual Studio. В более ранних версиях MSBuild определяет местоположение соответствующего раздела реестра в соответствии со значением атрибута ToolsVersion в файле проекта, а затем использует сведения из этого раздела для настройки свойств набора инструментов. Например, если атрибут ToolsVersion имеет значение 12.0, то MSBuild задает свойства набора инструментов в соответствии со следующим разделом реестра: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.

Свойства набора инструментов:

  • MSBuildToolsPath указывает путь к двоичным файлам MSBuild;

  • SDK40ToolsPath указывает путь к дополнительным управляемым инструментам для MSBuild 4.x (4.0 или 4.5);

  • SDK35ToolsPath указывает путь к дополнительным управляемым инструментам для MSBuild 3.5.

Вы также можете программно определить набор инструментов, вызвав методы класса ToolLocationHelper. Класс включает следующие методы:

Связанный контент