tarefa MSBuild

  • Artigo

Compila projetos do MSBuild de outro projeto do MSBuild.

Parâmetros

A tabela a seguir descreve os parâmetros da tarefa MSBuild.

Parâmetro Descrição
BuildInParallel Parâmetro Boolean opcional.

Se true, os projetos especificados no parâmetro Projects serão criados em paralelo, se possível. O padrão é false.
Projects Parâmetro ITaskItem[] obrigatório.

Especifica os arquivos de projeto para compilar.
Properties Parâmetro String opcional.

Uma lista delimitada por ponto-e-vírgula de pares de nome/valor de propriedade para aplicar como propriedades globais para o projeto filho. Ao especificar esse parâmetro, ele será funcionalmente equivalente às propriedades de definição que têm o comutador -property quando você compila com MSBuild.exe. Por exemplo:

Properties="Configuration=Debug;Optimize=$(Optimize)"

Ao passar propriedades para o projeto por meio do parâmetro Properties, o MSBuild poderá criar uma nova instância do projeto, mesmo se o arquivo de projeto já estiver carregado. O MSBuild cria uma única instância de projeto para determinado caminho de projeto e um conjunto exclusivo de propriedades globais. Por exemplo, esse comportamento permite criar várias tarefas do MSBuild que chamam myproject.proj, com Configuration=Release, e você obtém uma única instância do myproject.proj (se não houver propriedades exclusivas especificadas na tarefa). Se você especificar uma propriedade que ainda não foi vista pelo MSBuild, o MSBuild cria uma nova instância do projeto, que pode ser compilada em paralelo a outras instâncias do projeto. Por exemplo, uma configuração de versão poderia ser compilada ao mesmo tempo como uma configuração de depuração.
RebaseOutputs Parâmetro Boolean opcional.

Se true, os caminhos relativos dos itens de saída de destino de projetos de compilação terão seus caminhos ajustados para serem relativos ao projeto de chamada. O padrão é false.
RemoveProperties Parâmetro String opcional.

Especifica o conjunto de propriedades globais para remover.
RunEachTargetSeparately Parâmetro Boolean opcional.

Se true, a tarefa MSBuild chamará cada destino na lista passada para o MSBuild, um de cada vez, em vez de ao mesmo tempo. Definir esse parâmetro como true garante que os destinos subsequentes sejam chamados mesmo se os destinos chamados anteriormente tiverem falhado. Caso contrário, um erro de build pararia a invocação de todos os destinos subsequentes. O padrão é false.
SkipNonexistentProjects Parâmetro Boolean opcional.

Se true, os arquivos de projeto que não existem no disco serão ignorados. Caso contrário, esses projetos causarão um erro. Assume o padrão de false.
SkipNonexistentTargets Parâmetro Boolean opcional.

Se true, os arquivos de projeto que existem, mas não contêm o nomeado Targets, serão ignorados. Caso contrário, esses projetos causarão um erro. Assume o padrão de false. Introduzido no MSBuild 15.5.
StopOnFirstFailure Parâmetro Boolean opcional.

Se true, quando um dos projetos falhar em compilar, os projetos não serão mais compilados. Atualmente isso não tem suporte na criação em paralelo (com vários processadores).
TargetAndPropertyListSeparators Parâmetro String[] opcional.

Especifica uma lista de destinos e de propriedades como metadados de item Project). Separadores não serão escapados antes do processamento. Por exemplo, %3B (um escape ';') será tratado como se não fosse escapado ';'.
TargetOutputs Parâmetro ITaskItem[] de saída opcional somente leitura.

Retorna as saídas dos destinos compilados de todos os arquivos de projeto. Somente as saídas de destinos que foram especificados são retornadas, não as saídas que podem existir em destinos dos quais esses destinos dependem.

O parâmetro TargetOutputs também contém os metadados a seguir:

- MSBuildSourceProjectFile: O arquivo de projeto do MSBuild que contém o destino que define as saídas.
- MSBuildSourceTargetName: o destino que define as saídas. Observação: Se você deseja identificar as saídas de cada arquivo de projeto ou destino separadamente, execute a tarefa MSBuild separadamente para cada arquivo de projeto ou destino. Se você executar a tarefa MSBuild apenas uma vez para compilar todos os arquivos de projeto, as saídas de todos os destinos serão coletadas em uma matriz.
Targets Parâmetro String opcional.

Especifica o destino ou destinos para build nos arquivos de projeto. Use uma lista separada por ponto-e-vírgula de nomes de destino. Se nenhum destino for especificado na tarefa MSBuild, os destinos padrão especificados nos arquivos de projeto serão compilados. Observação: os destinos devem ocorrer em todos os arquivos de projeto. Caso contrário, ocorrerá um erro de build.
ToolsVersion Parâmetro String opcional.

