UsingTask 元素 (MSBuild)

  • 项目

将 Task 元素中引用的任务映射到包含该任务实现的程序集。

<Project><UsingTask>

语法

<UsingTask TaskName="TaskName"
    AssemblyName = "AssemblyName"
    TaskFactory = "ClassName"
    Condition="'String A'=='String B'" />

注意

不同于属性和项，将使用应用于 TaskName 的第一个UsingTask 元素；若要覆盖任务，必须在现有任务之前定义一个新的 UsingTask，或在新 UsingTask 中指定 Override="true"。

特性和元素

下列各节描述了特性、子元素和父元素。

特性

属性 描述
Architecture 可选特性。

指定任务必须在指定位数的进程中运行。 如果当前进程不满足要求，则任务将在满足要求的任务主机进程中运行。

支持的值为 x86（32 位）、x64（64 位）、CurrentArchitecture 和 *（任何体系结构）。
AssemblyName AssemblyName 属性或 AssemblyFile 属性是必需的。

要加载的程序集的名称。 尽管强命名不是必需的，但是 AssemblyName 属性可以接受强名称程序集。 使用此属性等效于使用 .NET 中的 Load 方法加载程序集。

如果使用了 AssemblyFile 属性，则不能使用此属性。
AssemblyFile AssemblyName 或 AssemblyFile 属性是必需的。

程序集的文件路径。 此属性接受完整路径或相对路径。 相对路径是相对于声明 UsingTask 元素的项目文件或目标文件的目录位置而言的。 使用此属性等效于使用 .NET 中的 LoadFrom 方法加载程序集。

如果使用了 AssemblyName 属性，则不能使用此属性。
Override 可选特性。

指定此 UsingTask 元素的优先级应高于定义相同任务名称的其他元素。 每个任务名称只允许一次替代。 已在 MSBuild 17.2 中添加。
Runtime 可选属性。

指定该任务必须在指定版本的 .NET Framework 运行时中运行。 如果当前进程不满足要求，则任务将在满足要求的任务主机进程中运行。

支持的值为“NET”（.NET Core 和 .NET 5 或更高版本）、CLR2 (.NET Framework 3.5)、CLR4（.NET Framework 4.7.2 或更高版本）、CurrentRuntime 和 *（任何运行时）。 请注意，当你运行.NET Framework (CLR4) MSBuild 时，无法调用 NET 任务，并且无法从 .NET MSBuild（正在运行 dotnet build 时）调用 CLR2/CLR4 任务。
TaskFactory 可选特性。

在负责生成指定 Task 名称的实例的程序集中指定类。 用户还可以将 Task 指定为任务工厂接收并用于生成任务的子元素。 Task 的内容特定于任务工厂。 默认值 TaskFactory 为 AssemblyTaskFactory，这会将任务加载到正在运行的进程中。
TaskName 必需的特性。

要从程序集中引用的任务的名称。 如果可能存在多义性，则此属性应始终指定完整命名空间。 如果存在多义性，则 MSBuild 将选择任意匹配项，该匹配项可能产生意外结果。
Condition 可选特性。

要计算的条件。 有关详细信息，请参阅条件。

子元素

元素 描述
ParameterGroup 参数集，在指定 TaskFactory 生成的任务中显示。
任务 传递给 TaskFactory 的数据，用于生成任务的实例。

父元素

元素 描述
Project MSBuild 项目文件必需的根元素。

备注

UsingTask 元素（该元素直接进入或通过导入项目文件而包括在项目文件中）可以引用环境变量、命令行属性、项目级属性及项目级项。 有关详细信息，请参阅任务。

注意

如果 UsingTask 元素来自使用 MSBuild 引擎进行全局注册的某个 .tasks 文件，则项目级属性和项没有意义。 项目级值对于 MSBuild 而言不是全局性的。

在 MSBuild 4.0 中，可以从 .overridetask 文件加载 using 任务。

第一次使用 Task 时，将加载包含自定义任务的程序集。

示例 1

下面的示例演示如何将 UsingTask 元素和 AssemblyFile 属性结合使用。

<UsingTask TaskName="Email"
           AssemblyFile="c:\myTasks\myTask.dll" />

由于没有指定 Runtime 或 TaskHost，该任务将在运行给定构建的时候发生的 MSBuild 进程中执行，并会根据当前的运行时和架构来进行。

示例 2

以下示例演示如何将 UsingTask 元素与该程序集中定义的 AssemblyName 属性和自定义 TaskFactory 一起使用。

<UsingTask TaskName="MyTask" AssemblyName="My.Assembly" TaskFactory="MyTaskFactory">
       <ParameterGroup>
              <Parameter1 ParameterType="System.String" Required="False" Output="False"/>
              <Parameter2 ParameterType="System.Int" Required="True" Output="False"/>
              ...
</ParameterGroup>
       <Task>
      ... Task factory-specific data ...
       </Task>
</UsingTask>

另请参阅