使用 .NET CLI 发布 .NET 应用

本文展示了如何使用命令行来发布 .NET 应用程序。 .NET 提供了三种发布应用程序的方法。 依赖于框架的部署会生成一个跨平台 .dll 文件,此文件使用本地安装的 .NET 运行时。 依赖于框架的可执行文件会生成一个特定于平台的可执行文件,此文件使用本地安装的 .NET 运行时。 独立式可执行文件会生成一个特定于平台的可执行文件,并包含 .NET 运行时的本地副本。

有关这些发布模式的概述,请参阅 .NET 应用程序部署

正在查找有关 CLI 的快速帮助? 下表列出了一些关于如何发布应用的示例。 可以使用 -f <TFM> 参数或通过编辑项目文件来指定目标框架。 有关详细信息,请参阅发布基本知识

发布模式 命令
依赖框架的部署 dotnet publish -c Release -p:UseAppHost=false
依赖于框架的可执行文件 dotnet publish -c Release -r <RID> --self-contained false
dotnet publish -c Release
独立部署 dotnet publish -c Release -r <RID> --self-contained true

注意

  • -c Release 参数不是必需的。 它作为提醒提供来发布应用的发行内部版本。
  • .NET SDK 3.1 或更高版本中,运行基本 dotnet publish 命令时,依赖于框架的可执行文件是默认发布模式。

发布基本知识

发布应用时,项目文件的 <TargetFramework> 设置指定默认目标框架。 可以将目标框架更改为任意有效目标框架名字对象 (TFM)。 例如,如果项目使用 <TargetFramework>net8.0</TargetFramework>,则会创建以 .NET 8 为目标的二进制文件。 此设置中指定的 TFM 是dotnet publish 命令使用的默认目标。

若要以多个框架为目标,则可以将 <TargetFrameworks> 设置设为多个 TFM 值(以分号分隔)。 当你生成应用时,会为每个目标框架生成一个内部版本。 但是,当你发布应用时,必须使用 dotnet publish -f <TFM> 命令指定目标框架。

除非使用 参数进行更改,否则默认的 BUILD-CONFIGURATION 模式为 Debug。

dotnet publish 命令的默认输出目录是 ./bin/<BUILD-CONFIGURATION>/<TFM>/publish/。 例如,dotnet publish -c Release -f net8.0 发布到 ./bin/Release/net8.0/publish/。 但是,可以为所有生成输出选择简化的输出路径和文件夹结构。 有关详细信息,请参阅生成工件输出布局

本机依赖项

如果应用具有本机依赖项,则只能在相同操作系统上运行。 例如,如果应用使用本机 Windows API,则不能在 macOS 或 Linux 上运行。 需要提供特定于平台的代码并为每个平台编译可执行文件。

另外,如果引用的库具有本机依赖项,则应用可能无法在每个平台上运行。 但是,引用的 NuGet 包可能包含特定于平台的版本,以便处理所需的本机依赖项。

使用本机依赖项分发应用时,可能需要使用 dotnet publish -r <RID> 开关来指定想要发布的目标平台。 有关运行时标识符的详细信息,请参阅运行时标识符 (RID) 目录

有关特定于平台的二进制文件的详细信息,请参阅依赖于框架的可执行文件独立部署部分。

示例应用

可使用以下应用来探索发布命令。 通过在终端中运行以下命令来创建应用:

mkdir apptest1
cd apptest1
dotnet new console
dotnet add package Figgle

控制台模板生成的 Program.csProgram.vb 文件需要进行以下更改:

using System;

namespace apptest1
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!"));
        }
    }
}
Module Program
    Sub Main(args As String())
        Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!"))
    End Sub
End Module

