Configurar destinos y tareas

  • Artículo

Las tareas de MSBuild seleccionadas se pueden establecer para ejecutarlas en el entorno de destino si el equipo de desarrollo admite el entorno de destino. Por ejemplo, si se utiliza un equipo Windows de 64 bits para compilar una aplicación destinada a una arquitectura de Windows de 32 bits, las tareas seleccionadas se ejecutan en un proceso de 32 bits.

Nota

Si una tarea de compilación se escribe en un lenguaje .NET, como Visual C# o Visual Basic, y no utiliza recursos o herramientas nativos, se ejecutará en cualquier contexto de destino sin adaptación.

Atributos UsingTask y parámetros de tareas

Los siguientes atributos de UsingTask afectan a todas las operaciones de una tarea en un proceso de compilación determinado:

  • El atributo de Runtime, si está presente, establece la versión de Common Language Runtime (CLR), y puede tomar cualquiera de estos valores: CLR2, CLR4, CurrentRuntime o * (cualquier tiempo de ejecución).

  • El atributo de Architecture, si está presente, establece la plataforma y el valor de bits, y puede tomar cualquiera de estos valores: x86, x64, CurrentArchitecture o * (cualquier arquitectura).

  • El atributo de TaskFactory, si está presente, establece el generador de tareas que crea y ejecuta la instancia de tarea, y únicamente toma el valor TaskHostFactory. Para obtener más información, vea Generadores de tareas más adelante en este documento.

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

También puede utilizar los parámetros MSBuildRuntime y MSBuildArchitecture para establecer el contexto de destino de una invocación de tarea individual.

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

Antes de que MSBuild ejecute una tarea, busca un valor UsingTask coincidente que tenga el mismo contexto de destino. Los parámetros que se especifican en UsingTask pero no en la tarea correspondiente se consideran coincidentes. Los parámetros que se especifican en la tarea pero no en el valor UsingTask correspondiente también se consideran coincidentes. Si no se especifican valores de parámetros no se especifican en UsingTask o la tarea, los valores se establecen de manera predeterminada en * (cualquier parámetro).

Advertencia

Si existe más de un UsingTask y todos tienen atributos TaskName, Runtime y Architecture coincidentes, el primero que se evalúe reemplaza a los demás. Esto es diferente del comportamiento de los elementos Property y Target.

Si se definen parámetros en la tarea, MSBuild intenta encontrar un valor UsingTask que coincida con estos parámetros o, al menos, que no esté en conflicto con ellos. Más de un UsingTask puede especificar el contexto de destino de la misma tarea. Por ejemplo, una tarea que tiene archivos ejecutables diferentes para entornos de destino diferentes podría parecerse 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>

Invalidación del valor predeterminado de UsingTasks

De forma predeterminada, MSBuild controla el elemento UsingTask priorizándolo según el concepto "el primero en llegar, gana". A partir de la versión 17.2, MSBuild admite la invalidación de este comportamiento a través del parámetro Override. Un elemento UsingTask con el parámetro Override establecido en true tendrá prioridad sobre cualquier otro con el mismo atributo TaskName.

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

Advertencia

Esto solo se puede hacer una vez por tarea. Las compilaciones que intenten agregar varias invalidaciones para la misma tarea recibirán el error de MSBuild MSB4275.

Generadores de tareas

En la tabla siguiente se muestran las factorías de tareas proporcionadas por la instalación de MSBuild:

Fábrica de tareas Descripción
AssemblyTaskFactory Este es el valor predeterminado. Ejecuta la tarea en proceso.
TaskHostFactory Ejecuta la tarea fuera de proceso.
RoslynCodeTaskFactory Para las tareas insertadas escritas en C# o Visual Basic y destinadas a .NET Standard; funciona con msbuild.exe y dotnet build.
CodeTaskFactory Para las tareas insertadas escritas en C# o Visual Basic y destinadas a .NET Framework; funciona solo con msbuild.exe.

