目录

Chromium 二进制文件品牌化

本文介绍如何在 dotnet publish 流程中为 DotNetBrowser Chromium 二进制文件应用自定义品牌。

在使用 DotNetBrowser 的 .NET 应用程序中，请使用 DotNetBrowser.Branding NuGet 包。

如果你只需要用于构建或发布输出的解包 Chromium 二进制文件，请参阅 预提取 Chromium 二进制文件。

DotNetBrowser 会与库一起部署 Chromium 二进制文件。在大多数应用程序中，DotNetBrowser 会自动提取并使用这些二进制文件。本文介绍的包适用于你希望对品牌化、部署和白标输出拥有更多控制的场景：

  • DotNetBrowser.Branding 会在 dotnet publish 期间对 DotNetBrowser Chromium 二进制文件应用自定义品牌。它还包含提取任务，因此可以在应用品牌之前先提取 Chromium 二进制文件。

该包通过应用程序项目文件中的 MSBuild 属性进行配置。

前提条件 

开始之前，请确保应用程序项目已引用 DotNetBrowser API 包以及与目标运行时匹配的平台特定 Chromium 包。API 包提供应用程序使用的 .NET API，而 Chromium 包提供品牌化工具处理的对应 Chromium 二进制文件。

支持的软件包及平台特定安装选项的完整列表，请参阅 从 NuGet 安装。

请在与目标运行时相同的操作系统家族上执行品牌化。例如，在 Linux 上品牌化 Linux 二进制文件，在 macOS 上品牌化 macOS 二进制文件。这样可以保留可执行权限、符号链接和平台 bundle 结构。

DotNetBrowser.Branding 

DotNetBrowser.Branding 是一个 MSBuild 任务包，用于在 dotnet publish 期间对 DotNetBrowser Chromium 二进制文件应用自定义品牌。

当你需要白标 Chromium 二进制文件时，请使用此包，例如更改可执行文件名称、产品元数据、进程显示名称、图标或 macOS bundle 信息。

该包内部包含 Chromium 提取任务。如果品牌化源是 DotNetBrowser.Chromium.*.dll 程序集，或者是包含该程序集的发布目录，则会先执行提取，再执行品牌化。

在内部，DotNetBrowser.Branding 使用 chromium_branding 命令行工具。它会修改 DotNetBrowser Chromium 二进制文件的各平台品牌信息，例如可执行文件名称、进程显示名称、图标、版本信息、版权和产品元数据，以及 macOS bundle 信息。它支持 Windows、macOS 和 Linux Chromium 二进制文件。

NuGet 包会从 MSBuild 中调用该工具，因此你无需手动运行 chromium_branding。

安装 DotNetBrowser.Branding 

将该包添加到应用程序项目中：

<ItemGroup>
  <PackageReference Include="DotNetBrowser.Branding"
                    Version="..."
                    PrivateAssets="all" />
</ItemGroup>

对于应用程序项目，建议使用 PrivateAssets="all"，因为该包提供的是构建和发布任务。

最小品牌化配置 

创建一个品牌化参数文件，例如 branding.params.json，并在项目文件中启用品牌化：

<PropertyGroup>
  <DotNetBrowserBrandingEnabled>true</DotNetBrowserBrandingEnabled>
  <DotNetBrowserBrandingParamsFile>$(MSBuildProjectDirectory)/branding.params.json</DotNetBrowserBrandingParamsFile>
</PropertyGroup>

然后发布应用程序：

dotnet publish -c Release -r win-x64

品牌化在 Publish 之后执行。默认情况下，该包：

  • 使用 $(PublishDir) 作为品牌化源；
  • 如果源中包含 Chromium 程序集，则自动先提取 Chromium 二进制文件；
  • 将品牌化后的二进制文件写入 $(PublishDir)branded/；
  • 追加平台特定子目录，例如 WindowsX64、LinuxX64、MacX64 或 MacArm64。

最终输出路径会记录为 DotNetBrowserBrandedOutputPath。

品牌化参数文件 

品牌化参数文件是由内置 chromium_branding 工具使用的 JSON 文件。

示例：

{
  "version": "1.2.3",
  "win": {
    "executableName": "myapp",
    "processDisplayName": "My App",
    "legalCopyright": "© 2026 MyCompany",
    "author": "MyCompany",
    "productName": "MyApp",
    "icoPath": "assets/app.ico",
    "signCommand": "echo @@BINARY_PATH@@"
  },
  "mac": {
    "bundle": {
      "name": "MyApp",
      "id": "com.mycompany.myapp"
    },
    "icnsPath": "assets/app.icns",
    "codesignIdentity": "${CODESIGN_IDENTITY}",
    "codesignEntitlements": "assets/entitlements.plist",
    "provisioningProfile": "assets/app.provisionprofile",
    "teamID": "${TEAM_ID}",
    "appleID": "${APPLE_ID}",
    "password": "${PASSWORD}"
  },
  "linux": {
    "executableName": "myapp"
  }
}

