dotnet builddotnet build

本文適用於:✓ .NET Core 1.x SDK 及更新版本This article applies to: ✓ .NET Core 1.x SDK and later versions

名稱Name

dotnet build - 建置專案和其所有相依性。dotnet build - Builds a project and all of its dependencies.

概要Synopsis

dotnet build [<PROJECT>|<SOLUTION>] [-c|--configuration] [-f|--framework] [--force] [--interactive] [--no-dependencies]
    [--no-incremental] [--nologo] [--no-restore] [-o|--output] [-r|--runtime] [-v|--verbosity] [--version-suffix]

dotnet build [-h|--help]

說明Description

dotnet build 命令會將專案及其相依性建置成一組二進位檔。The dotnet build command builds the project and its dependencies into a set of binaries. 二進位檔將專案程式碼包含在副檔名為 .dll 的中繼語言 (IL) 檔案中,以及副檔名為 .pdb 且用於偵錯的符號檔。The binaries include the project's code in Intermediate Language (IL) files with a .dll extension and symbol files used for debugging with a .pdb extension. 產生相依性的 JSON 檔案 (*.deps.json),其中列出應用程式的相依性。A dependencies JSON file (*.deps.json) is produced that lists the dependencies of the application. 產生 *.runtimeconfig.json 檔案,其中指定應用程式的共用執行階段及其版本。A *.runtimeconfig.json file is produced, which specifies the shared runtime and its version for the application.

如果專案對於第三方有相依性 (例如來自 NuGet 的程式庫),這些相依性將會從 NuGet 快取解析,而不會透過專案的建置輸出提供。If the project has third-party dependencies, such as libraries from NuGet, they're resolved from the NuGet cache and aren't available with the project's built output. 因此,dotnet build 產生的結果尚未準備好轉移到另一部電腦來執行。With that in mind, the product of dotnet build isn't ready to be transferred to another machine to run. 這與 .NET Framework 的行為相反。在 .NET Framework 中,建置可執行檔專案 (應用程式) 所產生的輸出,可在任何已安裝 .NET Framework 的電腦上執行。This is in contrast to the behavior of the .NET Framework in which building an executable project (an application) produces output that's runnable on any machine where the .NET Framework is installed. 若要在 .NET Core 中擁有類似體驗,您需要使用 dotnet publish 命令。To have a similar experience with .NET Core, you need to use the dotnet publish command. 如需詳細資訊,請參閱 .NET Core 應用程式部署For more information, see .NET Core Application Deployment.

建置會需要 project.assets.json 檔案,其中列出您應用程式的相依性。Building requires the project.assets.json file, which lists the dependencies of your application. 檔案會在 dotnet restore 執行時建立。The file is created when dotnet restore is executed. 如果沒有資產檔案,工具就會因為無法解析參考組件而發生錯誤。Without the assets file in place, the tooling can't resolve reference assemblies, which results in errors. 以前使用 .NET Core 1.x SDK 時,您需要先明確執行 dotnet restore 再執行 dotnet buildWith .NET Core 1.x SDK, you needed to explicitly run the dotnet restore before running dotnet build. 自 .NET Core 2.0 SDK 開始,dotnet restore 會在您執行 dotnet build 時以隱含方式執行。Starting with .NET Core 2.0 SDK, dotnet restore runs implicitly when you run dotnet build. 如果您想要在執行 build 命令時停用隱含還原,您可以跳過 --no-restore 選項。If you want to disable implicit restore when running the build command, you can pass the --no-restore option.

注意

從 .NET Core 2.0 開始,您不需要執行 dotnet restore,因為它是以隱含方式由需要進行還原的所有命令執行,例如 dotnet builddotnet runStarting with .NET Core 2.0, you don't have to run dotnet restore because it's run implicitly by all commands, such as dotnet build and dotnet run, that require a restore to occur. 它在執行明確還原有意義的某些情況下仍然是有效的命令,例如 Azure DevOps Services 中的持續整合組建,或在需要明確控制還原進行時間的建置系統中。It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control the time at which the restore occurs.

此命令也支援以完整形式傳入的 dotnet restore 選項 (例如 --source)。This command also supports the dotnet restore options when passed in the long form (for example, --source). 不支援簡短形式選項,例如 -sShort form options, such as -s, are not supported.

專案是否為可執行檔可透過專案檔中的 <OutputType> 屬性來判斷。Whether the project is executable or not is determined by the <OutputType> property in the project file. 下列範例顯示會產生可執行程式碼的專案:The following example shows a project that produces executable code:

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

若要產生程式庫,只要省略 <OutputType> 屬性即可。To produce a library, omit the <OutputType> property. 建置輸出的主要差別在於,程式庫的 IL DLL 不包含進入點,而且無法執行。The main difference in built output is that the IL DLL for a library doesn't contain entry points and can't be executed.

MSBuildMSBuild

dotnet build 使用 MSBuild 來建置專案,因此同時支援平行和累加建置。dotnet build uses MSBuild to build the project, so it supports both parallel and incremental builds. 如需詳細資訊,請參閱累加建置For more information, see Incremental Builds.

