通过

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 命令的输出已准备好部署到托管系统（例如服务器、电脑、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，该 MSBuild 调用 Publish 目标。 如果 IsPublishable 属性 设置为特定项目的 false，则无法调用 Publish 目标，dotnet publish 命令仅对项目运行隐式 dotnet 还原。

传递给 dotnet publish 的任何参数都传递给 MSBuild。 -c 和 -o 参数分别映射到 MSBuild 的 Configuration 和 PublishDir 属性。

dotnet publish 命令接受 MSBuild 选项，例如用于设置属性和 -l 来定义记录器 -p。 例如，可以使用以下格式设置 MSBuild 属性：-p:<NAME>=<VALUE>。

.pubxml 文件

还可以通过引用 .pubxml 文件来设置与发布相关的属性。 例如：

dotnet publish -p:PublishProfile=FolderProfile

前面的示例使用 <project_folder>/Properties/PublishProfiles 文件夹中找到的 FolderProfile.pubxml 文件。 如果在设置 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 是预先编译（AOT）的一种形式。 有关详细信息，请参阅 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 预览版 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，并且运行 dotnet publish 两次，则第二次运行会将内容文件（如 .config 和 .json 文件）放在 myproject/publish/publish中。 为了避免嵌套发布文件夹，请指定不直接在项目文件夹下 的发布文件夹，或从项目中排除发布文件夹。 若要排除名为 publishoutput的发布文件夹，请将以下元素添加到 .csproj 文件中 元素：

    <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 应用程序发布，使用 .NET CLI发布 .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 应用程序发布，使用 .NET CLI发布 .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

另请参阅