Tutorial: usar o MSBuild

O MSBuild é a plataforma de build 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. Saiba mais sobre:

• Criando e manipulando um arquivo de projeto.

• Como usar as propriedades de build.

• Usar itens de build.

Você pode executar o MSBuild no Visual Studio ou na Janela de Comando executando MSBuild.exe. Há muitos motivos pelos quais talvez você queira executar o MSBuild na janela de comando, como se você deseja criar em um computador que não tenha o Visual Studio instalado ou se deseja usar argumentos de linha de comando específicos que não podem ser definidos 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 build ou executar um subconjunto do build, como executar explicitamente um destino de build específico em vez do build completo. Consulte a referência de linha de comando do MSBuild. Você também pode usar MSBuild.exe para criar em computadores que não têm o Visual Studio completo instalado, como em um servidor de build ou fazendo logon em um contêiner em um pipeline.

Neste tutorial, você criará um arquivo de projeto do MSBuild usando o Visual Studio. Edite o arquivo de projeto no Visual Studio e use a janela de comando para criar o projeto e examinar os resultados.

Instalar o MSBuild

Criar um projeto do MSBuild

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

Criar um arquivo de projeto

1. Abra o Visual Studio e crie um projeto:

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

   Na caixa de nome do Projeto , digite BuildApp. Insira um Local para a solução, por exemplo, D:\.

2. Clique em 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 em C#. O arquivo de projeto é representado no Gerenciador de Soluções pelo nó de projeto chamado BuildApp. Você pode usar o editor de código do Visual Studio para examinar o arquivo de projeto.

Examinar o arquivo de projeto

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

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

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

   O arquivo de projeto é exibido no editor de código.

Adicionar um destino e uma tarefa

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

Destinos e tarefas

Arquivos de projeto são arquivos XML com o projeto do nó raiz.

A maioria dos projetos do .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 build para esse SDK. Se você não fizer referência a nenhum SDK, ainda poderá usar o MSBuild, mas 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 do .NET para fins especiais; elas são descritas em SDKs do projeto .NET.

O trabalho de construir um aplicativo é realizado com os elementos Destino e Tarefa.

• 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. No momento, não há tarefas 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 build, normalmente para alguns artefatos de saída, como um arquivo ou um conjunto de arquivos, dadas determinadas entradas. Normalmente, ele é composto por uma sequência de tarefas, mas, criticamente, representa algo a ser criado ou feito, portanto, deve ser definido de forma orientada a metas. Para obter mais informações, consulte Destinos.

O destino padrão não é definido no arquivo de projeto. Em vez disso, ele é 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 de importação, 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 seja criado no máximo uma vez.

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

Adicionar um destino e uma tarefa

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

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

   Esse código cria um destino chamado HelloWorld. Observe que você tem suporte do IntelliSense durante a edição do arquivo de projeto.

2. Adicione linhas ao destino HelloWorld, de modo que a seção resultante seja semelhante a esta:

   <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 são fornecidas com o MSBuild. Para obter uma lista completa de tarefas disponíveis e informações de uso, consulte Referência de tarefa.

