syncfusion-maui-licensing

Syncfusion .NET MAUI 许可

全面介绍如何管理 Syncfusion .NET MAUI 许可，涵盖从生成到注册和故障排除的全过程。

何时使用此技能

遇到以下情况时，请立即使用此技能：

许可错误：

• 显示“This application was built using a trial version”消息
• 出现“The included Syncfusion license key is invalid”错误
• 许可验证失败
• 平台不匹配错误
• 版本不匹配错误
• 试用期已过期消息

许可密钥任务：

• 从 Syncfusion 帐户生成许可密钥
• 在应用程序中注册许可密钥
• 了解试用版与已授权安装版本之间的区别
• 区分解锁密钥与许可密钥
• 为构建服务器配置许可
• 设置 CI/CD 许可验证

常见场景：

• 使用 Syncfusion 组件进行应用初始设置
• 解决开发期间出现的许可警告
• 使用正确的许可部署应用程序
• 从试用版升级到已授权版本
• 管理多个项目的许可
• 排查“Could not load Syncfusion.Licensing.dll”错误

许可系统概览

从版本 20.2.0.x 开始，Syncfusion 引入了新的许可系统，适用于：

• 来自 nuget.org 的 NuGet 包
• 评估版安装程序
• 试用许可

要点：

• 许可密钥与版本和平台相关
• NuGet 包和试用版安装程序需要注册
• 已授权安装程序无需注册许可密钥
• 许可验证在离线状态下进行（无需联网）
• 许可密钥与安装程序解锁密钥不同

文档与导航指南

了解许可

**何时阅读：**首次设置、了解许可要求，或确认试用版与已授权安装版本之间的区别时。

📄 阅读：references/licensing-overview.md

• 许可系统简介（v20.2.0.x 的变更）
• 何时需要注册许可密钥
• 试用版与已授权安装版本之间的区别
• 解锁密钥与许可密钥的区别
• 构建服务器许可场景
• NuGet 包许可要求
• 版本和平台相关性

生成许可密钥

**何时阅读：**需要获取新的许可密钥、使用试用许可，或管理不同版本/平台的许可时。

📄 阅读：references/license-generation.md

• 访问“License & Downloads”部分
• 访问“Trial & Downloads”部分
• 使用“Claim License Key”功能
• 为有效许可生成密钥
• 为有效试用生成密钥
• 处理过期许可（临时 5 天密钥）
• 为 NuGet.org 用户设置帐户
• 生成特定平台和版本的密钥

注册许可密钥

**何时阅读：**需要在应用程序中注册许可密钥、选择注册位置，或实施正确的许可配置时。

📄 阅读：references/license-registration.md

• RegisterLicense() 方法语法
• 在 App.xaml.cs 构造函数中注册
• 在 MauiProgram.cs 中注册
• Syncfusion.Licensing.dll 引用要求
• 注册位置的最佳实践
• 多种注册场景
• 每种方法的完整代码示例

排查许可错误

**何时阅读：**遇到许可验证错误、试用期已过期消息、平台/版本不匹配或程序集加载问题时。

📄 阅读：references/licensing-errors.md

• 未注册许可密钥错误
• 无效密钥错误消息
• 试用期已过期错误
• 平台不匹配错误
• 版本不匹配错误
• “Could not load Syncfusion.Licensing.dll”问题
• 每种错误类型的解决方案
• 特定版本的错误变体
• 程序集的 Copy Local 配置

高级主题与常见问题

适用情形： 设置 CI/CD 流水线、以编程方式验证许可证、咨询离线部署问题，或从试用版升级时。

📄 阅读： references/licensing-faq.md

• CI/CD 许可证验证（Azure Pipelines、GitHub Actions、Jenkins）
• 用于编程检查的 ValidateLicense() 方法
• 许可证验证的单元测试
• Internet 连接要求（离线验证）
• 从试用版升级到授权版本
• NuGet.org 用户账号注册
• 获取许可证密钥的途径
• 常见问题解答

快速入门指南

步骤 1：生成许可证密钥

1. 登录 Syncfusion 账号
2. 前往 License & Downloads（授权版）或 Trial & Downloads（试用版）
3. 为 .NET MAUI 平台和对应版本生成许可证密钥
4. 复制生成的许可证密钥

步骤 2：注册许可证密钥

选择以下一种注册方式：

选项 A：在 App.xaml.cs 中注册

public App()
{
    // Register Syncfusion license
    string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
    if (!string.IsNullOrEmpty(licenseKey))
    {   
        Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(licenseKey);
    }
    
    InitializeComponent();
    
    MainPage = new AppShell();
}

选项 B：在 MauiProgram.cs 中注册

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        // Register the Syncfusion license key
       string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
        if (!string.IsNullOrEmpty(licenseKey))
        {   
            Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(licenseKey);
        }
 
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureSyncfusionCore()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        return builder.Build();
    }
}

步骤 3：验证注册

运行应用程序。若注册成功，您应该不会看到任何许可证警告消息。

常见模式

模式 1：新项目的初始设置

