Conjunto de herramientas de MSBuild (ToolsVersion)

  • Artículo

Un conjunto de herramientas de MSBuild incluye un archivo microsoft.common.tasks, un archivo microsoft.common.targets y compiladores como csc.exe y vbc.exe. La mayoría de los conjuntos de herramientas se pueden usar para compilar aplicaciones correspondientes a más de una versión de .NET Framework y a más de una plataforma de sistema. Sin embargo, el conjunto de herramientas de MSBuild 2.0 solo se puede usar para las aplicaciones de .NET Framework 2.0.

El atributo ToolsVersion de MSBuild en el elemento Project de Visual Studio y los archivos de proyecto de MSBuild se considera obsoleto en Visual Studio 2019 y versiones posteriores; puede eliminarlo de forma segura. En este artículo se describe su uso en versiones anteriores de MSBuild o en conjuntos de herramientas personalizados. Vea Configuraciones de conjuntos de herramientas estándar y personalizados.

Atributo ToolsVersion

El conjunto de herramientas se especifica en el atributo ToolsVersion del elemento Project del archivo de proyecto. En el ejemplo siguiente, se especifica que el proyecto debe compilarse usando el conjunto de herramientas de MSBuild "Current".

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

Nota

En algunos tipos de proyecto se usa el atributo sdk en lugar de ToolsVersion. Para más información, vea Adiciones al formato csproj para .NET Core.

Cómo funciona el atributo ToolsVersion

Al crear un nuevo proyecto en Visual Studio, o actualizar uno ya existente, se incluye automáticamente un atributo denominado ToolsVersion en el archivo de proyecto y su valor corresponde a la versión de MSBuild incluida en la edición de Visual Studio. Para obtener más información, vea Información general sobre destinos de Framework.

Cuando se define un valor ToolsVersion en un archivo de proyecto, MSBuild usa ese valor para determinar los valores de las propiedades del conjunto de herramientas que están disponibles para el proyecto. Una propiedad del conjunto de herramientas es $(MSBuildToolsPath), que especifica la ruta de acceso de las herramientas de .NET Framework. Solo se requiere esa propiedad (o $(MSBuildBinPath)) del conjunto de herramientas.

A partir de Visual Studio 2013, la versión del conjunto de herramientas MSBuild es la misma que el número de versión de Visual Studio. De forma predeterminada, MSBuild usa este conjunto de herramientas en Visual Studio y en la línea de comandos, independientemente de la versión del conjunto de herramientas especificada en el archivo de proyecto. Este comportamiento puede invalidarse usando la marca -ToolsVersion. Para más información, consulte Invalidar la configuración de ToolsVersion.

En el ejemplo siguiente, MSBuild busca el archivo Microsoft.CSharp.targets usando la propiedad reservada MSBuildToolsPath.

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

Puede modificar el valor de MSBuildToolsPath definiendo un conjunto de herramientas personalizado. Para más información, consulte Configuraciones de conjuntos de herramientas estándar y personalizados.

Al crear una solución en la línea de comandos y especifique un ToolsVersion para msbuild.exe, todos los proyectos y sus dependencias proyecto a proyecto se crean según la que ToolsVersion, aunque cada proyecto de la solución Especifique su propia ToolsVersion. Para definir el valor ToolsVersion según el proyecto, consulte Invalidar la configuración de ToolsVersion.

El atributo ToolsVersion también se usa para la migración del proyecto. Por ejemplo, si abre un proyecto de Visual Studio 2008 en Visual Studio 2010, el archivo de proyecto se actualiza para incluir ToolsVersion="4.0". Si después intenta abrir ese proyecto en Visual Studio 2008, este no reconocerá el atributo ToolsVersion actualizado y compilará el proyecto como si dicho atributo todavía estuviese establecido en 3.5.

Visual Studio 2010 y Visual Studio 2012 usan ToolsVersion 4.0. Visual Studio 2013 usa ToolsVersion 12.0. Visual Studio 2015 usa ToolsVersion 14.0, y Visual Studio 2017 usa ToolsVersion 15.0. En muchos casos, puede abrir el proyecto en varias versiones de Visual Studio sin modificaciones. Visual Studio siempre usa el conjunto de herramientas correcto, pero se te notificará si la versión usada no coincide con la versión del archivo de proyecto. En casi todos los casos, esta advertencia es inofensiva porque los conjuntos de herramientas son compatibles en la mayoría de los casos.

Los subconjuntos de herramientas, que se describen más adelante en este tema, permiten que MSBuild cambie automáticamente a las herramientas que se van a usar en función del contexto en el que se ejecuta la compilación. Por ejemplo, MSBuild usa un conjunto de herramientas más reciente cuando se ejecuta en Visual Studio 2012 que cuando se ejecuta en Visual Studio 2010, sin necesidad de cambiar explícitamente el archivo de proyecto.

Implementación del conjunto de herramientas

Para implementar un conjunto de herramientas, seleccione las rutas de acceso de las distintas herramientas, destinos y tareas que constituyen dicho conjunto. Las herramientas del conjunto de herramientas que define MSBuild proceden de los orígenes siguientes:

  • La carpeta de .NET Framework.

  • Herramientas administradas adicionales.

    Entre las herramientas administradas se incluyen ResGen.exe y TlbImp.exe.

MSBuild proporciona dos maneras de tener acceso al conjunto de herramientas:

  • Mediante las propiedades del conjunto de herramientas

  • Mediante los métodos de la clase ToolLocationHelper

Las propiedades del conjunto de herramientas especifican las rutas de acceso de las herramientas. A partir de Visual Studio 2017, MSBuild deja de tener una ubicación fija. Se encuentra de forma predeterminada en la carpeta MSBuild\15.0\Bin correspondiente a la ubicación de instalación de Visual Studio. En versiones anteriores, MSBuild usa el valor del atributo ToolsVersion del archivo de proyecto para encontrar la clave del Registro correspondiente y, después, usa la información de dicha clave para establecer las propiedades del conjunto de herramientas. Por ejemplo, si ToolsVersion tiene el valor 12.0, MSBuild establece las propiedades del conjunto de herramientas conforme a esta clave del Registro: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.

Estas son las propiedades del conjunto de herramientas:

  • MSBuildToolsPath especifica la ruta de acceso de los archivos binarios de MSBuild.

  • SDK40ToolsPath especifica la ruta de acceso de las herramientas administradas adicionales para MSBuild 4.x (que podría ser 4.0 o 4.5).

  • SDK35ToolsPath especifica la ruta de acceso de las herramientas administradas adicionales para MSBuild 3,5.

Como alternativa, puede determinar el conjunto de herramientas mediante programación llamando a los métodos de la clase ToolLocationHelper. La clase contiene estos métodos:

Contenido relacionado