A tarefa Message usa o valor da cadeia de caracteres do atributo Text como entrada e exibe-o no dispositivo de saída (ou grava-o 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".

Compilar o destino

Se você tentar criar esse projeto no Visual Studio, ele não criará o alvo que você 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 o build novamente no Visual Studio e examine a guia Compilar da janela Saída para ver as mensagens Hello World.

Você também pode especificar os destinos desejados executando o MSBuild na linha de comando. Nesta seção, você executará o MSBuild no 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.

Para compilar o destino:

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. Uma lista de aplicativos instalados que correspondem ao padrão de pesquisa é exibida.

   Se você precisar encontrá-lo manualmente, o arquivo será LaunchDevCmd.bat na pasta de {pasta de instalação do Visual Studio}\Common7\Tools.

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

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

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examine a saída na janela de comando . Você deverá 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.

Propriedades de build

As propriedades de build são pares nome-valor que guiam o build. Várias propriedades de build 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 filho 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 da cadeia de caracteres "net8.0"

As propriedades de criação podem ser redefinidas a qualquer momento. If

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

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

Examinar um valor da propriedade

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

$(PropertyName)

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

Para examinar um valor da 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 Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

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

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

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

Propriedades condicionais

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

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

significa "Se a propriedade Configuração ainda não tiver sido definida, defina-a e dê a ela o valor 'Depurar'."

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

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

Variáveis de ambiente

Você pode referenciar variáveis de ambiente em arquivos de projeto da mesma maneira que as propriedades de build. Por exemplo, para usar a variável de ambiente PATH no arquivo de projeto, use $(Path). Se o projeto contiver uma definição de propriedade que tenha o mesmo nome de uma variável de ambiente, a propriedade no projeto substituirá o valor da variável de ambiente. Para obter mais informações, consulte Como usar variáveis de ambiente em um build.

Definir propriedades da linha de comando

As propriedades podem ser definidas na linha de comando usando o comutador de linha de comando -property ou -p. Valores de propriedade recebidos da linha de comando substituem valores de propriedade definidos no arquivo de projeto e variáveis de ambiente.

Para definir um valor de propriedade da linha de comando:

1. Na janela Comando, digite e execute esta linha:

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

2. Verifique a saída. Você deverá ver esta linha:

   Configuration is Release.
   

O MSBuild cria a propriedade Configuração e fornece o valor "Release".

Caracteres especiais

Determinados caracteres têm um significado especial nos arquivos de projeto do 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>, em que <xx> representa o valor hexadecimal ASCII do caractere.

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

Para usar caracteres especiais na tarefa Message:

1. No Editor de Código, substitua ambas as tarefas Message por esta linha:

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

2. Salve o arquivo de projeto.

3. Na janela Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique a saída. Você deverá ver esta linha:

   $(Configuration) is "Debug"
   

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

Compilar itens

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

Todos os itens são elementos filho dos 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 correspondentes. Por exemplo

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

define um grupo de itens que contém 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 um ponto-e-vírgula.

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

Para obter mais informações, consulte Itens.

Examinar os valores de tipo de item

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

@(ItemType)

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

Para examinar os valores de tipo de item:

1. No editor de código, substitua a tarefa alvo 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 Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique a saída. Você deverá ver esta linha longa:

   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 seguinte sintaxe, em que ItemType é o tipo de item e Separador é uma cadeia de caracteres de um ou mais caracteres separados:

@(ItemType, Separator)

Altere a tarefa Message para usar retornos de carro e alimentações de linha (%0A%0D) para exibir os itens Compile em linhas individuais.

Para exibir valores de tipo de item um por linha

1. No editor de código, 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 Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique 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 caracteres curinga "*", "**" 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 Foto que contém todos os arquivos na pasta imagens com uma extensão de arquivo de .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 para arquivos cujos nomes contêm a cadeia de caracteres Designer. Para obter mais exemplos, consulte Como: Excluir arquivos da compilação.

O atributo Exclude afeta apenas os itens adicionados pelo atributo Include no elemento de 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 de item anterior.

Para incluir e excluir itens

1. No editor de código, 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 Import:

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

3. Salve o arquivo de projeto.

4. Na janela Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Verifique a saída. Você deverá 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. Tarefas que exigem mais informações sobre itens do que apenas o valor do item podem usar esses metadados.

Os metadados de 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 de cultura com um valor "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, em que ItemType é o nome do tipo de item e MetaDataName é o nome dos metadados:

%(ItemType.MetaDataName)

Examinar os metadados do item:

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

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

2. Salve o arquivo de projeto.

3. Na janela Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique 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 em um destino causa "envio em lote". O envio em lote significa que as tarefas dentro do destino são executadas uma vez para cada valor de metadados exclusivo. O envio em lote é o equivalente do script do MSBuild do constructo de programação comum "foreach loop". Para obter mais informações, consulte Envio em lote.

Metadados conhecidos

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

Para examinar os metadados conhecidos:

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

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

2. Salve o arquivo de projeto.

3. Na janela Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique 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
   

Comparando os dois exemplos anteriores, você pode ver que, embora nem todos os itens no tipo de item Compile tenham o metadado DependentUpon, todos os itens têm o conhecido metadado Nome do Arquivo.

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, em que <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ódigo, substitua a tarefa Mensagem por esta linha:

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

2. Salve o arquivo de projeto.

3. Na janela Comando, digite e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Verifique a saída. Você deverá 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 nessa sintaxe não causam envio em lote.

Próximas etapas

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 usando principalmente o SDK do .NET, continue lendo em Referência do MSBuild para projetos do SDK do .NET.

Conteúdo relacionado

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