UsingTask 元素 (MSBuild)

  • 發行項

將 Task 元素中參考的工作對應至包含工作實作的組件。

<專案><UsingTask>

Syntax

<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 呼叫 CLR2/CLR4 工作(執行 dotnet build 時)。
TaskFactory 選用屬性。

指定組件中的類別，該組件負責產生指定 Task 名稱的執行個體。 使用者也可以指定 Task 做為子項目，工作 Factory 會接收並用來產生工作。 Task 的內容專屬於工作 Factory。 預設值 TaskFactory 為 AssemblyTaskFactory，它會將工作載入執行中的進程。
TaskName 必要屬性。

從組件參考之工作的名稱。 如果可能會有模稜兩可的情況，這個屬性應該一律指定完整的命名空間。 如果有模稜兩可的情況，MSBuild 會選擇任意的相符項目，這樣可能會產生非預期的結果。
Condition 選用屬性。

要評估的條件。 如需詳細資訊，請參閱條件。

子元素

元素 描述
ParameterGroup 在指定的 TaskFactory 產生之工作上顯示的參數集。
Task 傳遞至 TaskFactory 以產生工作之執行個體的資料。

父元素

元素 描述
計畫 MSBuild 專案檔的必要根項目。

備註

您可以在專案檔所包含 (直接包含或透過匯入的專案檔來包含) 的 UsingTask 元素中，參考環境變數、命令列屬性、專案層級屬性及專案層級項目。 如需詳細資訊，請參閱工作。

注意

如果 UsingTask 元素來自已經向 MSBuild 引擎全域註冊的其中一個 .tasks 檔案，則專案層級屬性和項目沒有任何意義。 專案層級值對 MSBuild 而言不是全域的。

在 MSBuild 4.0 中，使用工作可以從 .overridetask 檔案載入。

第一次使用 Task 時，會載入包含自訂工作的元件。

範例 1

下列範例示範如何使用具有 AssemblyFile 屬性的 UsingTask 項目。

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

另請參閱