MSBuild

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

Visual Studio usa MSBuild para carregar e criar projetos gerenciados. Os arquivos de projeto no Visual Studio (.csproj, .vbproj, .vcxproje outros) contêm código XML MSBuild que é executado quando você cria um projeto no IDE. Os projetos do Visual Studio importam todas as configurações e processos de compilação necessários 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, vá para Build Tools for Visual Studio na página downloads. Instalar o MSBuild por este método dá-lhe 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 compilação 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 .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 destinados ao .NET Core e ao .NET 5 e posterior.

Sobre o MSBuild

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

Os exemplos a seguir ilustram quando você pode executar compilações invocando 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 é geralmente desnecessária, mas permite que o MSBuild aceda a mais memória.

• Você deseja 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 compilação. Por exemplo, talvez você queira habilitar as seguintes ações:

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

  • Copie as saídas de compilação para um local diferente.

  • Crie arquivos compactados a partir de saídas de compilação.

  • Faça uma etapa de pós-processamento. Por exemplo, talvez você queira carimbar um assembly com uma versão diferente.

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

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 compilação. 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

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 MSBuild principal, chamado de "arquivo de projeto".

Para obter mais informações sobre as opções de linha de comando do MSBuild, consulte a referência da linha de comandos .

Para .NET Core e .NET 5 ou posterior, você normalmente usa dotnet build para invocar o MSBuild. Consulte dotnet build. Se você instalar apenas o SDK do .NET, e não o Visual Studio ou as ferramentas de compilação do Visual Studio, então você tem MSBuild somente através dotnet build.

O dotnet build --help da linha de comando lista as opções da linha de comando específicas para dotnet build, não todas as opções de MSBuild.exe, mas 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.

Ficheiro 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 compilação reutilizáveis que podem ser fatoradas em arquivos separados para que as compilações possam ser executadas de forma consistente em diferentes projetos no produto.

O sistema de compilação do Visual Studio armazena lógica específica do projeto no próprio arquivo de projeto e usa arquivos XML MSBuild importados com extensões como .props e .targets para definir a lógica de compilação 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 do SDK do .NET, que são usados no .NET Core (e no .NET 5 e posterior), você não vê as importações no arquivo de projeto; em vez disso, você verá uma referência do SDK, que se parece com isto:

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

Esses 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 MSBuild. Para obter um tutorial sobre como criar um arquivo de projeto básico, consulte Passo a passo: Criando um arquivo de projeto MSBuild do zero.

Propriedades

As propriedades representam pares chave/valor que podem ser usados para configurar compilações. As propriedades são declaradas criando um elemento cujo nome é a propriedade como 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 é 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 fazer referência às propriedades nos exemplos anteriores usando $(BuildDir) e $(Configuration).

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

Itens

Os itens são entradas no sistema de compilação e normalmente representam arquivos. Os itens são agrupados em tipos de itens 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 compilação.

Os itens são declarados no arquivo de projeto ao criar um elemento cujo nome do tipo de item é 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 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 fazem distinção entre maiúsculas e minúsculas. No entanto, os nomes de propriedade, de item e de metadados não são. O exemplo a seguir cria o tipo de item Compile, comPileou qualquer outra variação de maiúsculas e minúsculas e atribui 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 compilação mais avançados. Para obter mais informações sobre itens, consulte Itens.

Tarefas

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

A lógica de execução de uma tarefa é escrita em código gerenciado e mapeada para MSBuild usando o UsingTask elemento. 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 Task writing.

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 juntamente com informações de uso, consulte a Referência de Tarefas .

Uma tarefa é executada em um arquivo de projeto 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 a ela 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.

Objetivos

Direciona tarefas de grupo em uma ordem específica e expõe seções do arquivo de projeto como pontos de entrada no processo de compilação. Os alvos são frequentemente agrupados em seções lógicas para aumentar a legibilidade e permitir a expansão. Dividir as etapas de compilação em destinos permite que você chame uma parte do processo de compilação 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 compilação exigirem que as referências sejam criadas, você poderá criar um destino que crie referências e, em seguida, executar esse destino a partir de cada ponto de entrada onde for necessário.

Os destinos são declarados no arquivo de projeto usando o elemento Target. Por exemplo, o código a seguir cria um alvo chamado Compile, que depois 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 alvos podem ser usados para descrever relacionamentos uns com os outros e executar análise de dependências, permitindo que seções inteiras do processo de construção sejam ignoradas se esse alvo estiver up-to-data. Para obter mais informações sobre objetivos, consulte Targets.

Registos de construção

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

Usar MSBuild no Visual Studio

Visual Studio usa o formato de arquivo de projeto MSBuild para armazenar informações de compilação sobre projetos gerenciados. As configurações de projeto que são adicionadas ou alteradas usando a interface do Visual Studio são refletidas no arquivo de .*proj gerado para cada projeto. 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.

Multisegmentação

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 o .NET 5 e posterior. Por exemplo, você pode compilar um aplicativo para ser executado no .NET Framework 3.5 SP1 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 do que uma plataforma é chamada de multitargeting.

Estes são alguns dos benefícios do multitargeting:

• 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 for lançado um service pack para a versão atual do .NET Framework, poderás direcionar para ele.

• A multisegmentação garante que um aplicativo use apenas a funcionalidade disponível na estrutura e na plataforma de destino.

Para obter mais informações, consulte Multitargeting.

Personalizando a compilação

MSBuild fornece suporte para uma ampla gama de cenários de compilação personalizada. A maioria das funcionalidades internas pode ser substituída ou estendida. Consulte Personalizar sua compilação.

Acessando o MSBuild programaticamente

Se você estiver desenvolvendo uma ferramenta de compilação, convém invocar o MSBuild programaticamente de um aplicativo .NET. Usando a API do MSBuild, você pode controlar todos os aspetos de um sistema de compilação 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. Veja Usar a API do MSBuild.

MSBuild é de código aberto

MSBuild é um projeto de código aberto que aceita contribuições de usuários no de repositório do MSBuild GitHub.

Ver também

Referência

• Referência do MSBuild
  Links para tópicos que contêm informações de referência.

• Glossário
  Define termos comuns do MSBuild.