Compartilhar via

MSBuild

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 cria software. O Visual Studio usa o MSBuild, mas o MSBuild 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 criar projetos gerenciados. Os arquivos de projeto no Visual Studio (.csproj, .vbproj, .vcxproje outros) contêm código XML do MSBuild que é executado quando você cria um projeto no IDE. Os projetos do Visual Studio importam todas as configurações necessárias e os processos de build para fazer o trabalho de desenvolvimento típico, mas você pode estendê-los ou modificá-los de dentro do Visual Studio ou usando um editor de texto.

Instalar o MSBuild

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. A instalação do MSBuild por esse método fornece MSBuild.exe.

Para .NET Core e .NET 5 ou posterior, outra maneira de obter o equivalente ao MSBuild é instalar o SDK do .NET . O comando de build do .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.

Sobre o MSBuild

A partir do Visual Studio 2022, quando você cria no Visual Studio, a versão de 64 bits do MSBuild é usada.

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

Os exemplos a seguir ilustram quando você pode 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. Essa versão do MSBuild geralmente é desnecessária, mas permite que o MSBuild acesse mais memória.

  • Você quer executar uma compilação em vários processos. No entanto, você pode usar o IDE para obter o mesmo resultado em projetos em C++ e C#.

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

    • Pré-processar arquivos antes que eles cheguem ao compilador.

    • Copiar os resultados do build para um local diferente.

    • Crie arquivos compactados a partir de saídas de build.

    • Realize uma etapa de pós-processamento. Por exemplo, você pode querer carimbar um assembly com uma versão diferente.

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

Nota

Você pode usar o Azure Pipelines para compilar, testar e implantar automaticamente seu aplicativo. 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, consulte Azure Pipelines.

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

Usar o MSBuild em um prompt de comando

Para executar o MSBuild em um prompt de comando, passe um arquivo de projeto para MSBuild.exe, juntamente com as opções de linha de comando apropriadas. As opções de linha de comando permitem definir propriedades, executar destinos específicos e definir outras opções que controlam o processo de build. Por exemplo, você usaria a sintaxe de linha de comando a seguir 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 de arquivo, mas a convenção é usar extensões que terminam em proj como .csproj, .vcxprojou .vbproj, para o arquivo de entrada principal do MSBuild, chamado de "arquivo de projeto".

Para obter mais informações sobre as opções de linha de comando do MSBuild, consulte 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, normalmente você usa dotnet build para invocar o MSBuild. Confira o build do dotnet. Se você instalar apenas 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 são processadas por dotnet build são passadas para o 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 criados e também como eles devem ser criados para diferentes sistemas operacionais e configurações. Além disso, o formato de arquivo de projeto permite que os desenvolvedores criem regras de build reutilizáveis que podem ser fatoradas em arquivos separados para que os builds possam ser executados de forma consistente em 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 os 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 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: criando 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 criando 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 definida.

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

As propriedades podem ser referenciadas em todo o arquivo de projeto usando a sintaxe $(<PropertyName>). Por exemplo, você pode referenciar as propriedades nos exemplos anteriores usando $(BuildDir) e $(Configuration).

Para saber mais sobre propriedades, confira Propriedades do MSBuild.

Itens

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 itens 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 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 em 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, nomes de propriedade, item e metadados não são. O exemplo a seguir cria o tipo de item Compile, comPileou qualquer outra variação de caso 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 itens, consulte Items.

Tarefas

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

A lógica de execução de uma tarefa é escrita em código gerenciado e mapeada para MSBuild usando o elemento UsingTask. Você pode escrever sua própria tarefa criando um tipo gerenciado que implementa a interface ITask. Para obter mais informações sobre como escrever tarefas, consulte Escrita de tarefas.

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

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

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

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

Metas

Os alvos agrupam tarefas em uma ordem específica e expõem seções do arquivo de projeto como pontos de entrada para o processo de construção. Os alvos geralmente são agrupados em seções lógicas para aumentar a legibilidade e 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 de código para cada destino. Por exemplo, se vários pontos de entrada no processo de build exigirem que as referências sejam criadas, você poderá criar um destino que compila referências e, em seguida, executar esse destino de cada ponto 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 chama a tarefa Csc que tem a lista de itens que foi 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, confira Destinos.

Logs de build

Você pode registrar erros de build, avisos e mensagens no console ou em outro dispositivo de saída. Para obter mais informações, consulte Obtendo registros de compilação com o MSBuild.

Usar o 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 de 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 criar projetos gerenciados. Isso significa que um projeto gerenciado pode ser criado no Visual Studio ou em um prompt de comando (mesmo que o Visual Studio não esteja instalado) e os resultados serão idênticos.

Para obter um tutorial sobre como usar o MSBuild no Visual Studio, consulte 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 do .NET Core, incluindo o .NET 5 e posterior. Por exemplo, você pode compilar um aplicativo para ser executado no .NET Framework 4 em uma plataforma de 32 bits e compilar o mesmo aplicativo a 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 do multitargeting:

  • Você pode desenvolver aplicativos destinados a versões anteriores do .NET Framework, por exemplo, as 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á segmentá-lo.

  • O multitargeting garante que um aplicativo use apenas a funcionalidade disponível na estrutura e na plataforma de destino.

Para obter mais informações, confira Multitargeting.

Personalizando a compilação

O MSBuild oferece suporte para uma ampla gama de cenários de build personalizados. A maioria das funcionalidades internas pode ser substituída ou estendida. Consulte Personalizar a build.

Acessando o MSBuild programaticamente

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. Consulte Usar a API do MSBuild.

O MSBuild é de software livre

O MSBuild é um projeto de software livre que aceita contribuições do usuário no repositório do GitHub do MSBuild.

Consulte também

Título Descrição
Passo a passo: criando um arquivo de projeto do MSBuild do zero Mostra como criar um arquivo de projeto básico incrementalmente usando apenas um editor de texto.
Passo a passo: usando o MSBuild Apresenta os blocos de construção do MSBuild e mostra como gravar, 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 de arquivo MSBuild e como as peças se encaixam.
Propriedades do MSBuild Introdução às propriedades e coleções de propriedades. As propriedades são pares chave/valor que podem ser usados para configurar builds.
Destinos Explica como agrupar tarefas em uma determinada ordem e habilitar seções do processo de build a serem chamadas na linha de comando.
Tarefas Mostra como criar uma unidade de código executável que pode ser usada pelo MSBuild para executar operações de build atômicas.
Condições Discute como usar o atributo Condition em um elemento MSBuild.
Envio em lote Discute como o MSBuild categoriza listas de itens por metadados para execução em tarefas e destinos.
Multidestino Mostra como direcionar várias versões do .NET e/ou várias plataformas.
Obter logs de criação Descreve como registrar em log eventos de build, mensagens e erros.
Como o MSBuild cria projetos Descreve o processo de build interno usado no MSBuild
práticas recomendadas de uso seguro do MSBuild Descreve as práticas recomendadas para configurar e executar seus builds com o MSBuild
Criar uma tarefa personalizada para 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 a comunidade e os recursos de suporte para obter mais informações sobre o MSBuild.

Referência