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 安装。

DotNetBrowser.Branding 

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

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

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

DotNetBrowser.Branding 内部使用 chromium_branding 命令行工具。该工具通过修改特定平台的品牌信息来自定义 DotNetBrowser Chromium 二进制文件，包括可执行文件名称、进程显示名称、图标、版本信息、版权与产品元数据，以及 macOS 软件包信息。它支持 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 的名称记录在日志中。

品牌定制参数文件 

品牌定制参数文件是一个 JSON 文件，由包中自带的 chromium_branding 工具读取。

示例：

{
  "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 属性覆盖该基础目录。

支持的品牌定制选项 

以下是在 branding.params.json 中常用的选项。

Windows 

macOS 

Linux 

品牌化属性 

重新打包到运行时可提取的容器 

默认情况下，品牌定制操作会将 Chromium 二进制文件输出到一个普通目录中。如果您的应用程序从映射的网络驱动器或 UNC 路径运行，则必须单独分发并验证该目录中的每个 Chromium 文件。

启用重新打包功能，可将完成品牌定制的二进制文件重新打包为 DotNetBrowser 通常使用的相同紧凑容器格式，以便在运行时将其提取到当前用户的本地目录中：

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

重新打包功能仅在品牌定制源是 Chromium 容器程序集（DotNetBrowser.Chromium.<Platform>.dll）而非已解压目录时才有效。重新打包后的程序集必须保留与原始程序集相同的文件名，因此请确保您的应用程序从 DotNetBrowserBrandingRepackDestinationPath 输出目录中加载并部署该程序集，以替代原始程序集。

重新打包会改变程序集的二进制内容，从而导致原始程序集携带的所有 Authenticode 签名失效。如有需要，请设置 DotNetBrowserBrandingRepackSignCommand（使用与 branding.params.json 中的 signCommand 相同的 @@BINARY_PATH@@ 占位符规则），对重新打包后的程序集重新签名。

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

通过 EngineOptions.ChromiumDirectory 配置 DotNetBrowser，使其使用品牌定制输出目录。

该值应指向品牌定制输出的基础目录。DotNetBrowser 会自动附加当前平台对应的子目录。

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

请在与目标运行时属于同一操作系统系列的系统上运行相应命令。