dotnet build

  • 發行項

本文適用於： ✔️ .NET Core 3.1 SDK 與更新版本

名稱

dotnet build - 建置專案和其所有相依性。

概要

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
    [--disable-build-servers]
    [--force] [--interactive] [--no-dependencies] [--no-incremental]
    [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>]
    [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] [--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet build -h|--help

描述

dotnet build 命令會將專案及其相依性建置成一組二進位檔。 二進位檔包含中繼語言 (IL) 檔案 (副檔名為 .dll) 的專案程式碼。 視專案類型和設定而定，可能會包含其他檔案，例如：

  • 可以用來執行應用程式的可執行檔 (如果專案類型是以 .NET Core 3.0 或更新版本為目標的可執行檔)。
  • 用於進行偵錯工具的符號檔 (副檔名為 .pdb)。
  • .deps.json 檔案，其會列出應用程式或程式庫的相依性。
  • .runtimeconfig.json 檔案，可指定共用的執行階段及應用程式的版本。
  • 專案相依的其他程式庫 (透過專案參考或 NuGet 封裝參考)。

針對以 .NET Core 3.0 之前版本為目標的可執行檔專案，NuGet 的程式庫相依性通常不會複製到輸出檔案夾。 會在執行階段從 NuGet 全域套件資料夾解析這些項目。 因此，dotnet build 產生的結果尚未準備好轉移到另一部電腦來執行。 若要建立可部署的應用程式版本，您需要進行發佈 (例如，使用 dotnet publish 命令)。 如需詳細資訊，請參閱 .NET 應用程式部署。

針對以 .NET Core 3.0 和更新版本為目標的可執行專案，程式庫相依性會複製到輸出檔案夾。 這表示如果沒有任何其他發佈特定邏輯 (例如 Web 專案)，則應該可部署組建輸出。

隱含還原

建置會需要 project.assets.json 檔案，其中列出您應用程式的相依性。 檔案會在 dotnet restore 執行時建立。 如果沒有資產檔案，工具就會因為無法解析參考組件而發生錯誤。

您不必執行 dotnet restore，因為其會由需要進行還原的所有命令隱含執行，例如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要停用隱含還原，請使用 --no-restore 選項。

dotnet restore 命令在適合進行明確還原的特定案例中仍可派上用場，例如 Azure DevOps Services 中的持續整合組建，或在需要明確控制何時進行還原的組建系統中。

如需了解如何管理 NuGet 摘要，請參閱 dotnet restore 文件。

此命令支援以完整形式傳入的 dotnet restore 選項 (例如 --source)。 不支援簡短形式選項，例如 -s。

可執行檔或程式庫輸出

專案是否為可執行檔可透過專案檔中的 <OutputType> 屬性來判斷。 下列範例顯示會產生可執行程式碼的專案：

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

若要產生程式庫，請省略 <OutputType> 屬性，或將其值變更為 Library。 程式庫的 IL DLL 不包含進入點，而且無法執行。

MSBuild

dotnet build 使用 MSBuild 來建置專案，因此同時支援平行和累加建置。 如需詳細資訊，請參閱累加建置。

除了其選項，dotnet build 命令也接受 MSBuild 選項，例如用於設定屬性的 -p，以及用於定義記錄器的 -l。 如需這些選項的詳細資訊，請參閱 MSBuild 命令列參考。 或者，您也可以使用 dotnet msbuild 命令。

注意

當由 dotnet run 自動執行 dotnet build 時，不會遵守 -property:property=value 之類的引數。

執行 dotnet build 相當於執行 dotnet msbuild -restore；不過，輸出的預設詳細資訊不同。

工作負載資訊清單下載作業

執行此命令會啟動工作負載公告資訊清單的非同步背景下載。 若此命令完成時下載仍在執行，則會停止下載。 如需詳細資訊，請參閱廣告資訊清單。

引數

PROJECT | SOLUTION

要建置的專案或方案檔。 若未指定專案或解決方案檔，MSBuild 會搜尋目前工作目錄中副檔名結尾為 proj 或 sln 的檔案，並使用該檔案。

選項。

  • -a|--arch <ARCHITECTURE>

    指定目標結構。 這是用於設定執行階段識別碼 (RID) 的速記語法，其中提供的值會與預設 RID 合併。 例如在 win-x64 機器上，指定 --arch x86 將 RID 設定為 win-x86。 若使用此選項，請勿使用 -r|--runtime 選項。 自 .NET 6 Preview 7 起提供使用。

  • -c|--configuration <CONFIGURATION>

    定義組建組態。 大部分專案的預設值為 Debug，但您可以覆寫專案中的組建組態設定。

  • --disable-build-servers

    強制命令忽略任何持續性組建伺服器。 此選項提供一致的方式來停用所有建置快取的使用，以強制從頭開始建置。 當快取可能因某些原因而損毀或不正確時，不依賴快取的組建很有用。 自 .NET 7 SDK 起提供使用。

  • -f|--framework <FRAMEWORK>

    針對特定架構進行編譯。 架構必須定義於專案檔中。 例如：net7.0、net462。

  • --force

    即使最後的還原成功，仍強制解析所有相依性。 指定這個旗標等同於刪除 project.assets.json 檔案。

  • -?|-h|--help

    列印如何使用命令的描述。

  • --interactive

    可讓命令停止，並等候使用者輸入或進行動作。 例如完成驗證。 自 .NET Core 3.0 SDK 起提供使用。

  • --no-dependencies

    忽略專案對專案 (P2P) 參考，並且只建置指定的根專案。

  • --no-incremental

    針對累加建置，將建置標示為不安全。 此旗標會關閉累加編譯，並強制全新重建專案的相依性關係圖。

  • --no-restore

    建置期間不會執行隱含還原。

  • --nologo

    不要顯示程式啟始橫幅或著作權訊息。

  • --no-self-contained

    將應用程式發佈為架構相依應用程式。 相容的 .NET 執行階段必須安裝在目標機器上，才能執行應用程式。 自 .NET 6 SDK 起提供使用。

  • -o|--output <OUTPUT_DIRECTORY>

    在其中放置已建置的二進位檔的目錄。 如果未指定，則預設路徑為 ./bin/<configuration>/<framework>/。 針對具有多個目標 Framework 的專案 (透過 TargetFrameworks 屬性)，您在指定此選項時也必須定義 --framework。

    • .NET 7.0.200 SDK 和更新版本

      如果您在解決方案上執行此命令時指定 --output 選項，則 CLI 將會因輸出路徑語意不清楚而發出警告 (7.0.200 中的錯誤)。 不允許 --output 選項，因為所有已建置專案的所有輸出都會複製至指定的目錄，而這與多目標專案以及具有不同直接和可轉移相依性版本的專案都不相容。 如需詳細資訊，請參閱解決方案層級的 --output 選項不再適用組建相關命令。

  • --os <OS>

    指定目標作業系統 (OS)。 這是用於設定執行階段識別碼 (RID) 的速記語法，其中提供的值會與預設 RID 合併。 例如在 win-x64 機器上，指定 --os linux 將 RID 設定為 linux-x64。 若使用此選項，請勿使用 -r|--runtime 選項。 自 .NET 6 起提供使用。

  • -p|--property:<PROPERTYNAME>=<VALUE>

    設定一個或多個 MSBuild 屬性。 指定以分號分隔的多個屬性，或重複選項：

    --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>

  • -r|--runtime <RUNTIME_IDENTIFIER>

    指定目標執行階段。 如需執行階段識別項 (RID) 清單，請參閱 RID 目錄。 如果您搭配 .NET 6 SDK 使用此選項，也請使用 --self-contained 或 --no-self-contained。 如果未指定，預設值是針對目前的 OS 和結構進行建置。

  • --self-contained [true|false]

    使用應用程式發佈 .NET 執行階段，這樣一來目標機器便不需要安裝執行階段。 如果指定執行階段識別碼，則預設值為 true。 自 .NET 6 起提供使用。

  • --source <SOURCE>

    在還原作業期間使用的 NuGet 套件來源 URI。

  • --tl:[auto|on|off]

    指定終端記錄器是否應該用於組建輸出。 預設值為 auto，這會先驗證環境，再啟用終端記錄。 環境檢查會驗證終端是否能夠使用新式輸出功能，而且在啟用新的記錄器之前，不會使用重新導向的標準輸出。 on 略過環境檢查並啟用終端記錄。 off 略過環境檢查並使用預設控制台記錄器。

    終端記錄器會顯示還原階段，後面接著建置階段。 在每個階段，目前建置的專案會出現在終端底部。 建置的每個專案都會輸出目前建置的 MSBuild 目標，以及花費在該目標上的時間量。 您可以搜尋此資訊以深入了解組建。 當專案完成建置時，撰寫了單一「已完成建置」區段來擷取：

    • 所建置專案的名稱。
    • 目標架構 (如果為多目標)。
    • 該組建的狀態。
    • 該組建的主要輸出 (已有超連結)。
    • 任何針對該專案產生的診斷。

    此選項從 .NET 8 開始提供使用。

  • -v|--verbosity <LEVEL>

    設定命令的詳細資訊層級。 允許的值為 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。 預設值為 minimal。 根據預設，MSBuild 會顯示所有詳細資訊層級的警告和錯誤。 若要排除警告，請使用 /property:WarningLevel=0。 如需詳細資訊，請參閱 LoggerVerbosity 和 WarningLevel。

  • --use-current-runtime, --ucr [true|false]

    在其中一台機器上，將 RuntimeIdentifier 設定為平台可攜 RuntimeIdentifier。 這會與需要 RuntimeIdentifier 的屬性 (例如 SelfContained、PublishAot、PublishSelfContained、PublishSingleFile 與 PublishReadyToRun) 一起隱含執行。 若此屬性設為 False，隱含解析就再也不會執行。

  • --version-suffix <VERSION_SUFFIX>

    設定要在建置專案時使用的 $(VersionSuffix) 屬性值。 這只有在沒有設定 $(Version) 屬性時才能運作。 接著，$(Version) 會設為 $(VersionPrefix) 加上 $(VersionSuffix)，並以破折號區隔。

範例

  • 建置專案和其相依性：

    dotnet build

  • 使用發行組態來建置專案和其相依性︰

    dotnet build --configuration Release

  • 針對特定運行時間建置專案及其相依性（在此範例中為Linux）：

    dotnet build --runtime linux-x64

  • 建置專案，並在還原作業期間使用指定的 NuGet 套件來源：

    dotnet build --source c:\packages\mypackages

  • 建置專案並使用 -pMSBuild 選項 將 1.2.3.4 版設定為組建參數：

    dotnet build -p:Version=1.2.3.4