MSBuild

  • Artigo

O Microsoft Build Engine é uma plataforma para a criação de aplicativos. Esse mecanismo, que é também conhecido como MSBuild, fornece um esquema XML para um arquivo de projeto que controla como a plataforma de build processa e compila software. O Visual Studio usa o MSBuild, que não depende do Visual Studio. Ao invocar msbuild.exe ou build dotnet no seu arquivo de projeto ou solução, você pode organizar e criar produtos em ambientes em que o Visual Studio não está instalado.

O Visual Studio usa o MSBuild para carregar e compilar projetos gerenciados. Os arquivos de projeto no Visual Studio (.csproj, .vbproj, .vcxproj e outros) contêm o código XML do MSBuild que é executado ao compilar um projeto usando o IDE. Os projetos do Visual Studio importam toas as configurações e processos de build necessários para realizar o trabalho de desenvolvimento típico, mas você pode estendê-las ou modificá-las de dentro do Visual Studio ou usando um editor de XML.

Para instalar o MSBuild em um sistema Windows que não tenha o Visual Studio, acesse Ferramentas de Construção para o Visual Studio na página de downloads. Ao instalar o MSBuild por esse método, você obtém MSBuild.exe.

Para o .NET Core e o .NET 5 ou posterior, outra maneira de obter o equivalente ao MSBuild é instalar o SDK do .NET. O comando de compilação .NET dotnet build está disponível com o SDK do .NET no macOS, Windows ou Linux. O comando de compilação do .NET dotnet build é um wrapper fino sobre a versão do .NET Core do MSBuild.exe. Você pode usar a interface de linha de comando (CLI) do .NET Core , que usa o MSBuild, para criar projetos direcionados ao .NET Core e ao .NET 5 e posterior.

No Visual Studio 2022 e versões posteriores, quando você compila no Visual Studio, a versão de 64 bits do MSBuild é usada.

Para obter informações sobre o MSBuild para C++, confira MSBuild (C++).

Os exemplos a seguir ilustram quando você deve executar builds invocando o MSBuild da linha de comando em vez do IDE do Visual Studio.

  • O Visual Studio não está instalado.

  • Você deseja usar a versão de 64 bits do MSBuild e está usando o Visual Studio 2019 ou anterior. Esta versão do MSBuild normalmente não é necessária, mas permite que o MSBuild acesse mais memória.

  • Você deseja executar um build em vários processos. No entanto, você pode usar o IDE para alcançar o mesmo resultado em projetos em C++ e C#.

  • Você deseja modificar o sistema de build. Por exemplo, você talvez queira habilitar as seguintes ações:

    • Pré-processar arquivos antes de eles chegarem ao compilador.

    • Copiar as saídas de build para um local diferente.

    • Criar arquivos compactados de saídas de build.

    • Realizar uma etapa de pós-processamento. Por exemplo, convém marcar um assembly com uma versão diferente.

Você pode escrever código no IDE do Visual Studio, mas executar os builds usando o MSBuild. Como outra alternativa, você pode compilar o código no IDE em um computador de desenvolvimento, mas executar o MSBuild da linha de comando para compilar o código integrado de um repositório de origem com colaboração de vários desenvolvedores.

Observação

Você pode usar o Azure Pipelines para compilar, testar e implantar seu aplicativo automaticamente. O sistema de build pode executar builds automaticamente quando os desenvolvedores fazem o check-in de código (por exemplo, como parte de uma estratégia de Integração Contínua) ou de acordo com um cronograma (por exemplo, um build de teste de aceitação pós-build noturno). O Azure Pipelines compila seu código usando o MSBuild. Para obter mais informações, confira Azure Pipelines.

Para obter um tutorial introdutório para o MSBuild no Windows, confira Passo a passo: usando o MSBuild.

Usar MSBuild em um prompt de comando

Para executar o MSBuild em um prompt de comando, passe um arquivo de projeto para MSBuild.exe, junto com as opções de linha de comando apropriadas. As opções de linha de comando permitem que você defina propriedades, execute destinos específicos e defina outras opções que controlam o processo de build. Por exemplo, você usaria a seguinte sintaxe de linha de comando para criar o arquivo MyProj.proj com a propriedade Configuration definida como Debug.

