Partilhar via

Configurar destinos e tarefas

  • Artigo

Tarefas do MSBuild selecionadas poderão ser definidas para serem executadas no ambiente de destino, quando o computador de desenvolvimento dá suporte ao ambiente de destino. Por exemplo, quando você usa um computador Windows de 64 bits para criar um aplicativo destinado a uma arquitetura Windows de 32 bits, as tarefas selecionadas são executadas em um processo de 32 bits.

Observação

Se uma tarefa de build é escrita em uma linguagem .NET como Visual C# ou Visual Basic e essa tarefa não usa recursos nativos nem ferramentas, ela será executada em qualquer contexto de destino sem adaptação.

Parâmetros de tarefa e atributos UsingTask

Os atributos UsingTask a seguir afetam todas as operações de uma tarefa em um processo de build específico:

  • O atributo Runtime, se presente, define a versão do CLR (Common Language Runtime) e pode assumir qualquer um destes valores: CLR2, CLR4, CurrentRuntime ou * (qualquer tempo de execução).

  • O atributo Architecture, se presente, define a plataforma e o número de bit e pode assumir qualquer um destes valores: x86, x64, CurrentArchitecture ou * (qualquer arquitetura).

  • O atributo TaskFactory, se presente, define a fábrica de tarefas que cria e executa a instância de tarefa e usa apenas o valor TaskHostFactory. Para obter mais informações, confira Fábricas de tarefas mais adiante neste documento.

<UsingTask TaskName="SimpleTask"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v3.5.dll" />

Você também pode usar os parâmetros MSBuildRuntime e MSBuildArchitecture para definir o contexto de destino da invocação de uma tarefa individual.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Antes do MSBuild executar uma tarefa, ele procura uma correspondência UsingTask que tem o mesmo contexto de destino. Parâmetros especificados no UsingTask mas não na tarefa correspondente são considerados com correspondência. Parâmetros especificados na tarefa mas não no UsingTask correspondente também são considerados com correspondência. Se os valores de parâmetro não forem especificados no UsingTask nem na tarefa, os valores assumem o valor * por padrão (qualquer parâmetro).

Aviso

Se mais de um UsingTask existe e todos têm atributos TaskName, Runtime e Architecture correspondentes, o primeiro a ser avaliado substitui os outros. Isso é diferente do comportamento dos elementos Property e Target.

Se os parâmetros são definidos na tarefa, o MSBuild tenta encontrar um UsingTask que corresponde a esses parâmetros ou que, pelo menos, não está em conflito com eles. Mais de um UsingTask pode especificar o contexto de destino da mesma tarefa. Por exemplo, uma tarefa com executáveis diferentes para ambientes de destino diferentes pode ser semelhante a esta:

<UsingTask TaskName="MyTool"
    Runtime="CLR2"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.v2.0.dll" />

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <MyTool MSBuildRuntime="CLR2" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Substituir UsingTasks padrão

Por padrão, o MSBuild manipula UsingTask como "primeiro ganha". A partir do 17.2, o MSBuild dá suporte à substituição desse comportamento por meio do parâmetro Override. Um UsingTask com o parâmetro Override definido como true terá prioridade sobre qualquer outro UsingTask do mesmo TaskName.

<UsingTask TaskName="MyTool"
    Runtime="CLR4"
    Architecture="x86"
    Override="true"
    AssemblyFile="$(MyToolsPath)\MyTool.4.0.dll" />

Aviso

Isso só pode ser feito uma vez por tarefa. Builds que tentam adicionar várias substituições para a mesma tarefa receberão o erro MSB4275 do MSBuild.

Fábricas de tarefas

A tabela a seguir mostra as fábricas de tarefas fornecidas pela instalação do MSBuild:

Fábrica de tarefas Descrição
AssemblyTaskFactory Este é o valor padrão. Executa a tarefa em processo.
TaskHostFactory Executa a tarefa fora do processo.
RoslynCodeTaskFactory Para tarefas embutidas escritas em C# ou Visual Basic e direcionadas ao .NET Standard; funciona com msbuild.exe e dotnet build.
CodeTaskFactory Para tarefas embutidas escritas em C# ou Visual Basic e direcionadas ao .NET Framework; funciona apenas com msbuild.exe.

Como o mecanismo de fábrica de tarefas é extensível, você também pode usar aqueles criados por terceiros ou criar o seu próprio. Uma razão para criar um seria dar suporte a outra linguagem para escrever tarefas embutidas.

