Tutorial: Usar o MSBuild

MSBuild é a plataforma de compilação para Microsoft e Visual Studio que é usada para criar a maioria dos projetos do Visual Studio, incluindo projetos .NET e C++. Este tutorial apresenta os blocos de construção do MSBuild e mostra como escrever, manipular e depurar projetos do MSBuild. Você aprende sobre:

• Criação e manipulação de um arquivo de projeto.

• Como usar as propriedades de compilação.

• Como usar itens de compilação.

Você pode executar o MSBuild do Visual Studio ou da janela de comando executando MSBuild.exe. Há muitas razões pelas quais você pode querer executar o MSBuild a partir da janela de comando, como se você deseja criar em uma máquina que não tem o Visual Studio instalado ou se deseja usar argumentos de linha de comando específicos que você não pode definir no IDE do Visual Studio. Por exemplo, executando a partir da linha de comando, você pode definir determinadas propriedades do MSBuild, gerar um log binário para depurar um problema de compilação ou executar um subconjunto da compilação, como executar explicitamente um destino de compilação específico em vez da compilação completa. Consulte Referência de linha de comando do MSBuild. Você também pode usar MSBuild.exe para criar em máquinas que não têm o Visual Studio completo instalado, como em um servidor de compilação ou fazendo logon em um contêiner em um pipeline.

Neste tutorial, você cria um arquivo de projeto MSBuild usando o Visual Studio. Editar o arquivo de projeto no Visual Studio e usar o janela de comando para criar o projeto e examinar os resultados.

Instalar o MSBuild

Se você tiver o Visual Studio, então você já tem o MSBuild instalado. Ele é instalado na pasta de instalação do Visual Studio. Para uma instalação padrão típica no Windows, MSBuild.exe está na pasta de instalação em MSBuild\Current\Bin.

Para instalar o MSBuild em um sistema que não tem o Visual Studio, vá para Ferramentas para Visual Studio>Ferramentas de compilação para Visual Studio na página de downloads. Outra maneira de obter o MSBuild é instalar o SDK do .NET.

Criar um projeto MSBuild

O sistema de projeto do Visual Studio é baseado em MSBuild. É fácil criar um novo arquivo de projeto usando o Visual Studio. Nesta seção, você cria um arquivo de projeto C#. Você pode optar por criar um arquivo de projeto do Visual Basic em vez disso. No contexto deste tutorial, a diferença entre os dois arquivos de projeto é menor. Os tipos de projeto C++ usam uma infraestrutura de compilação diferente da descrita aqui. Para projetos C++, consulte Usar MSBuild para criar um projeto C++.

Para criar um arquivo de projeto

1. Abra o Visual Studio e crie um projeto:

   Na caixa de pesquisa, digite winformse, em seguida, escolha Criar um novo aplicativo Windows Forms (.NET Framework). Na caixa de diálogo exibida, escolha Criar.

   Na caixa nome do projeto, escreva BuildApp. Insira um de localização para a solução, por exemplo, D:\.

2. Clique OK ou Criar para criar o arquivo de projeto.

Examinar o arquivo de projeto

Na seção anterior, você usou o Visual Studio para criar um arquivo de projeto C#. O arquivo de projeto é representado em Gerenciador de Soluções pelo nó do projeto chamado BuildApp. Você pode usar o editor de código do Visual Studio para examinar o arquivo de projeto.

Para examinar o arquivo de projeto

1. No Explorador de Soluções , clique no nó do projeto BuildApp.

2. No Propriedades navegador, observe que a propriedade Project File é BuildApp.csproj. Todos os arquivos de projeto são nomeados com o sufixo proj. Se você tivesse criado um projeto Visual Basic, o nome do arquivo de projeto seria BuildApp.vbproj.

3. Clique com o botão direito do mouse no nó do projeto novamente e, em seguida, clique em Editar BuildApp.csproj.

   O arquivo de projeto aparece no editor de código.

Observação

Para alguns tipos de projeto, como C++, você precisa descarregar o projeto (clique com o botão direito do mouse no arquivo de projeto e escolha Descarregar projeto) antes de abrir e editar o arquivo de projeto.

Adicionar um destino e uma tarefa

Nesta seção, você adiciona um destino ao arquivo de projeto, que grava uma mensagem na saída da compilação. A próxima seção fornece uma breve visão geral de destinos e tarefas em arquivos de projeto do MSBuild.

Objetivos e tarefas

Os arquivos de projeto são arquivos XML com o nó raiz Project.