运行应用 (dotnet run) 时,将显示以下输出:

  _   _      _ _         __        __         _     _ _
 | | | | ___| | | ___    \ \      / /__  _ __| | __| | |
 | |_| |/ _ \ | |/ _ \    \ \ /\ / / _ \| '__| |/ _` | |
 |  _  |  __/ | | (_) |    \ V  V / (_) | |  | | (_| |_|
 |_| |_|\___|_|_|\___( )    \_/\_/ \___/|_|  |_|\__,_(_)
                     |/

依赖框架的部署

将应用作为 FDD 发布时,会在 ./bin/<BUILD-CONFIGURATION>/<TFM>/publish/ 文件夹中创建 <PROJECT-NAME>.dll 文件。 若要运行应用,请导航到输出文件夹并使用 dotnet <PROJECT-NAME>.dll 命令。

你的应用被配置为以特定版本的 .NET 为目标。 目标 .NET 运行时必须在运行应用的任何虚拟机上。 例如,如果应用以 .NET Core 8 为目标,则任何运行该应用的虚拟机都必须安装 .NET Core 8 运行时。 如发布基础知识部分中所述,可以编辑项目文件为更改默认目标框架或面向多个框架。

发布 FDD 会创建一个应用,该应用会自动前滚到运行该应用的系统上可用的最新 .NET 安全补丁。 若要详细了解编译时的版本绑定,请参阅选择要使用的 .NET 版本

发布模式 命令
依赖框架的部署 dotnet publish -c Release -p:UseAppHost=false

依赖于框架的可执行文件

依赖于框架的可执行文件 (FDE) 是基本 dotnet publish 命令的默认模式。 只要想要面向当前操作系统,就不需要指定任何其他参数。

在此模式下,将创建特定于平台的可执行主机来托管跨平台应用。 此模式类似于 FDD,因为 FDD 需要 dotnet 命令形式的主机。 每个平台的主机可执行文件名各不相同,其文件名类似于 <PROJECT-FILE>.exe。 可以直接运行此可执行文件,而不是调用 dotnet <PROJECT-FILE>.dll,这仍然是运行应用的可接受方式。

你的应用被配置为以特定版本的 .NET 为目标。 目标 .NET 运行时必须在运行应用的任何虚拟机上。 例如,如果应用以 .NET 8 为目标,则任何运行该应用的虚拟机都必须安装 .NET 8 运行时。 如发布基础知识部分中所述,可以编辑项目文件为更改默认目标框架或面向多个框架。

发布 FDE 会创建一个应用,此应用会自动前滚到运行此应用的系统上可用的最新 .NET 安全补丁。 若要详细了解编译时的版本绑定,请参阅选择要使用的 .NET 版本

发布模式 命令
依赖于框架的可执行文件 dotnet publish -c Release -r <RID> --self-contained false
dotnet publish -c Release

每次使用 -r 开关时,输出文件路都将更改为:./bin/<BUILD-CONFIGURATION>/<TFM>/<RID>/publish/

如果使用示例应用,请运行 dotnet publish -f net6.0 -r win-x64 --self-contained false。 此命令将创建以下可执行文件:./bin/Debug/net6.0/win-x64/publish/apptest1.exe

注意

可以通过启用全局固定模式来降低部署的总大小。 此模式适用于不具有全局意识且可以使用固定区域性的格式约定、大小写约定以及字符串比较和排序顺序的应用程序。 若要详细了解全球化固定模式以及如何启用它,请参阅 .NET 全球化固定模式

配置 .NET 安装搜索行为

在 .NET 9 及更高版本中,你可以通过 AppHostDotNetSearchAppHostRelativeDotNet 属性配置已发布可执行文件的 .NET 安装搜索路径。

AppHostDotNetSearch 允许指定可执行文件查找 .NET 安装所在的一个或多个位置:

  • AppLocal:应用可执行文件的文件夹
  • AppRelative:相对于应用可执行文件的路径
  • EnvironmentVariablesDOTNET_ROOT[_<arch>] 环境变量的值
  • Global注册的默认的全局安装位置

AppHostRelativeDotNet指定相对于AppHostDotNetSearch 包含 AppRelative 时要搜索的可执行文件的路径。

有关详细信息,请参阅 AppHostDotNetSearchAppHostRelativeDotNetapphost 中的安装位置选项

独立部署

当你发布独立式部署 (SCD) 时,.NET SDK 会创建特定于平台的可执行文件。 如果发布 SCD,则会包括运行应用所需的所有 .NET 文件,但不包括 .NET(例如,Linux 上的 .NET 6Linux 上的 .NET 8)的本机依赖项。 这些依赖项必须在应用运行前存在于系统中。

如果发布 SCD,则会创建一个不前滚到最新可用 .NET 安全补丁的应用。 若要详细了解编译时的版本绑定,请参阅选择要使用的 .NET 版本

必须通过 dotnet publish 命令使用以下开关来发布 SCD:

  • -r <RID>

    此开关使用标识符 (RID) 来指定目标平台。 有关运行时标识符的详细信息,请参阅运行时标识符 (RID) 目录

  • --self-contained true

    此开关告知 .NET SDK 创建可执行文件作为 SCD。

发布模式 命令
独立部署 dotnet publish -c Release -r <RID> --self-contained true

提示

  • 在 .NET 6 及更高版本中,可通过发布剪裁来减小兼容的自包含应用的总大小。 这使剪裁器可以删除没有在任何代码路径中或运行时反射中引用的框架和引用程序集的部分。 请参阅剪裁不兼容性,以确定剪裁是否适合你的应用程序。
  • 可以通过启用全局固定模式来降低部署的总大小。 此模式适用于不具有全局意识且可以使用固定区域性的格式约定、大小写约定以及字符串比较和排序顺序的应用程序。 有关全局固定模式及其启用方式的详细信息,请参阅 .NET Core 全局固定模式

另请参阅