Especifica o ToolsVersion a ser usado ao compilar projetos passados para essa tarefa.

Permite que uma tarefa MSBuild compile um projeto direcionado a uma versão diferente do .NET Framework do que a especificada no projeto. Os valores válidos são 2.0, 3.0 e 3.5. O valor padrão é 3.5.

Comentários

Além dos parâmetros listados acima, essa tarefa herda parâmetros da classe TaskExtension, que herda da classe Task. Para obter uma lista desses parâmetros adicionais e suas descrições, confira Classe base TaskExtension.

Em vez de usar a tarefa Exec para iniciar o MSBuild.exe, essa tarefa usa o mesmo processo do MSBuild para compilar os projetos filho. A lista de destinos já compilados que pode ser ignorada é compartilhada entre as compilações pai e filho. Essa tarefa também é mais rápida porque nenhum processo novo do MSBuild é criado.

Essa tarefa pode processar não somente arquivos de projeto, mas também arquivos de solução.

Qualquer configuração que é exigida pelo MSBuild para habilitar projetos para build ao mesmo tempo, mesmo se a configuração envolve a infraestrutura remota (por exemplo, portas, protocolos, tempos limite, repetições e assim por diante), deverá ser feita configurável usando um arquivo de configuração. Quando possível, itens de configuração deverão ser capazes de ser especificados como parâmetros de tarefa na tarefa MSBuild.

A partir do MSBuild 3.5, os projetos de solução agora abrangem TargetOutputs de todos os subprojetos que ele compila.

Passar propriedades para projetos

Em versões do MSBuild anteriores ao MSBuild 3.5, passar diferentes conjuntos de propriedades para diferentes projetos listados no item MSBuild era um desafio. Se você tiver usado o atributo de propriedades da tarefa do MSBuild, então essa configuração foi aplicada a todos os projetos que estão sendo criados, a menos que você tenha enviado em lote a tarefa do MSBuild e fornecido condicionalmente propriedades diferentes para cada projeto na lista de itens.

O MSBuild 3.5, no entanto, fornece dois novos itens de metadados reservados, Properties e AdditionalProperties, que oferecem uma maneira flexível de passar diferentes propriedades para diferentes projetos criados usando a tarefa MSBuild.

Observação

Esses novos itens de metadados são aplicáveis apenas para itens que passaram no atributo de projetos da tarefa do MSBuild.

Benefícios da compilação multiprocessador

Um dos principais benefícios de usar esses novos metadados ocorre quando você compila seus projetos em paralelo em um sistema com vários processadores. Os metadados permitem consolidar todos os projetos em uma única chamada da tarefa MSBuild sem ter que executar qualquer processamento em lotes ou tarefas MSBuild condicionais. E quando você chama uma única tarefa do MSBuild, todos os projetos listados no atributo de projetos são criados em paralelo. (No entanto, somente se o atributo BuildInParallel=true estiver presente na tarefa MSBuild.) Para obter mais informações, consulte Compilar vários projetos em paralelo.

Metadados de propriedades

Quando especificados, os metadados de propriedades substituem o parâmetro Propriedades da tarefa, enquanto os metadados de AdditionalProperties são acrescentados às definições do parâmetro.

Um cenário comum é ao compilar vários arquivos de solução usando a tarefa do MSBuild, usar apenas configurações de build diferentes. Você pode querer compilar a solução a1 usando a configuração de depuração e compilar a solução a2 usando a configuração de versão. No MSBuild 2.0, esse arquivo de projeto seria semelhante ao seguinte:

Observação

No exemplo a seguir, "…" representa arquivos adicionais da solução.

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

Usando os metadados de propriedades, no entanto, você pode simplificar isso para usar uma única tarefa do MSBuild, conforme mostrado a seguir:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

- ou -

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln..."/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Debug"/>
    </Target>
</Project>

Metadados de AdditionalProperties

Considere o seguinte cenário em que você está compilando dois arquivos de solução usando a tarefa do MSBuild, usando a configuração de versão, mas uma que usa a arquitetura x86 e outra usando a arquitetura ia64. No MSBuild 2.0, você precisaria criar várias instâncias da tarefa MSBuild: uma para compilar o projeto usando a configuração de versão com a arquitetura x86, a outra usando a configuração de versão com a arquitetura ia64. Seu arquivo de projeto seria semelhante ao seguinte:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Release;
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release;
          Architecture=ia64"/>
    </Target>
</Project>

Usando os metadados AdditionalProperties, você pode simplificar isso para usar uma única tarefa do MSBuild, conforme mostrado a seguir:

a.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Release"/>
    </Target>
</Project>

Exemplo

O exemplo a seguir usa a tarefa MSBuild para compilar projetos especificados pela coleção de itens ProjectReferences. As saídas de destino resultantes são armazenadas na coleção de itens AssembliesBuiltByChildProjects.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

Confira também