A maioria dos projetos .NET tem um atributo Sdk. Esses projetos são chamados de projetos no estilo SDK. Fazer referência a um SDK significa que o MSBuild importa um conjunto de arquivos que fornecem a infraestrutura de compilação para esse SDK. Se você não fizer referência a nenhum SDK, ainda poderá usar o MSBuild, simplesmente não terá automaticamente todas as propriedades e destinos específicos do SDK disponíveis para você.

<Project Sdk="Microsoft.NET.Sdk">

Há muitas variações de SDKs .NET para fins especiais; eles são descritos em SDKs do Projeto .NET.

O trabalho de criação de um aplicativo é feito com os elementos Target e Task.

• Uma tarefa é a menor unidade de trabalho, em outras palavras, o "átomo" de uma construção. As tarefas são componentes executáveis independentes, que podem ter entradas e saídas. Não há tarefas atualmente referenciadas ou definidas no arquivo de projeto. Você adiciona tarefas ao arquivo de projeto nas seções a seguir. Para obter mais informações, consulte Tarefas.

• Um destino encapsula instruções de compilação, normalmente para alguns artefatos de saída, como um arquivo ou conjunto de arquivos, dadas determinadas entradas. Normalmente é composto por uma sequência de tarefas, mas criticamente, representa algo a ser construído ou feito, por isso deve ser definido de forma orientada a objetivos. Para obter mais informações, consulte Targets.

O destino padrão não está definido no arquivo de projeto. Em vez disso, isso é especificado em projetos importados. O elemento Import especifica projetos importados. Por exemplo, em um projeto C#, o destino padrão é importado do arquivo Microsoft.CSharp.targets.

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

Os arquivos importados são efetivamente inseridos no arquivo de projeto onde quer que sejam referenciados.

Em projetos no estilo SDK, você não vê esse elemento import, pois o atributo SDK faz com que esse arquivo seja importado implicitamente.

O MSBuild controla os destinos de uma compilação e garante que cada destino não seja criado mais de uma vez.

Adicione um destino ao arquivo de projeto. Adicione uma tarefa ao destino que imprime uma mensagem.

Para adicionar um destino e uma tarefa

1. Adicione essas linhas ao arquivo de projeto, logo após a instrução Import ou o elemento Project de abertura.

   <Target Name="HelloWorld">
   </Target>
   

   Esse código cria um destino chamado HelloWorld. Observe que você tem suporte ao IntelliSense ao editar o arquivo de projeto.

2. Adicione linhas ao destino HelloWorld, para que a seção resultante tenha esta aparência:

   <Target Name="HelloWorld">
     <Message Text="Hello"></Message>
     <Message Text="World"></Message>
   </Target>
   

3. Salve o arquivo de projeto.

A tarefa Message é uma das muitas tarefas que acompanha o MSBuild. Para obter uma lista completa de tarefas disponíveis e informações de utilização, consulte a referência de tarefas em .

A tarefa Message usa o valor da cadeia de caracteres do atributo Text como entrada e o exibe no dispositivo de saída (ou o grava em um ou mais logs, se aplicável). O destino HelloWorld executa a tarefa Mensagem duas vezes: primeiro para exibir "Olá" e, em seguida, para exibir "Mundo".

Construa o alvo

Se tentar compilar este projeto no Visual Studio, ele não compila o alvo que definiu. Isso ocorre porque o Visual Studio escolhe o destino padrão, que ainda é aquele no arquivo de .targets importado. Para criar seu destino no Visual Studio, você pode encadeá-lo a um dos destinos padrão usando determinados atributos no Target elemento , como AfterTargets ou BeforeTargets. Veja como fazer com que seu destino HelloWorld seja executado após o destino padrão Build :

<Target Name="HelloWorld" AfterTargets="Build">
    <Message Text="Hello"></Message>
    <Message Text="World"></Message>
</Target>

Execute a compilação novamente no Visual Studio e procure na guia Build da janela Saída para ver as mensagens Hello World.

Você também pode especificar destinos desejados executando o MSBuild a partir da linha de comando. Nesta seção, você executará o MSBuild a partir do prompt de comando do desenvolvedor para Visual Studio para criar o destino HelloWorld. Use a opção de linha de comando -target ou -t para selecionar o destino.

Observação

Vamos referir-nos ao Prompt de Comando do Desenvolvedor como a Janela de Comando nas seções a seguir.

Para construir o objetivo:

1. Se você o adicionou, exclua o AfterTargets atributo e salve o arquivo de projeto.

