Tutorial: usar o MSBuild

O MSBuild é a plataforma de build para Microsoft e Visual Studio. 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 . 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

Se você tiver o Visual Studio, já terá o MSBuild instalado. Com o Visual Studio 2022, ele é instalado na pasta de instalação do Visual Studio. Para uma instalação padrão típica no Windows 10, MSBuild.exe está na pasta de instalação no MSBuild\Current\Bin.

No instalador do Visual Studio, navegue até Componentes Individuaise localize a caixa de seleção para MSBuild. Ele é selecionado automaticamente quando você escolhe qualquer uma das outras cargas de trabalho a serem instaladas.

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

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.

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.

Nota

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 Descarregardo projeto) antes de abrir e editar o arquivo de projeto.

Destinos e tarefas

Arquivos de projeto são arquivos formatados em XML com o nó raiz Project.

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 alvo é uma sequência nomeada de tarefas. Pode ser uma sequência nomeada 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.

Adicionar um destino e uma tarefa

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.

Execute o MSBuild no Prompt de Comando do Desenvolvedor do Visual Studio para criar o destino HelloWorld definido previamente. Use a opção de linha de comando -target ou -t para selecionar o destino.

Nota

Vamos nos referir ao prompt de comando do desenvolvedor como a Janela de Comando nas seções seguintes.

Para compilar o destino:

1. 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.

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

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

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examine a saída na janela de comando . Você deverá ver as duas linhas "Olá" e "Mundo":

   Hello
   World
   

Nota

Se, em vez disso, você vir The target "HelloWorld" does not exist in the project, provavelmente esqueceu de salvar o arquivo de projeto no editor de código. Salve o arquivo e tente novamente.

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>net6.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 "net6.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\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 de Comando , insira e execute esta linha:

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

2. Examine o resultado. 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.

Nota

Os caminhos de arquivo são relativos à pasta que contém o arquivo de projeto DO MSBuild, mesmo que o arquivo de projeto seja um arquivo de projeto importado. Há algumas exceções a isso, como ao usar os elementos Import e UsingTask.

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 de Comando , insira e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examine o resultado. 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 de Comando do , insira e execute a seguinte linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examine o resultado. 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 de Comando do ,, insira e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Examine o resultado. 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 de Comando , insira e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examine o resultado. 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. Examine o resultado. 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 de Comando do , insira e execute esta linha:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Examine o resultado. 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