dotnet builddotnet build

本文适用于: ✔️ .NET Core 2.x SDK 及更高版本This article applies to: ✔️ .NET Core 2.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 <CONFIGURATION>]
    [-f|--framework <FRAMEWORK>] [--force] [--interactive] [--no-dependencies]
    [--no-incremental] [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
    [-r|--runtime <RUNTIME_IDENTIFIER>] [--source <SOURCE>]
    [-v|--verbosity <LEVEL>] [--version-suffix <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) 文件中的项目代码。The binaries include the project's code in Intermediate Language (IL) files with a .dll extension. 根据项目类型和设置,可能会包含其他文件,例如:Depending on the project type and settings, other files may be included, such as:

  • 可用于运行应用程序的可执行文件(如果项目类型是面向 .NET Core 3.0 或更高版本的可执行文件)。An executable that can be used to run the application, if the project type is an executable targeting .NET Core 3.0 or later.
  • 用于调试的扩展名为 .pdb 的符号文件。Symbol files used for debugging with a .pdb extension.
  • 列出了应用程序或库的依赖项的 .deps.json 文件。A .deps.json file, which lists the dependencies of the application or library.
  • 用于指定应用程序的共享运行时及其版本的 .runtimeconfig.json 文件。A .runtimeconfig.json file, which specifies the shared runtime and its version for an application.
  • 项目通过项目引用或 NuGet 包引用所依赖的其他库。Other libraries that the project depends on (via project references or NuGet package references).

对于目标版本低于 .NET Core 3.0 的可执行项目,通常不会将 NuGet 中的库依赖项复制到输出文件夹。For executable projects targeting versions earlier than .NET Core 3.0, library dependencies from NuGet are typically NOT copied to the output folder. 而是在运行时从 NuGet 全局包文件夹中对其进行解析。They're resolved from the NuGet global packages folder at run time. 考虑到这一点,dotnet build 的产品还未准备好转移到另一台计算机进行运行。With that in mind, the product of dotnet build isn't ready to be transferred to another machine to run. 要创建可部署的应用程序版本,需要发布该应用程序(例如,使用 dotnet publish 命令)。To create a version of the application that can be deployed, you need to publish it (for example, with the dotnet publish command). 有关详细信息,请参阅 .NET Core 应用程序部署For more information, see .NET Core Application Deployment.

对于面向 .NET Core 3.0 及更高版本的可执行项目,库依赖项会被复制到输出文件夹。For executable projects targeting .NET Core 3.0 and later, library dependencies are copied to the output folder. 这意味着如果没有其他任何特定于发布的逻辑(例如,Web 项目具有的逻辑),则应可部署生成输出。This means that if there isn't any other publish-specific logic (such as Web projects have), the build output should be deployable.

隐式还原Implicit restore

构建需要 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.

无需运行 dotnet restore,因为它由所有需要还原的命令隐式运行,如 dotnet newdotnet builddotnet rundotnet testdotnet publishdotnet packYou don't have to run dotnet restore because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish, and dotnet pack. 若要禁用隐式还原,请使用 --no-restore 选项。To disable implicit restore, use the --no-restore option.

在执行显式还原有意义的某些情况下,例如 Azure DevOps Services 中的持续集成生成中,或在需要显式控制还原发生时间的生成系统中,dotnet restore 命令仍然有用。The dotnet restore command is still useful in certain scenarios where explicitly restoring makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control when the restore occurs.

有关如何使用 NuGet 源的信息,请参阅 dotnet restore 文档For information about how to manage NuGet feeds, see the dotnet restore documentation.

以长格式传入时,此命令支持 dotnet restore 选项(例如,--source)。This command supports the dotnet restore options when passed in the long form (for example, --source). 不支持缩写选项,例如 -sShort form options, such as -s, are not supported.

可执行文件或库输出Executable or library output

项目是否可执行由项目文件中的 <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> 属性或将其值更改为 LibraryTo produce a library, omit the <OutputType> property or change its value to Library. 库的 IL DLL 不包含入口点,因此无法执行。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;但是,输出的默认详细程度不同。Running dotnet build is equivalent to running dotnet msbuild -restore; however, the default verbosity of the output is different.

自变量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 <CONFIGURATION>

    定义生成配置。Defines the build configuration. 大多数项目的默认配置为 Debug,但你可以覆盖项目中的生成配置设置。The default for most projects is Debug, but you can override the build configuration settings in your project.

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

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

    在生成期间不执行隐式还原。Doesn't execute an implicit restore during build.

  • --nologo

    不显示启动版权标志或版权消息。Doesn't display the startup banner or the copyright message. 自 .NET Core 3.0 SDK 起可用。Available since .NET Core 3.0 SDK.

  • -o|--output <OUTPUT_DIRECTORY>

    放置生成二进制文件的目录。Directory in which to place the built binaries. 如果未指定,则默认路径为 ./bin/<configuration>/<framework>/If not specified, the default path is ./bin/<configuration>/<framework>/. 对于具有多个目标框架的项目(通过 TargetFrameworks 属性),在指定此选项时还需要定义 --frameworkFor projects with multiple target frameworks (via the TargetFrameworks property), you also need to define --framework when you specify this option.

  • -r|--runtime <RUNTIME_IDENTIFIER>

    指定目标运行时。Specifies the target runtime. 有关运行时标识符 (RID) 的列表,请参阅 RID 目录For a list of Runtime Identifiers (RIDs), see the RID catalog.

  • --source <SOURCE>

    要在还原操作期间使用的 NuGet 包源的 URI。The URI of the NuGet package source to use during the restore operation.

  • -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
    
  • 生成项目并设置版本 1.2.3.4 作为使用 -p MSBuild 选项的生成参数: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