MSBuild.exe MyProj.proj -property:Configuration=Debug

O MSBuild não altera seu comportamento com base na extensão do arquivo, mas a convenção é usar extensões terminadas em proj, como .csproj, .vcxproj ou .vbproj, para o arquivo de entrada principal do MSBuild, chamado de "arquivo do projeto".

Para obter mais informações sobre as opções de linha de comando do MSBuild, confira Referência de linha de comando.

Importante

Antes de baixar um projeto, determine a confiabilidade do código.

Para .NET Core e .NET 5 ou posterior, você normalmente usa dotnet build para invocar o MSBuild. Confira o build do dotnet. Se você instalar somente o SDK do .NET e não o Visual Studio ou as Ferramentas de Build do Visual Studio, terá o MSBuild somente por meio de dotnet build.

A linha de comando dotnet build --help lista as opções de linha de comando específicas para dotnet build, nem todas as opções de MSBuild.exe, mas você ainda pode usar todas as opções de linha de comando listadas na referência de linha de comando do MSBuild. As opções que não forem processadas por dotnet build serão repassadas ao MSBuild.

Arquivo de projeto

O MSBuild usa um formato de arquivo de projeto baseado em XML que é simples e extensível. O formato de arquivo de projeto do MSBuild permite que os desenvolvedores descrevam os itens que devem ser compilados e também como eles devem ser compilados para diferentes sistemas operacionais e configurações. Além disso, o formato de arquivo de projeto permite aos desenvolvedores criar regras de build reutilizáveis que podem ser fatoradas em arquivos separados para que os builds possam ser realizados de forma consistente entre os diferentes projetos no produto.

O sistema de build do Visual Studio armazena a lógica específica do projeto no próprio arquivo de projeto e usa arquivos XML do MSBuild importados, com extensões como .props e .targets, para definir a lógica de build padrão. Os arquivos .props definem as propriedades do MSBuild e os arquivos .targets definem destinos do MSBuild. Essas importações às vezes são visíveis no arquivo de projeto do Visual Studio, mas em projetos mais recentes, como projetos .NET Core, .NET 5 e .NET 6, você não vê as importações no arquivo de projeto; Em vez disso, você verá uma referência do SDK, que tem esta aparência:

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

Eles são chamados de projetos no estilo do SDK. Quando você faz referência a um SDK, como o SDK do .NET, as importações de arquivos .props e .target são especificadas implicitamente pelo SDK.

As seções a seguir descrevem alguns dos elementos básicos do formato de arquivo de projeto do MSBuild. Para obter um tutorial sobre como criar um arquivo de projeto básico, consulte Passo a passo: criar um arquivo de projeto do MSBuild do zero.

Propriedades

As propriedades representam pares chave-valor que podem ser usados para configurar builds. As propriedades são declaradas com a criação de um elemento que tem o nome da propriedade como um filho de um elemento PropertyGroup. Por exemplo, o código a seguir cria uma propriedade chamada BuildDir que tem um valor de Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Você pode definir uma propriedade condicionalmente colocando um atributo Condition no elemento. O conteúdo dos elementos condicionais é ignorado a menos que a condição seja avaliada como true. No exemplo a seguir, a propriedade Configuration será definida se ainda não tiver sido.

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

As propriedades podem ser referenciadas por todo o arquivo de projeto usando a sintaxe $(<PropertyName>). Por exemplo, você pode fazer referência às propriedades nos exemplos anteriores usando $(BuildDir) e $(Configuration).

Para obter mais informações sobre propriedades, confira Propriedades do MSBuild.

Itens

Os itens são entradas no sistema de build e normalmente representam arquivos. Os itens são agrupados em tipos de item com base em nomes de item definidos pelo usuário. Esses tipos de item podem ser usados como parâmetros para tarefas, que usam os itens individuais para executar as etapas do processo de build.

