Compartilhar via

MSBuild Toolset (ToolsVersion)

  • Artigo

O MSBuild usa um conjunto de ferramentas de tarefas, metas e ferramentas para compilar um aplicativo. Normalmente, um conjunto de ferramentas do MSBuild inclui um arquivo microsoft.common.tasks, um arquivo microsoft.common.targets e compiladores como o csc.exe e o vbc.exe. A maioria dos conjuntos de ferramentas pode ser usada para compilar aplicativos para mais de uma versão do .NET Framework e mais de uma plataforma de sistema. No entanto, o conjunto de ferramentas do MSBuild 2.0 pode ser usado para visar apenas o NET Framework 2.0.

Atributo ToolsVersion

Especifique o conjunto de ferramentas no atributo ToolsVersion no elemento Projeto no arquivo do projeto. O exemplo a seguir especifica que o projeto deve ser compilado usando o conjunto de ferramentas do MSBuild 12.0.

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

Como funciona o atributo ToolsVersion

Quando você cria um projeto no Visual Studio, ou atualiza um projeto existente, um atributo chamado ToolsVersion é automaticamente incluído no arquivo de projeto e seu valor corresponde à versão do MSBuild incluída na edição do Visual Studio. Para obter mais informações, consulte Destinando uma versão do .NET Framework específica ou perfil.

Quando um valor ToolsVersion é definido em um arquivo do projeto, o MSBuild usa esse valor para determinar os valores das propriedades do conjunto de ferramentas que estão disponíveis para o projeto. Uma propriedade do conjunto de ferramentas é $(MSBuildToolsPath), que especifica o caminho das ferramentas do .NET Framework. Só essa propriedade do conjunto de ferramentas (ou o $(MSBuildBinPath)) é necessária.

A partir do Visual Studio 2013, a versão do conjunto de ferramentas do MSBuild é a mesma que o número de versão do Visual Studio. O MSBuild assume o padrão deste conjunto de ferramentas no Visual Studio e na linha de comando, independentemente da versão do conjunto de ferramentas especificada no arquivo de projeto. Esse comportamento pode ser substituído usando o sinalizador /ToolsVersion. Para obter mais informações, consulte Substituindo as configurações de ToolsVersion.

No exemplo a seguir, o MSBuild encontra o arquivo Microsoft.CSharp.targets usando a propriedade reservada MSBuildToolsPath.

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

É possível modificar o valor do MSBuildToolsPath ao definir um conjunto de ferramentas personalizado. Para obter mais informações, consulte Configurações padrão e personalizadas do Toolset

Quando você compila uma solução na linha de comando e especifica ToolsVersion para msbuild.exe, todos os projetos e suas dependências projeto a projeto são compilados de acordo com o ToolsVersion, mesmo que cada projeto na solução especifique seu próprio ToolsVersion. Para definir um valor de ToolsVersion por projeto, consulte Substituindo as configurações de ToolsVersion.

O atributo ToolsVersion também é usado para migração de projeto. Por exemplo, se você abrir um projeto do Visual Studio 2008 no Visual Studio 2010, o arquivo do projeto será atualizado para incluir TToolsVersion=”4.0”. Se você tentar abrir o projeto no Visual Studio 2008, ele não reconhecerá o ToolsVersion atualizado e, consequentemente, compilará o projeto como se o atributo ainda estivesse definido para 3.5.

Tanto o Visual Studio 2010 quanto o Visual Studio 2012 usam o ToolsVersion 4.0. O Visual Studio 2013 usa um ToolsVersion 12.0. Em muitos casos, você pode abrir o projeto em todas as três versões do Visual Studio sem modificação. O Visual Studio sempre usa o conjunto de ferramentas correto, mas você será notificado se a versão usada não corresponder à versão encontrada no arquivo de projeto. Em quase todos os casos esse aviso é benigno, já que os conjuntos de ferramentas são compatíveis na maioria dos casos.