情景： 使用 NuGet 中的 Syncfusion 组件启动新的 .NET MAUI 项目。

步骤：

1. 安装 Syncfusion NuGet 包
2. 为 MAUI 平台和对应版本生成许可证密钥
3. 在 MauiProgram.cs 中、ConfigureSyncfusionCore() 之前注册许可证密钥
4. 确保已安装 Syncfusion.Licensing 包
5. 构建并运行，以确认没有许可证警告

模式 2：解决“试用版”警告

情景： 应用程序显示“This application was built using a trial version”消息。

解决方案：

1. 确认您拥有有效的许可证密钥（未过期）
2. 检查许可证密钥的平台是否正确（MAUI）
3. 检查许可证密钥的版本是否与您的包版本一致
4. 在 InitializeComponent() 或 ConfigureSyncfusionCore() 之前注册许可证密钥
5. 清理并重新构建应用程序

模式 3：版本不匹配错误

情景： 错误消息显示“included Syncfusion license ({Registered Version}) is invalid for version {Required version}”

解决方案：

1. 检查 NuGet 包版本（所有包的版本应相同）
2. 为您使用的确切版本生成新的许可证密钥
3. 用新的许可证密钥替换旧密钥
4. 清理解决方案并重新构建

模式 4：构建服务器 / CI/CD 设置

情景： 需要在持续集成期间验证许可证。

方法：

• 在 CI 流水线中使用 LicenseKeyValidator 实用工具
• 使用单元测试实现 ValidateLicense() 方法
• 配置许可证密钥的环境变量
• 验证失败时使构建失败

阅读： references/licensing-faq.md，了解详细的 CI/CD 设置说明。

模式 5：解决方案中的多个项目

情景： 解决方案中有多个使用 Syncfusion 组件的 MAUI 项目。

解决方案：

1. 在每个项目的 App.xaml.cs 或 MauiProgram.cs 中注册许可证密钥
2. 如果版本相同，所有项目使用相同的许可证密钥
3. 确保所有项目都引用 Syncfusion.Licensing.dll
4. 考虑使用共享常量保存许可证密钥字符串

关键概念

许可证密钥与解锁密钥

• 解锁密钥： 用于在安装期间解锁 Syncfusion 安装程序
• 许可证密钥： 使用 NuGet 包或试用版安装程序时，必须在应用程序代码中提供
• 二者用途不同，是不同的密钥

版本和平台特定性

许可证密钥绑定到：

• 平台： MAUI、WPF、Blazor 等（MAUI 应用使用 MAUI 许可证）
• 版本： Major.Minor.Patch（例如，26.2.4）

MAUI 26.2.4 许可证密钥不能用于：

• 不同平台（例如，Blazor）
• 不同版本（例如，26.1.0 或 27.0.0）

需要注册许可证的情况

需要：

• 来自 nuget.org 的 NuGet 包
• 试用版安装程序集
• 评估场景

不需要：

• 已授权的安装程序集（许可证已嵌入程序集）

离线验证

• 许可证验证会在应用运行期间离线进行
• 验证无需连接互联网
• 应用可以部署到无法访问互联网的系统

常见用例

用例 1：开发者首次设置

用户：“我刚通过 NuGet 安装了 Syncfusion MAUI 组件，现在收到了试用许可证警告。”

解决方案：

1. 阅读 references/licensing-overview.md，了解许可证要求
2. 阅读 references/license-generation.md，生成适用的密钥
3. 阅读 references/license-registration.md，在应用中注册密钥

用例 2：部署问题

用户：“我的应用在开发环境中运行正常，但部署后却出现许可证错误。”

解决方案：

1. 确认部署包中包含 Syncfusion.Licensing.dll
2. 检查 Syncfusion 程序集的 Copy Local 是否设置为 True
3. 阅读 references/licensing-errors.md，了解“Could not load”问题的排查方法

用例 3：从试用版升级为已授权版本

用户：“我购买了许可证，该如何移除试用版警告？”

解决方案：

1. 阅读 references/licensing-faq.md 中的“从试用版升级”部分
2. 生成新的已授权密钥（而不是试用密钥）
3. 在 RegisterLicense() 调用中用已授权密钥替换试用密钥
4. 清理并重新生成应用

用例 4：CI/CD 集成

用户：“如何在 Azure DevOps 流水线中验证许可证？”

解决方案： 阅读 references/licensing-faq.md，了解完整的 CI/CD 设置，包括：

• Azure Pipelines（YAML 和 Classic）
• GitHub Actions
• Jenkins
• 使用 ValidateLicense() 的单元测试方法

重要说明

• 始终在 App.xaml.cs 中调用 InitializeComponent() 之前，或在 MauiProgram.cs 中调用 ConfigureSyncfusionCore() 之前注册许可证密钥
• 妥善保管许可证密钥（不要提交到公开代码仓库）
• 项目中的所有 Syncfusion 包使用同一个许可证密钥
• 确保所有 Syncfusion 包的版本相同
• 许可证验证错误会在运行时显示，而不是在编译时显示