Os itens são declarados no arquivo de projeto, criando um elemento que tem o nome do tipo de item como um filho de um elemento ItemGroup. Por exemplo, o código a seguir cria um tipo de item chamado Compile, que inclui dois arquivos.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Os tipos de item podem ser referenciados por todo o arquivo de projeto usando a sintaxe @(<ItemType>). Por exemplo, o tipo de item no exemplo seria referenciado usando @(Compile).

No MSBuild, os nomes de elementos e atributos diferenciam maiúsculas de minúsculas. No entanto, os nomes de propriedade, item e metadados não. O exemplo a seguir cria o tipo de item Compile, comPile ou qualquer outra variação de maiúsculas e minúsculas e fornece ao tipo de item o valor "one.cs;two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Os itens podem ser declarados usando caracteres curinga e podem conter metadados adicionais para cenários de build mais avançados. Para obter mais informações sobre os itens, consulte Itens.

Tarefas

As tarefas são unidades de código executável usadas por projetos do MSBuild para executar operações de build. Por exemplo, uma tarefa pode compilar os arquivos de entrada ou executar uma ferramenta externa. As tarefas podem ser reutilizadas e podem ser compartilhadas por diferentes desenvolvedores em projetos diferentes.

A lógica de execução de uma tarefa é escrita em código gerenciado e mapeada para o MSBuild usando o elemento UsingTask. Você pode escrever sua própria tarefa por meio da criação de um tipo gerenciado que implementa a interface ITask. Para saber mais sobre como escrever tarefas, consulte Produção de tarefas.

O MSBuild inclui tarefas comuns que você pode modificar para atender às suas necessidades. Os exemplos são Copy, que copia arquivos, MakeDir, que cria diretórios e Csc, que compila os arquivos de código-fonte do Visual C#. Para obter uma lista das tarefas disponíveis juntamente com as informações de uso, consulte Referência das tarefas.

Uma tarefa é executada em um arquivo de projeto do MSBuild criando um elemento que tem o nome da tarefa como um filho de um elemento Target. As tarefas normalmente aceitam parâmetros, que são passados como atributos do elemento. As propriedades e itens do MSBuild podem ser usados como parâmetros. Por exemplo, o código a seguir chama a tarefa MakeDir e passa para ela o valor da propriedade BuildDir que foi declarada em um exemplo anterior.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Para obter mais informações sobre as tarefas, consulte Tarefas.

Destinos

Os destinos agrupam tarefas em uma ordem específica e expõe seções do arquivo de projeto como pontos de entrada para o processo de build. Os destinos geralmente são agrupados em seções lógicas para aumentar a legibilidade e para permitir a expansão. Dividir as etapas de build em destinos permite que você chame uma parte do processo de build de outros destinos sem copiar essa seção do código em cada destino. Por exemplo, se vários pontos de entrada no processo de build precisam de referências para serem compilados, você pode criar um destino que compila as referências e, em seguida, executar esse destino de todos os pontos de entrada em que ele é necessário.

Os destinos são declarados no arquivo de projeto usando o elemento Target. Por exemplo, o código a seguir cria um destino chamado Compile, que, em seguida, chama a tarefa Csc que tem a lista de itens declarada no exemplo anterior.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

Em cenários mais avançados, os destinos podem ser usados para descrever relações entre si e executar a análise de dependência para que seções inteiras do processo de build possam ser ignoradas se o destino estiver atualizado. Para obter mais informações sobre destinos, consulte Destinos.

Logs de build

Você pode registrar erros de build, avisos e mensagens para o console ou outro dispositivo de saída. Para obter mais informações, confira Obtendo logs de build com o MSBuild).

Usar MSBuild no Visual Studio

O Visual Studio usa o formato de arquivo de projeto do MSBuild para armazenar informações de build sobre projetos gerenciados. As configurações do projeto adicionadas ou alteradas usando a interface do Visual Studio são refletidas no arquivo .*proj gerado para cada projeto. O Visual Studio usa uma instância hospedada do MSBuild para compilar projetos gerenciados. Isso significa que um projeto gerenciado pode ser compilado no Visual Studio ou em um prompt de comando (mesmo se o Visual Studio não estiver instalado) e os resultados serão idênticos.