Os subconjuntos de ferramentas, descritos mais adiante neste tópico, permitem que o MSBuild alterne automaticamente o conjunto de ferramentas para ser usado com base no contexto em que a compilação está sendo executada. Por exemplo, o MSBuild usa um conjunto mais recente de ferramentas quando é executado no Visual Studio 2012 do que quando é executado no Visual Studio 2010, sem que seja necessário alterar explicitamente o arquivo do projeto. Para obter mais informações, consulte Como: modificar um sistema de projeto para que a carga de projetos em várias versões do Visual Studio.

Implementação do conjunto de ferramentas

Implemente um conjunto de ferramentas selecionando os caminhos das várias ferramentas, destinos e tarefas que compõem o conjunto de ferramentas. As ferramentas do conjunto de ferramentas que o MSBuild define são fornecidas das seguintes fontes:

  • A pasta do .NET Framework.

  • Ferramentas gerenciadas adicionais.

As ferramentas gerenciadas incluem ResGen.exe e TlbImp.exe.

O MSBuild fornece duas maneiras de acessar o conjunto de ferramentas:

As propriedades do conjunto de ferramentas especificam os caminhos das ferramentas. O MSBuild usa o valor do atributo ToolsVersion no arquivo do projeto para localizar a chave do registro correspondente e usa as informações na chave do registro para definir as propriedades do conjunto de ferramentas. Por exemplo, se ToolsVersion tiver um valor 12.0, o MSBuild configurará as propriedades do conjunto de ferramentas de acordo com esta chave do registro: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.

Estas são as propriedades do conjunto de ferramentas:

  • MSBuildToolsPath especifica o caminho dos binários do MSBuild.

  • SDK40ToolsPath especifica o caminho de ferramentas gerenciadas adicionais para o MSBuild 4.x (que pode ser 4.0 ou 4.5).

  • SDK35ToolsPath especifica o caminho de ferramentas gerenciadas adicionais para o MSBuild 3.5.

Você também pode determinar o conjunto de ferramentas programaticamente, chamando os métodos da classe ToolLocationHelper. A classe inclui os seguintes métodos:

Subconjunto de ferramentas

Conforme descrito anteriormente neste tópico, o MSBuild usa uma chave de registro para especificar o caminho das ferramentas básicas. Se a chave tiver uma subchave, o MSBuild a usará para especificar o caminho de um subconjunto de ferramentas que contém ferramentas adicionais. Nesse caso, o conjunto de ferramentas é definido pela combinação das definições de propriedades definidas nas duas chaves.

Dica

Se os nomes de propriedade do conjunto de ferramentas coincidirem, o valor que está definido para o caminho da subchave substituirá o valor que está definido para o caminho da chave raiz.

Os subconjuntos de ferramentas tornam-se ativos na presença da propriedade de compilação VisualStudioVersion. Essa propriedade pode usar um dos seguintes valores:

  • “10.0” especifica o subconjunto de ferramentas do .NET Framework 4

  • “11.0” especifica o subconjunto de ferramentas do .NET Framework 4.5

  • “12.0” especifica o subconjunto de ferramentas do .NET Framework 4.5.1

Os subconjuntos de ferramentas 10.0 e 11.0 devem ser usados com o ToolsVersion 4.0. Em versões posteriores, a versão do subconjunto de ferramentas e o ToolsVersion devem corresponder.

Durante uma compilação, o MSBuild determina e define um valor padrão para a propriedade VisualStudioVersion se ele ainda não estiver definido.

O MSBuild fornece sobrecargas para os métodos ToolLocationHelper que adicionam um valor enumerado VisualStudioVersion como parâmetro

Os subconjuntos de ferramentas foram introduzidos no .NET Framework 4.5.

Consulte também

Conceitos

Configurações padrão e personalizadas do Toolset

Outros recursos

Visão geral da multiplataforma no MSBuild