像 icoPath、icnsPath 和 codesignEntitlements 这样的相对资源路径，默认会相对于 branding.params.json 所在目录解析。你可以通过 DotNetBrowserBrandingAssetsBasePath MSBuild 属性覆盖基目录。

请勿将 Apple ID 密码或签名凭据等机密信息写入 JSON 文件。尽可能使用环境变量或 CI/CD 密钥变量。

支持的品牌化选项 

以下选项通常会在 branding.params.json 中使用。

Windows 

选项说明
executableName自定义 Chromium 可执行文件名称，不包含 .exe 扩展名。
processDisplayName显示在 Chromium 进程中的名称。
legalCopyrightWindows 二进制文件的版权元数据。
author公司或作者元数据。
productName产品名称元数据。
icoPath指向 .ico 文件的路径。相对路径默认会自动复制。
signCommand用于签名品牌化二进制文件的命令。品牌化工具会替换 @@BINARY_PATH@@ 等占位符。

macOS 

选项说明
bundle.namemacOS bundle 显示名称。
bundle.idmacOS bundle 标识符，例如 com.company.product。
icnsPath指向 .icns 图标文件的路径。相对路径默认会自动复制。
codesignIdentity代码签名标识。
codesignEntitlements指向 entitlements .plist 文件的路径。相对路径默认会自动复制。
provisioningProfile指向 Apple 签名的 .provisionprofile 文件的可选路径。当 entitlements 文件包含 keychain-access-groups 时需要此项，例如支持 Touch ID。
teamIDApple Developer Team ID。
appleID签名/公证流程使用的 Apple ID。
password签名/公证流程使用的密码或专用密码。建议使用密钥或环境变量。

Linux 

选项说明
executableName自定义 Chromium 可执行文件名称。

品牌化属性 

属性默认值说明
DotNetBrowserBrandingEnabledfalse在发布后启用品牌化。
DotNetBrowserBrandingParamsFile空启用品牌化时必需。指向 branding.params.json。
DotNetBrowserBrandingSourcePath$(PublishDir)用于品牌化的源文件或目录。
DotNetBrowserBrandingDestinationPath$(PublishDir)branded/品牌化后二进制文件的输出目录。相对路径会相对于 $(PublishDir) 解析。
DotNetBrowserBrandingToolPath如有内置工具则使用内置工具；否则在 Windows 上使用 chromium_branding.exe，在 Linux/macOS 上使用 chromium_branding品牌化工具可执行文件的显式路径。
DotNetBrowserBrandingToolArguments空可选的自定义工具参数。支持 {source}、{destination} 和 {params} 占位符。若为空，任务将使用默认的 -p、-b 和 -o 参数。
DotNetBrowserBrandingWorkingDirectory已准备的源路径品牌化工具进程的工作目录。
DotNetBrowserBrandingStageAssetstrue在品牌化前，将 branding.params.json 中的相对资源路径复制到已准备好的二进制文件目录。
DotNetBrowserBrandingAssetsBasePathDotNetBrowserBrandingParamsFile 所在目录branding.params.json 中相对资源文件的基路径。
DotNetBrowserBrandingKeepTemporaryExtractionfalse品牌化后保留临时提取的二进制文件，便于诊断。

在应用启动时使用品牌化后的二进制文件 

通过 EngineOptions.ChromiumDirectory 配置 DotNetBrowser 使用品牌化输出目录。

该值应指向品牌化根目录。DotNetBrowser 会自动追加当前平台子目录。

C#
VB
string chromiumDirectory = Path.Combine(AppContext.BaseDirectory, "branded");

IEngine engine = EngineFactory.Create(new EngineOptions.Builder
{
    ChromiumDirectory = chromiumDirectory
}.Build());

Dim chromiumDirectory As String =
    Path.Combine(AppContext.BaseDirectory, "branded")

Dim engine As IEngine = EngineFactory.Create(
    New EngineOptions.Builder() With {
        .ChromiumDirectory = chromiumDirectory
    }.Build()
)

对于品牌化输出到 publish/branded/WindowsX64 的发布结果，请将 ChromiumDirectory 设置为 publish/branded。

构建和发布流程 

典型的品牌化流程如下：

  1. 将 DotNetBrowser 和平台特定 Chromium 包添加到应用程序项目。
  2. 添加 DotNetBrowser.Branding。
  3. 创建 branding.params.json。
  4. 在项目文件中配置 DotNetBrowserBrandingEnabled 和 DotNetBrowserBrandingParamsFile。
  5. 针对目标运行时标识符执行发布。
  6. 将品牌化输出目录与应用程序一起部署。

Windows x64 发布命令示例：

dotnet publish -c Release -r win-x64

Linux x64 发布命令示例：

dotnet publish -c Release -r linux-x64

macOS ARM64 发布命令示例：

dotnet publish -c Release -r osx-arm64

请在与目标运行时相同的操作系统家族上执行每条命令。

查看本文：