Para obter um tutorial sobre como usar o MSBuild no Visual Studio, consulte Instruções passo a passo: usando o MSBuild.

Multiplataforma

Usando o Visual Studio, você pode compilar um aplicativo para ser executado em qualquer uma das várias versões do .NET Framework ou .NET Core, incluindo .NET 5 e posterior. Por exemplo, você pode compilar um aplicativo para execução no .NET Framework 4 em uma plataforma de 32 bits e pode compilar o mesmo aplicativo para ser executado no .NET Framework 4.8 em uma plataforma de 64 bits. A capacidade de compilar para mais de uma estrutura é chamada de multiplataforma.

Estes são alguns dos benefícios de multiplataforma:

  • Você pode desenvolver aplicativos destinados a versões anteriores do .NET Framework, por exemplo, versões 3.5 e 4.7.2.

  • Você pode direcionar um perfil de estrutura, que é um subconjunto predefinido de uma estrutura de destino.

  • Se um service pack para a versão atual do .NET Framework for lançado, você poderá direcionar seu aplicativo a ele.

  • A multiplataforma garante que um aplicativo use apenas a funcionalidade que está disponível na estrutura de destino e na plataforma.

Para obter mais informações, consulte Multiplataforma.

Personalizando o build

O MSBuild dá suporte a uma ampla variedade de cenários de build personalizados. A maioria das funcionalidades internas pode ser substituída ou estendida. Confira Personalizar seu build.

Usando o MSBuild de maneira programática

Se você estiver desenvolvendo uma ferramenta de build, talvez queira invocar o MSBuild programaticamente de um aplicativo .NET. Usando a API do MSBuild, você pode controlar todos os aspectos de um sistema de build complexo. O MSBuild fornece um pacote NuGet com uma API completa (o namespace Microsoft.Build) que você pode usar de um aplicativo .NET para essas finalidades. Confira Usar a API do MSBuild.

O MSBuild é de código aberto

O MSBuild é um projeto de software livre que aceita contribuições de usuário, assim como o restante do ecossistema do .NET. O repositório que contém a origem do MSBuild está disponível no repositório GitHub do MSBuild.

Confira também

Título Descrição
Passo a passo: Criar um arquivo de projeto do MSBuild do zero Mostra como criar um arquivo de projeto básico de forma incremental, usando somente um editor de texto.
Passo a passo: Usando o MSBuild Apresenta os blocos de construção do MSBuild e mostra como escrever, manipular e depurar projetos do MSBuild sem fechar o IDE do Visual Studio.
Conceitos do MSBuild Apresenta os quatro blocos de construção do MSBuild: propriedades, itens, destinos e tarefas.
Itens Descreve os conceitos gerais por trás do formato do arquivo do MSBuild e como as partes se encaixam.
propriedades MSBuild Introduz propriedades e coleções de propriedades. Propriedades são pares chave-valor que podem ser usados para configurar builds.
Destinos Explica como agrupar tarefas em uma ordem específica e habilitar seções do processo de build a ser chamado na linha de comando.
Tarefas Mostra como criar uma unidade do código executável que pode ser usado pelo MSBuild para realizar operações de build atômicas.
Condições Discute como usar o atributo Condition em um elemento do MSBuild.
Separação em lotes Discute como o MSBuild categoriza listas de itens por metadados para execução em tarefas e destinos.
Multiplataforma Mostra como direcionar várias versões do .NET e/ou várias plataformas.
Obtendo logs de build Descreve como registrar eventos de build, mensagens e erros.
Como o MSBuild compila projetos Descreve o processo de build interno usado no MSBuild
Criar uma tarefa personalizada para a geração de código Mostra como criar uma tarefa personalizada, com um exemplo de código.
Usar o MSBuild para gerar um cliente da API REST Mostra como estender o build para lidar com a geração de cliente da API REST, com um exemplo de código.
Recursos adicionais Lista os recursos de comunidade e suporte para obter mais informações sobre o MSBuild.

Referência