El mecanismo de fábrica de tareas es extensible, por lo que también puede usar los creados por terceros o crear los suyos propios. Un motivo para crear uno sería admitir otro lenguaje para escribir tareas insertadas.

TaskHostFactory

Antes de ejecutar una tarea, MSBuild comprueba si está designada para ejecutarse en el contexto actual del software. De ser así, MSBuild la pasa a AssemblyTaskFactory, que la ejecuta en el proceso actual; de lo contrario, MSBuild pasa la tarea a la TaskHostFactory, que la ejecuta en un proceso que coincida con el contexto de destino. Incluso si el contexto actual y el contexto de destino coinciden, puede forzar que una tarea se ejecute fuera de proceso (por motivos de aislamiento, seguridad, o de otra índole) estableciendo TaskFactory en TaskHostFactory.

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

Cuando se especifica TaskHostFactory explícitamente, el proceso que ejecuta la tarea es de corta duración. Esto permite que el sistema operativo limpie todos los recursos relacionados con la tarea inmediatamente después de que se ejecute. Por este motivo, especifique TaskHostFactory al hacer referencia a las tareas integradas en el mismo proceso de compilación que su uso, para evitar errores de archivo en uso al actualizar el ensamblado de tareas después de una compilación.

RoslynCodeTaskFactory

RoslynCodeTaskFactory proporciona un mecanismo por el que puede escribir código de C# o Visual Basic para una tarea en un archivo de proyecto para su uso inmediato. El código se compila durante el proceso de compilación para generar una tarea que se puede ejecutar en esa misma compilación. El código que escribe tiene como destino .NET Standard, por lo que se puede usar al ejecutar dotnet build, que usa la versión de .NET Core (y .NET 5 y versiones posteriores) de MSBuild, así como msbuild.exe, que usa .NET Framework. RoslynCodeTaskFactory es mejor para la personalización que es un poco demasiado difícil de hacer en la lógica de MSBuild, pero no lo suficientemente compleja como para crear un proyecto independiente. Consulte Creación de una tarea insertada de MSBuild con RoslynCodeTaskFactory.

CodeTaskFactory

CodeTaskFactory es una versión anterior de RoslynCodeTaskFactory que está limitada a la versión de .NET Framework de MSBuild. Consulte Tareas insertadas de MSBuild. Esta factoría de tareas se admite, pero el código más reciente debe usar RoslynCodeTaskFactory para una aplicabilidad más amplia.

Parámetros de tareas fantasma

Al igual que cualquier otro parámetro de tarea, MSBuildRuntime y MSBuildArchitecture se pueden establecer desde las propiedades de compilación.

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

A diferencia de otros parámetros de tarea, MSBuildRuntime y MSBuildArchitecture no son evidentes para la propia tarea. Para escribir una tarea que tenga en cuenta el contexto en el que se ejecuta, debe probar el contexto mediante una llamada a .NET Framework o bien debe usar propiedades de compilación para pasar información de contexto a través de otros parámetros de tarea.

Nota

Es posible establecer atributos UsingTask desde las propiedades del conjunto de herramientas y del entorno.

Los parámetros MSBuildRuntime y MSBuildArchitecture proporcionan la manera más flexible de establecer el contexto de destino, pero también la manera más limitada en cuanto al ámbito. Por un lado, dado que se establecen en la propia instancia de tarea y no se evalúan hasta que la tarea está a punto de ejecutarse, pueden derivar su valor del ámbito completo de propiedades disponibles en tiempo de evaluación y tiempo de compilación. Por otro lado, estos parámetros solo se aplican a una instancia determinada de una tarea en un destino determinado.

Nota

Los parámetros de tareas se evalúan en el contexto del nodo primario, no en el del host de tareas. Las variables de entorno dependientes del tiempo de ejecución o de la arquitectura (por ejemplo, la ubicación Archivos de programa) se evalúan como el valor que coincide con el nodo primario. Pero si la tarea lee directamente la misma variable de entorno, se evaluará correctamente en el contexto del host de la tarea.

Contenido relacionado