共用方式為

dotnet publish

  • 發行項

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

名字

dotnet publish - 將應用程式及其相依性發佈至部署至主控系統的資料夾。

概要

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

dotnet publish -h|--help

描述

dotnet publish 編譯應用程式、讀取其在項目檔中指定的相依性，並將產生的檔案集發佈至目錄。 輸出包含下列資產：

  • 元件中具有 dll 延伸模組的中繼語言 （IL） 程序代碼。
  • 包含專案所有相依性的 .deps.json 檔案。
  • .runtimeconfig.json 檔案，指定應用程式預期的共用運行時間，以及運行時間的其他組態選項（例如垃圾收集類型）。
  • 從 NuGet 快取複製到輸出資料夾的應用程式相依性。

dotnet publish 命令的輸出已準備好部署至主控系統（例如伺服器、PC、Mac、膝上型電腦）來執行。 這是準備應用程式以進行部署的唯一正式支援方式。 視專案指定的部署類型而定，主控系統可能或可能不會安裝 .NET 共用運行時間。 如需詳細資訊，請參閱 使用 .NET CLI發行 .NET 應用程式。

隱含還原

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

命令在明確還原的某些案例中仍然很有用，例如在 Azure DevOps Services 或需要明確控制還原時機的建置系統中 持續整合組建。

如需如何管理 NuGet 摘要的資訊，請參閱 dotnet restore 檔案。

MSBuild

dotnet publish 命令會呼叫 MSBuild，以叫用 Publish 目標。 如果 IsPublishable 屬性 設定為特定專案的 false，則無法叫用 Publish 目標，而且 dotnet publish 命令只會在專案上執行隱含的 dotnet restore。

傳遞至 dotnet publish 的任何參數會傳遞至 MSBuild。 -c 和 -o 參數分別對應至 MSBuild 的 Configuration 和 PublishDir 屬性。

dotnet publish 命令接受 MSBuild 選項，例如設定屬性和 -l 來定義記錄器 -p。 例如，您可以使用 下列格式來設定 MSBuild 屬性：-p:<NAME>=<VALUE>。

.pubxml 檔案

您也可以參考 .pubxml 檔案來設定發行相關屬性。 例如：

dotnet publish -p:PublishProfile=FolderProfile

上述範例使用 FolderProfile.pubxml 檔案，該檔案位於 <project_folder>/Properties/PublishProfiles 資料夾中。 如果您在設定 PublishProfile 屬性時指定路徑和擴展名，則會忽略它們。 MSBuild 預設會在 Properties/PublishProfiles 資料夾中尋找，並假設 pubxml 擴展名。 若要指定路徑和檔名，包括擴展名，請設定 PublishProfileFullPath 屬性，而不是 PublishProfile 屬性。

在 .pubxml 檔案中：

  • Visual Studio 會使用 PublishUrl 來表示發佈目標。
  • CLI 會使用 PublishDir 來表示發佈目標。

如果您想要讓案例在所有位置運作，您可以將這兩個屬性初始化為 .pubxml 檔案中的相同值。 當 GitHub 問題 dotnet/sdk#20931 解決時，只需要設定其中一個屬性。

.pubxml 檔案中的某些屬性只會受到 Visual Studio 的接受，而且對 dotnet publish沒有任何作用。 我們正努力讓 CLI 更符合 Visual Studio 的行為。 但 CLI 永遠不會使用某些屬性。 CLI 和 Visual Studio 都執行發佈的封裝層面，dotnet/sdk#29817 計劃新增更多相關屬性的支援。 但是 CLI 不會執行發布的部署自動化層面，也不會支援與發布相關的屬性。 dotnet publish 不支援的最值得注意 .pubxml 屬性是下列會影響組建的屬性：

  • LastUsedBuildConfiguration
  • Configuration
  • Platform
  • LastUsedPlatform
  • TargetFramework
  • TargetFrameworks
  • RuntimeIdentifier
  • RuntimeIdentifiers

MSBuild 屬性

下列 MSBuild 屬性會變更 dotnet publish的輸出。

  • PublishReadyToRun

    將應用程式元件編譯為 ReadyToRun （R2R） 格式。 R2R 是預先編譯的一種形式。 如需詳細資訊，請參閱 ReadyToRun 映射。

    若要檢視可能導致執行時間失敗之遺漏相依性的警告，請使用 PublishReadyToRunShowWarnings=true。

    建議您在發行配置檔中指定 PublishReadyToRun，而不是在命令行上指定。

  • PublishSingleFile

    將應用程式封裝成平臺特定的單一檔案可執行檔。 如需單一檔案發佈的詳細資訊，請參閱單一檔案套件組合器設計檔。

    建議您在項目檔中指定此選項，而不是在命令行上指定此選項。

  • PublishTrimmed

    修剪未使用的連結庫，以在發佈獨立可執行檔時減少應用程式的部署大小。 如需詳細資訊，請參閱 修剪獨立式部署和可執行檔案。 自 .NET 6 SDK 起提供。

    建議您在項目檔中指定此選項，而不是在命令行上指定此選項。

