dotnet build

本文适用于： ✔️ .NET Core 3.1 SDK 及更高版本

“属性”

dotnet build - 生成项目及其所有依赖项。

摘要

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-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 命令将项目及其依赖项生成为一组二进制文件。 二进制文件包括扩展名为 .dll 的中间语言 (IL) 文件中的项目代码。 根据项目类型和设置，可能会包含其他文件，例如：

• 可用于运行应用程序的可执行文件（如果项目类型是面向 .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中，或在需要显式控制还原发生时间的生成系统中，dotnet restore 命令仍然有用。

有关如何使用 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 build 由 dotnet run 自动运行，则不遵守 -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 开始提供。

• --artifacts-path <ARTIFACTS_DIR>

  执行命令中的所有生成输出文件都将位于指定路径下的子文件夹中，由项目分隔。 有关详细信息，请参阅 Artifacts 输出布局。 自 .NET 8 SDK 起可用。

• -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>/。 对于具有多个目标框架的项目（通过 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 和警告级别。

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

• 生成项目并设置版本 1.2.3.4 作为使用 -p MSBuild 选项的生成参数：

  dotnet build -p:Version=1.2.3.4