TaskHostFactory

Antes de executar uma tarefa, o MSBuild verifica para ver se ela é designada para ser executada no contexto do software atual. Se a tarefa for designada desse modo, o MSBuild a passará para AssemblyTaskFactory, que a executará no processo atual; caso contrário, o MSBuild passará a tarefa para TaskHostFactory, que executará a tarefa em um processo correspondente ao contexto de destino. Mesmo se o contexto atual e o contexto de destino corresponderem, você poderá forçar a execução fora de processo de uma tarefa (para fins de isolamento, segurança ou outros) configurando TaskFactory para TaskHostFactory.

<UsingTask TaskName="MisbehavingTask"
    TaskFactory="TaskHostFactory"
    AssemblyFile="$(MSBuildToolsPath)\MyTasks.dll">
</UsingTask>

Quando TaskHostFactory é especificado explicitamente, o processo que executa a tarefa é de curta duração. Isso permite que o sistema operacional limpe todos os recursos relacionados à tarefa imediatamente após a execução. Por esse motivo, especifique TaskHostFactory ao referenciar tarefas criadas no mesmo processo de build que o uso delas, para evitar erros de arquivo em uso ao atualizar um assembly de tarefa após um build.

RoslynCodeTaskFactory

O RoslynCodeTaskFactory fornece um mecanismo pelo qual você pode escrever código C# ou Visual Basic para uma tarefa em um arquivo de projeto para uso imediato. O código é compilado durante o processo de build para produzir uma tarefa que você pode executar nesso mesmo build. O código que você escreve é para o .NET Standard, para que possa ser usado durante a execução do dotnet build, que usa a versão do .NET Core (e .NET 5 e posterior) do MSBuild, bem como msbuild.exe, que usa o .NET Framework. RoslynCodeTaskFactory é melhor para personalização que é um pouco difícil demais de fazer na lógica do MSBuild, mas não complexa o suficiente para criar um projeto separado. Consulte Criar uma tarefa embutida do MSBuild com RoslynCodeTaskFactory.

CodeTaskFactory

CodeTaskFactory é uma versão mais antiga do RoslynCodeTaskFactory que é limitada à versão do .NET Framework do MSBuild. Consulte Tarefas embutidas do MSBuild. Essa fábrica de tarefas tem suporte, mas o código mais recente deve usar RoslynCodeTaskFactory para uma aplicabilidade mais ampla.

Parâmetros de tarefa fantasma

Como qualquer outro parâmetro de tarefa, MSBuildRuntime e MSBuildArchitecture podem ser definidos de propriedades de build.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <FrameworkVersion>3.0</FrameworkVersion>
    </PropertyGroup>
    <Target Name="MyTarget">
        <SimpleTask MSBuildRuntime="$(FrameworkVerion)" MSBuildArchitecture= "x86"/>
    </Target>
</Project>

Ao contrário de outros parâmetros de tarefa, MSBuildRuntime e MSBuildArchitecture não são aparentes para a tarefa em si. Para escrever uma tarefa que reconhece o contexto no qual ela é executada, é necessário testar o contexto chamando o .NET Framework ou usar propriedades de build para passar as informações de contexto por meio de outros parâmetros de tarefa.

Observação

Os atributos UsingTask podem ser definidos no conjunto de ferramentas e nas propriedades do ambiente.

Os parâmetros MSBuildRuntime e MSBuildArchitecture fornecem a maneira mais flexível de definir o contexto de destino, mas também é a mais limitada em escopo. Por um lado, como eles são definidos na própria instância de tarefa e só são avaliados quando a tarefa está prestes a ser executada, eles podem derivar seu valor do escopo completo de propriedades disponíveis em tempo de avaliação e em tempo de build. Por outro lado, esses parâmetros se aplicam somente a uma instância específica de uma tarefa em um destino específico.

Observação

Os parâmetros de tarefa são avaliados no contexto do nó pai, não no contexto do host da tarefa. As variáveis de ambiente que são dependentes do runtime ou da arquitetura (como o local Arquivos de Programas) serão avaliadas como o valor que corresponde ao nó pai. No entanto, se a mesma variável de ambiente for lida diretamente pela tarefa, ela será avaliada corretamente no contexto do host da tarefa.

Conteúdo relacionado