2. Abra a janela de comando .

   Na caixa de pesquisa na barra de tarefas, comece a digitar o nome da ferramenta, como dev ou developer command prompt. É apresentada uma lista de aplicações instaladas que correspondem ao seu padrão de pesquisa.

   Se você precisar encontrá-lo manualmente, o arquivo será LaunchDevCmd.bat na pasta {Visual Studio installation folder}\Common7\Tools.

3. Na janela de comando, navegue até a pasta que contém o arquivo de projeto, neste caso, D:\BuildApp\BuildApp.

4. Execute msbuild com a opção de comando -t:HelloWorld. Este comando seleciona e cria o destino HelloWorld:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examine o resultado na janela de comandos . Você deve ver as duas linhas "Olá" e "Mundo":

   Hello
   World
   

Alternando entre o editor de código e a janela de comando, você pode alterar o arquivo de projeto e ver rapidamente os resultados.

Construir propriedades

As propriedades de compilação são pares nome-valor que guiam a compilação. Várias propriedades de compilação já estão definidas na parte superior do arquivo de projeto:

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Todas as propriedades são elementos filhos dos elementos PropertyGroup. O nome da propriedade é o nome do elemento filho e o valor da propriedade é o elemento de texto do elemento filho. Por exemplo

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

define a propriedade denominada TargetFrameworkVersion, dando-lhe o valor string "net8.0"

As propriedades de compilação podem ser redefinidas a qualquer momento. Se o

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

aparece mais tarde no arquivo de projeto, ou em um arquivo importado posteriormente no arquivo de projeto, em seguida TargetFrameworkVersion , leva o novo valor "net8.0"

Examinar um valor de propriedade

Para obter o valor de uma propriedade, use a seguinte sintaxe, onde PropertyName é o nome da propriedade:

$(PropertyName)

Use esta sintaxe para examinar algumas das propriedades no arquivo de projeto.

Para examinar um valor de propriedade

1. No editor de código, substitua o destino HelloWorld por este código:

   <Target Name="HelloWorld">
     <Message Text="Configuration is $(Configuration)" />
     <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
   </Target>
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver estas duas linhas (sua saída pode ser diferente):

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\18\MSBuild\Current\Bin\amd64
   

Propriedades condicionais

Muitas propriedades como Configuration são definidas condicionalmente, ou seja, o atributo Condition aparece no elemento property. As propriedades condicionais são definidas ou redefinidas somente se a condição for avaliada como "true". As propriedades indefinidas recebem o valor padrão de uma cadeia de caracteres vazia. Por exemplo

<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

significa "Se a propriedade Configuration ainda não tiver sido definida, defina a e atribua-lhe o valor 'Debug'."

Quase todos os elementos do MSBuild podem ter um atributo Condition. Para obter mais discussões sobre como usar o atributo Condition, consulte Conditions.

Propriedades reservadas

MSBuild reserva alguns nomes de propriedade para armazenar informações sobre o arquivo de projeto e os binários MSBuild. MSBuildToolsPath é um exemplo de uma propriedade reservada. As propriedades reservadas são referenciadas com a notação $ como qualquer outra propriedade. Para obter mais informações, consulte Como fazer referência ao nome ou local do arquivo de projeto e propriedades reservadas e conhecidas do MSBuild.

Variáveis de ambiente

Você pode fazer referência a variáveis de ambiente em arquivos de projeto da mesma maneira que as propriedades de compilação. Por exemplo, para usar a variável de ambiente PATH em seu arquivo de projeto, use $(Path). Se o projeto contém uma definição de propriedade que tem o mesmo nome de uma variável de ambiente, a propriedade no projeto substitui o valor da variável de ambiente. Para obter mais informações, consulte Como usar variáveis de ambiente em uma compilação.

Definir propriedades a partir da linha de comando

As propriedades podem ser definidas na linha de comando usando a opção de linha de comando -property ou -p. Os valores de propriedade recebidos da linha de comando substituem os valores de propriedade definidos no arquivo de projeto e nas variáveis de ambiente.

Para definir um valor de propriedade a partir da linha de comando:

1. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld -p:Configuration=Release
   

2. Examina a saída. Você deve ver esta linha:

   Configuration is Release.
   

O MSBuild cria a propriedade Configuration e atribui-lhe o valor "Release".

Caracteres especiais

