Tarefa MSBuild

Cria 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 de 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 de ITaskItem[] necessário. Especifica os arquivos de projeto a serem compilados.
Properties	Parâmetro de String opcional. Uma lista delimitada por ponto-e-vírgula de pares nome/valor da propriedade a ser aplicada como propriedades globais ao projeto filho. Quando você especifica esse parâmetro, ele é funcionalmente equivalente a definir propriedades que têm a opção -property ao compilar com MSBuild.exe. Por exemplo: Properties="Configuration=Debug;Optimize=$(Optimize)" Quando você passa propriedades para o projeto por meio do parâmetro Properties, o MSBuild pode criar uma nova instância do projeto mesmo que o arquivo de projeto já tenha sido carregado. O MSBuild cria uma única instância de projeto para um determinado caminho de projeto e um conjunto exclusivo de propriedades globais. Por exemplo, esse comportamento permite que você crie várias tarefas do MSBuild que chamam myproject.proj, com Configuration=Release e você obtém uma única instância de myproject.proj (se nenhuma propriedade exclusiva for especificada na tarefa). Se você especificar uma propriedade que ainda não foi vista pelo MSBuild, o MSBuild criará uma nova instância do projeto, que pode ser criada em paralelo a outras instâncias do projeto. Por exemplo, uma configuração de versão pode ser compilada ao mesmo tempo que uma configuração de Depuração.
RebaseOutputs	Parâmetro de Boolean opcional. Se true, os caminhos relativos dos itens de saída de destino dos projetos criados terão seus caminhos ajustados para serem relativos ao projeto de chamada. O padrão é false.
RemoveProperties	Parâmetro de String opcional. Especifica o conjunto de propriedades globais a serem removidas.
RunEachTargetSeparately	Parâmetro de Boolean opcional. Se true, a tarefa MSBuild invocará cada destino na lista passado 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 invocados mesmo se os destinos invocados anteriormente falharem. Caso contrário, um erro de build interromperia a invocação de todos os destinos subsequentes. O padrão é false.
SkipNonexistentProjects	Parâmetro de 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. Usa false como padrão.
SkipNonexistentTargets	Parâmetro de Boolean opcional. Se true, os arquivos de projeto que existem, mas não contêm os Targets nomeados, serão ignorados. Caso contrário, esses projetos causarão um erro. Usa false como padrão. Introduzido no MSBuild 15.5.
StopOnFirstFailure	Parâmetro de Boolean opcional. Se true, quando um dos projetos não for compilado, nenhum projeto será criado. Atualmente, não há suporte para essa opção ao criar em paralelo (com vários processadores).
TargetAndPropertyListSeparators	Parâmetro de String[] opcional. Especifica uma lista de destinos e propriedades como metadados de item Project). Separadores não são separados antes do processamento. Por exemplo, %3B (um ';') escapado é tratado como se fosse um ';' sem escape.
TargetOutputs	Opcional ITaskItem[] parâmetro de saída somente leitura. Retorna as saídas dos destinos criados de todos os arquivos de projeto. Somente as saídas dos destinos especificados são retornadas, não quaisquer saídas que possam existir em destinos dos quais esses destinos dependem. O parâmetro TargetOutputs também contém os seguintes metadados: - MSBuildSourceProjectFile: o arquivo de projeto MSBuild que contém o destino que define as saídas. - MSBuildSourceTargetName: o destino que define as saídas. Observação: Se você quiser 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 de String opcional. Especifica o destino ou os destinos a serem compilados nos arquivos do projeto. Use um ponto-e-vírgula para separar uma lista de nomes de destino. Se nenhum destino for especificado na tarefa MSBuild, os destinos padrão especificados nos arquivos de projeto serão criados. Observação: os destinos devem ocorrer em todos os arquivos de projeto. Se não o fizerem, ocorrerá um erro de build.
ToolsVersion	Parâmetro de String opcional. Especifica o ToolsVersion a ser usado ao criar projetos passados para essa tarefa. Permite que uma tarefa do MSBuild crie 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.

Observações

Além dos parâmetros listados anteriormente, 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, consulte de classe base TaskExtension.

Ao contrário do uso da tarefa Exec para iniciar MSBuild.exe, essa tarefa usa o mesmo processo do MSBuild para criar os projetos filho. A lista de destinos já criados que podem ser ignorados é compartilhada entre os builds pai e filho. Essa tarefa também é mais rápida porque nenhum novo processo do MSBuild é criado.

Essa tarefa pode processar não apenas arquivos de projeto, mas também arquivos de solução. No MSBuild 17.12 e posterior, os formatos de arquivo de solução .slnx e .sln são aceitos.

Qualquer configuração exigida pelo MSBuild para permitir que os projetos sejam criados ao mesmo tempo, mesmo que a configuração envolva infraestrutura remota (por exemplo, portas, protocolos, tempos limite, novas tentativas e assim por diante), deverá ser configurada usando um arquivo de configuração. Quando possível, os itens de configuração devem ser especificados como parâmetros de tarefa na tarefa MSBuild.

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

Passar propriedades para projetos

Nas versões do MSBuild anteriores ao MSBuild 3.5, passar diferentes conjuntos de propriedades para diferentes projetos listados no item MSBuild era desafiador. Se você usou o atributo Propriedades da tarefa MSBuild, sua configuração foi aplicada a todos os projetos que estão sendo criados, a menos que você tenha colocado em lote a tarefa MSBuild e fornecido condicionalmente propriedades diferentes para cada projeto na lista de itens.

No entanto, o MSBuild 3.5 fornece dois novos itens de metadados reservados, Propriedades e AdditionalProperties, que fornecem uma maneira flexível de passar propriedades diferentes para projetos diferentes que estão sendo criados usando a tarefa MSBuild.

Observação

Esses novos itens de metadados são aplicáveis somente a itens passados no atributo Projects da tarefa MSBuild.

Benefícios de build de vários processadores

Um dos principais benefícios de usar esses novos metadados ocorre quando você cria seus projetos em paralelo em um sistema multiprocessador. Os metadados permitem consolidar todos os projetos em uma única tarefa MSBuild chamada sem a necessidade de executar tarefas do MSBuild em lotes ou condicionais. E quando você chama apenas um único de tarefa do MSBuild, todos os projetos listados no atributo Projetos são compilados em paralelo. (Somente, no entanto, se o atributo BuildInParallel=true estiver presente na tarefa MSBuild.) Para obter mais informações, consulte Criar vários projetos em paralelo.

Metadados de propriedades

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

Um cenário comum é quando você está criando vários arquivos de solução usando a tarefa msbuild, usando apenas configurações de build diferentes. Talvez você queira criar a solução a1 usando a configuração de depuração e 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 de solução adicionais.

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>

No entanto, usando os metadados de Propriedades, você pode simplificar esse código para usar uma única de tarefa do MSBuild, conforme mostrado pelo exemplo 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 cenário a seguir em que você está criando dois arquivos de solução usando a tarefa MSBuild, ambos usando a configuração de versão, mas um usando a arquitetura x86 e o outro usando a arquitetura ia64. No MSBuild 2.0, você precisaria criar várias instâncias da tarefa MSBuild: uma para criar 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 MSBuild usando o seguinte:

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 criar os 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>

Consulte também

• Tarefas
• Referência de tarefas