如需詳細資訊，請參閱下列資源：

工作負載指令清單下載

當您執行此命令時，它會起始工作負載廣告指令清單的異步背景下載。 如果此命令完成時仍在執行下載，則會停止下載。 如需詳細資訊，請參閱廣告指令清單。

參數

  • PROJECT|SOLUTION

    要發佈的專案或方案。

    • PROJECT 是 C#、F# 或 Visual Basic 專案檔的路徑和檔名，或是包含 C#、F# 或 Visual Basic 專案檔之目錄的路徑。 如果未指定目錄，則會預設為目前目錄。

    • SOLUTION 是方案檔的路徑和檔名（.sln 擴展名），或包含方案檔的目錄路徑。 如果未指定目錄，則會預設為目前目錄。

選項

  • -a|--arch <ARCHITECTURE>

    指定目標架構。 這是設定 運行時間標識碼 （RID）的速記語法，其中提供的值會與預設 RID 結合。 例如，在 win-x64 電腦上，指定 --arch x86 將 RID 設定為 win-x86。 如果您使用此選項，請勿使用 [-r|--runtime] 選項。 自 .NET 6 Preview 7 起提供。

  • --artifacts-path <ARTIFACTS_DIR>

    執行命令的所有建置輸出檔案都會位於指定路徑下的子資料夾中，並以專案分隔。 如需詳細資訊，請參閱 成品輸出配置。 自 .NET 8 SDK 起提供。

  • -c|--configuration <CONFIGURATION>

    定義組建組態。 如果您要使用 .NET 8 SDK 或更新版本進行開發，此命令預設會針對 TargetFramework 設為 net8.0 或更新版本的專案使用 Release 組態。 舊版 SDK 和舊版目標架構的預設組建組態 Debug。 您可以在項目設定中覆寫預設值，或使用此選項。 如需詳細資訊，請參閱 'dotnet publish' 使用發行組態，'dotnet pack' 使用發行組態。

  • --disable-build-servers

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

  • -f|--framework <FRAMEWORK>

    發行指定 目標架構的應用程式。 您必須在項目檔中指定目標架構。

  • --force

    強制解析所有相依性，即使上次還原成功也一樣。 指定此旗標與刪除 project.assets.json 檔案相同。

  • -?|-h|--help

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

  • --interactive

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

  • --manifest <PATH_TO_MANIFEST_FILE>

    指定一或多個 目標指令清單， 用來修剪與應用程式一起發佈的套件集。 指令清單檔是 dotnet store 指令輸出的一部分，。 若要指定多個指令清單，請為每個指令清單新增 --manifest 選項。

  • --no-build

    在發佈之前不會建置專案。 它也會隱含地設定 --no-restore 旗標。

  • --no-dependencies

    忽略專案對項目參考，而且只會還原根專案。

  • --nologo

    不會顯示啟動橫幅或著作權訊息。

  • --no-restore

    執行 命令時，不會執行隱含還原。

  • -o|--output <OUTPUT_DIRECTORY>

    指定輸出目錄的路徑。

    如果未指定，它預設為 [project_file_folder]/bin/[configuration]/[framework]/publish/ 架構相依可執行檔和跨平臺二進制檔。 它預設為 [project_file_folder]/bin/[configuration]/[framework]/[runtime]/publish/ 獨立可執行檔。

    在 Web 專案中，如果輸出資料夾位於專案資料夾中，後續 dotnet publish 命令會導致巢狀輸出資料夾。 例如，如果專案資料夾 myproject，而發佈輸出資料夾 myproject/publish，而您執行 兩次，則第二次執行會將 .config 和 .json 檔案等內容檔案放在 myproject/publish/publish中。 若要避免巢狀發佈資料夾，請指定未直接 項目資料夾底下 的發行資料夾，或從專案排除發行資料夾。 若要排除名為 publishoutput的 publish 資料夾，請將下列元素新增至 .csproj 檔案中的 PropertyGroup 元素：

    <DefaultItemExcludes>$(DefaultItemExcludes);publishoutput**</DefaultItemExcludes>

    • .NET 7.0.200 SDK 和更新版本

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

    • .NET Core 3.x SDK 和更新版本

      如果您在發佈專案時指定相對路徑，產生的輸出目錄會相對於目前的工作目錄，而不是項目檔位置。

      如果您在發佈方案時指定相對路徑，則所有項目的輸出都會進入相對於目前工作目錄的指定資料夾。 若要讓發行輸出移至每個項目的個別資料夾，請使用 msbuild PublishDir 屬性指定相對路徑，而不是 --output 選項。 例如，dotnet publish -p:PublishDir=.\publish 將每個專案的發行輸出傳送至包含專案檔的資料夾下 publish 資料夾。

    • .NET Core 2.x SDK

      如果您在發佈專案時指定相對路徑，產生的輸出目錄會相對於項目檔位置，而不是目前的工作目錄。

      如果您在發佈方案時指定相對路徑，則每個項目的輸出都會進入相對於項目檔位置的個別資料夾。 如果您在發佈方案時指定絕對路徑，則所有專案的發佈輸出都會進入指定的資料夾。

  • --os <OS>

    指定目標作業系統 （OS）。 這是設定 運行時間標識碼 （RID）的速記語法，其中提供的值會與預設 RID 結合。 例如，在 win-x64 電腦上，指定 --os linux 將 RID 設定為 linux-x64。 如果您使用此選項，請勿使用 [-r|--runtime] 選項。 自 .NET 6 起提供。

  • --sc|--self-contained [true|false]

    使用您的應用程式發佈 .NET 運行時間，讓運行時間不需要安裝在目標計算機上。 如果指定運行時間標識碼，且專案是可執行的專案（而非連結庫專案），則預設值為 true。 如需詳細資訊，請參閱使用 .NET CLI.NET 應用程式發行 和 發佈 .NET 應用程式。

    如果使用這個選項而不指定 true 或 false，則預設值為 true。 在此情況下，請勿在 --self-contained之後立即放置方案或專案自變數，因為 true 或 false 預期在該位置。

  • --no-self-contained

    相當於 --self-contained false。

  • --source <SOURCE>

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

  • -r|--runtime <RUNTIME_IDENTIFIER>

    發佈指定運行時間的應用程式。 如需執行時間識別碼清單（RID），請參閱 RID 目錄。 如需詳細資訊，請參閱使用 .NET CLI.NET 應用程式發行 和 發佈 .NET 應用程式。 如果您使用此選項，請使用 --self-contained 或 --no-self-contained。

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

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

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

    • 建置項目的名稱。
    • 目標架構（如果多目標）。
    • 該組建的狀態。
    • 該組建的主要輸出（已超連結）。
    • 針對該項目產生的任何診斷。

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

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

    根據其中一部計算機，將 RuntimeIdentifier 設定為平臺可攜式 RuntimeIdentifier。 這與需要 RuntimeIdentifier的屬性隱含發生，例如 SelfContained、PublishAot、PublishSelfContained、PublishSingleFile和 PublishReadyToRun。 如果屬性設定為 false，則不會再發生隱含解析。

  • -v|--verbosity <LEVEL>

    設定命令的詳細資訊層級。 允許的值為 q[uiet]、m[inimal]、n[ormal]、d[etailed]與 diag[nostic]。 預設值為 minimal。 如需詳細資訊，請參閱 LoggerVerbosity。

  • --version-suffix <VERSION_SUFFIX>

    定義版本後綴，以取代項目檔版本欄位中的星號 （*）。

例子

  • 為目前目錄中的專案建立 架構相依的跨平臺二進位：

    dotnet publish

    從 .NET Core 3.0 SDK 開始，此範例也會為目前平臺建立 架構相依的可執行檔。

  • 針對特定運行時間，為目前目錄中的專案建立 獨立可執行檔：

    dotnet publish --runtime osx-x64

    RID 必須位於項目檔中。

  • 針對特定平臺，為目前目錄中的專案建立 架構相依的可執行檔：

    dotnet publish --runtime osx-x64 --self-contained false

    RID 必須位於項目檔中。 此範例適用於 .NET Core 3.0 SDK 和更新版本。

  • 針對特定運行時間和目標架構，發佈目前目錄中的專案：

    dotnet publish --framework net8.0 --runtime osx-x64

  • 發佈指定的項目檔：

    dotnet publish ~/projects/app1/app1.csproj

  • 發佈目前的應用程式，但不還原專案對專案 （P2P） 參考，只是還原作業期間的根專案：

    dotnet publish --no-dependencies

另請參閱