Certos caracteres têm um significado especial em arquivos de projeto MSBuild. Exemplos desses caracteres incluem ponto-e-vírgula (;) e asteriscos (*). Para usar esses caracteres especiais como literais em um arquivo de projeto, eles devem ser especificados usando a sintaxe %<xx>, onde <xx> representa o valor hexadecimal ASCII do caractere.

Alterar a tarefa "Message" para mostrar o valor da propriedade "Configuration" com caracteres especiais para torná-la mais compreensível.

Para usar caracteres especiais na tarefa Mensagem:

1. No editor de código, substitua ambas as tarefas de mensagem por esta linha:

   <Message Text="%24(Configuration) is %22$(Configuration)%22" />
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver esta linha:

   $(Configuration) is "Debug"
   

Para obter mais informações, consulte caracteres especiais do MSBuild.

Itens de construção

Um item é uma informação, normalmente um nome de arquivo, que é usado como uma entrada para o sistema de compilação. Por exemplo, uma coleção de itens que representam ficheiros de origem pode ser passada para uma tarefa chamada Compilar para compilá-los em uma assemblagem.

Todos os itens são elementos filho de elementos ItemGroup. O nome do item é o nome do elemento filho e o valor do item é o valor do atributo Include do elemento filho. Os valores de itens com o mesmo nome são coletados em tipos de item desse nome. Por exemplo

<ItemGroup>
    <Compile Include="Program.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

Define um grupo de itens contendo dois itens. O tipo de item Compile tem dois valores: Program.cs e Properties\AssemblyInfo.cs.

O código a seguir cria o mesmo tipo de item declarando ambos os arquivos em um atributo Include, separados por ponto-e-vírgula.

<ItemGroup>
    <Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>

Para obter mais informações, consulte Itens.

Observação

Os caminhos de arquivo são relativos à pasta que contém o arquivo de projeto MSBuild, mesmo se o arquivo de projeto for um arquivo de projeto importado. Existem algumas exceções a isto, como quando se utilizam os elementos Import e UsingTask.

Examinar os valores dos tipos de item

Para obter os valores de um tipo de item, use a seguinte sintaxe, onde ItemType é o nome do tipo de item:

@(ItemType)

Use esta sintaxe para examinar o tipo de item Compile no arquivo de projeto.

Para examinar valores de tipo de item:

1. No editor de código, substitua a tarefa de destino HelloWorld por este código:

   <Target Name="HelloWorld">
     <Message Text="Compile item type contains @(Compile)" />
   </Target>
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver esta longa fila:

   Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
   

Os valores de um tipo de item são separados por ponto-e-vírgula por padrão.

Para alterar o separador de um tipo de item, use a sintaxe a seguir, onde ItemType é o tipo de item e Separator é uma cadeia de caracteres de um ou mais caracteres de separação:

@(ItemType, Separator)

Altere a tarefa Message para usar retornos de carro e avanços de linha (%0A%0D) para exibir os itens de Compilação um por linha.

Para exibir valores de tipo de item um por linha

1. No editor de códigos, substitua a tarefa Mensagem por esta linha:

   <Message Text="Compile item type contains @(Compile, '%0A%0D')" />
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver estas linhas:

   Compile item type contains Form1.cs
   Form1.Designer.cs
   Program.cs
   Properties\AssemblyInfo.cs
   Properties\Resources.Designer.cs
   Properties\Settings.Designer.cs
   

Incluir, Excluir e curingas

Você pode usar os curingas "*", "**" e "?" com o atributo Include para adicionar itens a um tipo de item. Por exemplo

<Photos Include="images\*.jpeg" />

adiciona todos os arquivos com a extensão de arquivo .jpeg na pasta imagens ao tipo de item Fotos, enquanto

<Photos Include="images\**\*.jpeg" />

adiciona todos os arquivos com a extensão de arquivo .jpeg na pasta imagens e todas as suas subpastas ao tipo de item Fotos. Para obter mais exemplos, consulte Como: Selecionar os arquivos para criar.

Observe que, à medida que os itens são declarados, eles são adicionados ao tipo de item. Por exemplo

<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />

cria um tipo de item chamado Photo que contém todos os arquivos na pasta imagens com uma extensão de arquivo .jpeg ou .gif. Essas linhas são equivalentes à seguinte linha:

<Photos Include="images\*.jpeg;images\*.gif" />

Você pode excluir um item de um tipo de item com o atributo Exclude. Por exemplo

<Compile Include="*.cs" Exclude="*Designer*">