除了其選項,dotnet build 命令也接受 MSBuild 選項,例如用於設定屬性的 -p,以及用於定義記錄器的 -lIn addition to its options, the dotnet build command accepts MSBuild options, such as -p for setting properties or -l to define a logger. 如需這些選項的詳細資訊,請參閱 MSBuild 命令列參考For more information about these options, see the MSBuild Command-Line Reference. 或者,您也可以使用 dotnet msbuild 命令。Or you can also use the dotnet msbuild command.

執行 dotnet build 相當於 dotnet msbuild -restore -target:BuildRunning dotnet build is equivalent to dotnet msbuild -restore -target:Build.

引數Arguments

PROJECT | SOLUTION

要建置的專案或方案檔。The project or solution file to build. 若未指定專案或解決方案檔,MSBuild 會搜尋目前工作目錄中副檔名結尾為 projsln 的檔案,並使用該檔案。If a project or solution file isn't specified, MSBuild searches the current working directory for a file that has a file extension that ends in either proj or sln and uses that file.

選項Options

  • -c|--configuration {Debug|Release}

    定義組建組態。Defines the build configuration. 預設值為 DebugThe default value is Debug.

  • -f|--framework <FRAMEWORK>

    針對特定架構進行編譯。Compiles for a specific framework. 架構必須定義於專案檔中。The framework must be defined in the project file.

  • --force

    即使最後的還原成功,仍強制解析所有相依性。Forces all dependencies to be resolved even if the last restore was successful. 指定這個旗標等同於刪除 project.assets.json 檔案。Specifying this flag is the same as deleting the project.assets.json file. 自 .NET Core 2.0 SDK 起提供使用。Available since .NET Core 2.0 SDK.

  • -h|--help

    印出命令的簡短說明。Prints out a short help for the command.

  • --interactive

    可讓命令停止,並等候使用者輸入或進行動作。Allows the command to stop and wait for user input or action. 例如完成驗證。For example, to complete authentication. 自 .NET Core 3.0 SDK 起提供使用。Available since .NET Core 3.0 SDK.

  • --no-dependencies

    忽略專案對專案 (P2P) 參考,並且只建置指定的根專案。Ignores project-to-project (P2P) references and only builds the specified root project.

  • --no-incremental

    針對累加建置,將建置標示為不安全。Marks the build as unsafe for incremental build. 此旗標會關閉累加編譯,並強制全新重建專案的相依性關係圖。This flag turns off incremental compilation and forces a clean rebuild of the project's dependency graph.

  • --no-logo

    不要顯示程式啟始橫幅或著作權訊息。Doesn't display the startup banner or the copyright message. 自 .NET Core 3.0 SDK 起提供使用。Available since .NET Core 3.0 SDK.

  • --no-restore

    建置期間不會執行隱含還原。Doesn't execute an implicit restore during build. 自 .NET Core 2.0 SDK 起提供使用。Available since .NET Core 2.0 SDK.

  • -o|--output <OUTPUT_DIRECTORY>

    在其中放置已建置的二進位檔的目錄。Directory in which to place the built binaries. 當您指定這個選項時,也需要定義 --frameworkYou also need to define --framework when you specify this option. 如果未指定,則預設路徑為 ./bin/<configuration>/<framework>/If not specified, the default path is ./bin/<configuration>/<framework>/.

  • -r|--runtime <RUNTIME_IDENTIFIER>

    指定目標執行階段。Specifies the target runtime. 如需執行階段識別項 (RID) 清單,請參閱 RID 目錄For a list of Runtime Identifiers (RIDs), see the RID catalog.

  • -v|--verbosity <LEVEL>

    設定 MSBuild 詳細資訊層級。Sets the MSBuild verbosity level. 允許的值為 q[uiet]m[inimal]n[ormal]d[etailed]diag[nostic]Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]. 預設為 minimalThe default is minimal.

  • --version-suffix <VERSION_SUFFIX>

    設定要在建置專案時使用的 $(VersionSuffix) 屬性值。Sets the value of the $(VersionSuffix) property to use when building the project. 這只有在沒有設定 $(Version) 屬性時才能運作。This only works if the $(Version) property isn't set. 接著,$(Version) 會設為 $(VersionPrefix) 加上 $(VersionSuffix),並以破折號區隔。Then, $(Version) is set to the $(VersionPrefix) combined with the $(VersionSuffix), separated by a dash.

範例Examples

  • 建置專案和其相依性:Build a project and its dependencies:

    dotnet build
    
  • 使用發行組態來建置專案和其相依性︰Build a project and its dependencies using Release configuration:

    dotnet build --configuration Release
    
  • 針對特定執行階段,建置專案和其相依性 (在此範例中為 Ubuntu 18.04):Build a project and its dependencies for a specific runtime (in this example, Ubuntu 18.04):

    dotnet build --runtime ubuntu.18.04-x64
    
  • 建置專案,並在還原作業期間使用指定的 NuGet 套件來源 (.NET Core 2.0 SDK 和更新版本):Build the project and use the specified NuGet package source during the restore operation (.NET Core 2.0 SDK and later versions):

    dotnet build --source c:\packages\mypackages
    
  • 建置專案並使用 -p MSBuild 選項 將 1.2.3.4 版設定為組建參數:Build the project and set version 1.2.3.4 as a build parameter using the -p MSBuild option:

    dotnet build -p:Version=1.2.3.4