adiciona todos os arquivos com a extensão de arquivo .cs ao tipo de item Compile, exceto os arquivos cujos nomes contêm a cadeia de caracteres Designer. Para obter mais exemplos, consulte Como Excluir ficheiros da compilação.

O atributo Exclude afeta apenas os itens adicionados pelo atributo Include no elemento item que contém ambos. Por exemplo

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

não excluiria o arquivo Form1.cs, que foi adicionado no elemento item anterior.

Para incluir e excluir itens

1. No editor de códigos, substitua a tarefa Mensagem por esta linha:

   <Message Text="XFiles item type contains @(XFiles)" />
   

2. Adicione este grupo de itens logo após o elemento Importar:

   <ItemGroup>
      <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
   </ItemGroup>
   

3. Salve o arquivo de projeto.

4. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examina a saída. Você deve ver esta linha:

   XFiles item type contains Form1.cs;Program.cs;Properties/Resources.resx
   

Metadados do item

Os itens podem conter metadados, além das informações coletadas dos atributos Include e Exclude. As tarefas que exigem mais informações sobre itens do que apenas o valor do item podem usar esses metadados.

Os metadados do item são declarados no arquivo de projeto criando um elemento com o nome dos metadados como um elemento filho do item. Um item pode ter zero ou mais valores de metadados. Por exemplo, o seguinte item CSFile tem metadados Culture com um valor de "Fr":

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Para obter o valor de metadados de um tipo de item, use a seguinte sintaxe, onde ItemType é o nome do tipo de item e MetaDataName é o nome dos metadados:

%(ItemType.MetaDataName)

Para examinar os metadados do item:

1. No editor de códigos, substitua a tarefa Mensagem por esta linha:

   <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver estas linhas:

   Compile.DependentUpon:
   Compile.DependentUpon: Form1.cs
   Compile.DependentUpon: Resources.resx
   Compile.DependentUpon: Settings.settings
   

Observe como a frase "Compile.DependentUpon" aparece várias vezes. O uso de metadados com essa sintaxe dentro de um destino causa "lotes". Processamento em lote significa que as tarefas dentro do destino são executadas uma vez para cada valor de metadados exclusivo. Batching é o equivalente de script MSBuild da construção de programação comum "foreach loop". Para obter mais informações, consulte Batching.

Metadados bem conhecidos

Sempre que um item é adicionado a uma lista de itens, esse item recebe alguns metadados conhecidos. Por exemplo, %(Filename) retorna o nome de arquivo de qualquer item. Para obter uma lista completa de metadados bem conhecidos, consulte Metadados de itens bem conhecidos.

Para examinar metadados bem conhecidos:

1. No editor de códigos, substitua a tarefa Mensagem por esta linha:

   <Message Text="Compile Filename: %(Compile.Filename)" />
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver estas linhas:

   Compile Filename: Form1
   Compile Filename: Form1.Designer
   Compile Filename: Program
   Compile Filename: AssemblyInfo
   Compile Filename: Resources.Designer
   Compile Filename: Settings.Designer
   

Ao comparar os dois exemplos anteriores, você pode ver que, embora nem todos os itens no tipo de item Compile tenham metadados DependentUpon , todos os itens têm os conhecidos metadados Filename.

Transformações de metadados

As listas de itens podem ser transformadas em novas listas de itens. Para transformar uma lista de itens, use a seguinte sintaxe, onde <ItemType> é o nome do tipo de item e <MetadataName> é o nome dos metadados:

@(ItemType -> '%(MetadataName)')

Por exemplo, uma lista de itens de arquivos de origem pode ser transformada em uma coleção de arquivos de objeto usando uma expressão como @(SourceFiles -> '%(Filename).obj'). Para obter mais informações, consulte Transforms.

Para transformar itens usando metadados:

1. No editor de códigos, substitua a tarefa Mensagem por esta linha:

   <Message Text="Backup files: @(Compile->'%(filename).bak')" />
   

2. Salve o arquivo de projeto.

3. Na Janela de Comando, digite e execute este comando:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examina a saída. Você deve ver esta linha:

   Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
   

Observe que os metadados expressos nesta sintaxe não provocam agrupamento em lotes.

Próximos passos

Para saber como criar um arquivo de projeto simples uma etapa de cada vez, no Windows, experimente Criar um arquivo de projeto do MSBuild do zero.

Se estiver a usar principalmente o SDK .NET, continue a ler na secção Referência do MSBuild para projetos do SDK .NET.

Conteúdo relacionado

• Visão geral do MSBuild
• Referência do MSBuild