syncfusion-wpf-licensing

实现 Syncfusion 许可

关于在所有平台（WPF、Blazor、React、MAUI、Angular、Vue、ASP.NET Core 等）生成、注册和排查 Syncfusion 许可证密钥问题的全面指南。

概述

从版本 16.2.0.x 开始，Syncfusion 引入了适用于以下用户的许可系统：

• 使用试用安装程序的所有评估用户
• 使用 nuget.org 中 NuGet 包的付费客户

如果使用评估安装程序或 NuGet 包，则必须在应用程序中注册有效的许可证密钥，以避免出现许可证验证消息。

要点：

• 许可证密钥与版本和平台相关
• 注册过程离线进行（无需连接互联网）
• 许可证密钥与安装程序解锁密钥不同
• 使用 nuget.org 中的 NuGet 包和试用安装程序时必须注册
• 使用许可安装程序（来自许可安装的程序集）时无需注册

何时使用此技能

用户需要执行以下操作时，请立即使用此技能：

• 为 Syncfusion 组件生成许可证密钥
• 在应用程序中注册许可证密钥（WPF、Blazor、React 等）
• 排查许可错误（试用期已过、密钥无效、平台或版本不匹配）
• 设置 CI/CD 许可证验证（Azure Pipelines、GitHub Actions、Jenkins）
• 从试用版升级到许可版本
• 了解许可证密钥与解锁密钥的区别
• 配置构建服务器许可
• 解决“许可证验证消息”错误
• 为 nuget.org 用户注册 Syncfusion 帐户
• 使用 ValidateLicense() 方法以编程方式验证许可证

了解许可证类型

何时需要注册许可证

Syncfusion 来源	是否需要注册许可证？	备注
NuGet 包（nuget.org）	✅ 是	需要与版本和平台对应的密钥
试用安装程序	✅ 是	需要免费的 30 天试用密钥
许可安装程序	❌ 否	无需注册

许可证密钥与解锁密钥

• 许可证密钥：在应用程序代码中使用 SyncfusionLicenseProvider.RegisterLicense() 注册
• 解锁密钥：用于解锁 Syncfusion 安装程序（较早的系统）
• 两者是不同的密钥，用途也不同

文档与导航指南

开始使用许可

📄 阅读： references/overview-and-differences.md

• 许可系统概述
• 许可证密钥与解锁密钥的区别
• 何时需要许可证密钥（NuGet、试用版、许可安装程序）
• 构建服务器许可要求
• 平台和版本对应关系
• 在构建环境中注册密钥

生成许可证密钥

📄 阅读： references/generating-license-keys.md

• 生成密钥的位置（License & Downloads、Trial & Downloads）
• 使用“Claim License Key”功能
• 处理有效许可证与有效试用
• 处理已过期的许可证（临时 5 天密钥）
• 选择平台和版本的指南

注册许可证密钥

📄 阅读： references/registering-license-keys.md

• 特定平台的注册代码放置位置
• WPF：在 App.xaml.cs 构造函数中注册（C# 和 VB）
• Blazor、React、Angular、Vue、MAUI 的注册模式
• Syncfusion.Licensing.dll 要求
• 离线验证功能
• 注册代码示例

排查许可错误

📄 阅读： references/licensing-errors.md

• “许可证密钥未注册”错误
• “密钥无效”错误
• “试用期已过”错误
• “平台不匹配”错误
• “版本不匹配”错误
• “无法加载 Syncfusion.Licensing.dll”错误
• 各类错误的解决方案
• 程序集的 Copy Local 设置
• 不同版本的错误消息（16.2.0+ 与 20.3.0+）

CI/CD 许可证验证

📄 阅读： references/ci-license-validation.md

• CI/CD 验证指南（程序化验证、单元测试验证或内部托管的制品）。请勿在流水线中下载或执行未经审核的外部二进制文件。
• Azure Pipelines（YAML 和 Classic）集成
• GitHub Actions 集成
• Jenkins 流水线集成
• 用于程序化验证的 ValidateLicense() 方法
• 单元测试项目验证方法
• 防止部署期间出现许可错误

升级和账户设置

📄 阅读： references/upgrading-and-account-setup.md

• 购买许可证后从试用版升级
• 卸载和重新安装流程
• 将试用密钥替换为付费许可证密钥
• 为 NuGet.org 用户注册 Syncfusion 账户
• 开始免费 30 天试用
• 互联网连接要求（支持离线验证）

快速入门示例

⚠️ 安全警告

请勿在代码中硬编码许可证密钥。 许可证密钥属于机密，必须妥善保管。有关安全凭据处理模式，请参阅 SECURITY_ANALYSIS.md 文档。

WPF 应用（使用环境变量保护）

// In App.xaml.cs
using Syncfusion.Licensing;

public partial class App : Application
{
    public App()
    {
        // SECURE: Read from environment variable
        string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY")
            ?? throw new InvalidOperationException(
                "SYNCFUSION_LICENSE_KEY environment variable not set");
        
        // Register Syncfusion license key BEFORE initializing any components
        SyncfusionLicenseProvider.RegisterLicense(licenseKey);
        
        InitializeComponent();
    }
}

运行前设置环境变量：

# Windows Command Prompt
setx SYNCFUSION_LICENSE_KEY "your_actual_license_key"

# Windows PowerShell
$env:SYNCFUSION_LICENSE_KEY = "your_actual_license_key"

Blazor Server（使用配置保护）

// In Program.cs
using Syncfusion.Licensing;

var builder = WebApplication.CreateBuilder(args);

// SECURE: Read from configuration (loaded from environment variables or appsettings.json)
var licenseKey = builder.Configuration["Syncfusion:LicenseKey"]
    ?? throw new InvalidOperationException(
        "Syncfusion:LicenseKey not configured. " +
        "Set SYNCFUSION_LICENSE_KEY environment variable or add to appsettings.json");

// Register license key at application startup
SyncfusionLicenseProvider.RegisterLicense(licenseKey);

// ... rest of your configuration

环境设置：

# Set environment variable
set SYNCFUSION_LICENSE_KEY=your_license_key

# Or use user secrets in development
dotnet user-secrets set "Syncfusion:LicenseKey" "your_license_key"

React/Angular/Vue（使用环境变量保护）

// In your main entry point (e.g., index.js, main.ts)
import { registerLicense } from '@syncfusion/ej2-base';

// SECURE: Read from environment variable (via process.env or import.meta.env)
const licenseKey = process.env.REACT_APP_SYNCFUSION_LICENSE_KEY;

if (!licenseKey) {
    console.error('REACT_APP_SYNCFUSION_LICENSE_KEY environment variable not set');
    throw new Error('License key not configured');
}

// Register license key before rendering components
registerLicense(licenseKey);

环境设置（.env 文件）：

REACT_APP_SYNCFUSION_LICENSE_KEY=your_actual_license_key

重要提示： 将 .env 和 .env.local 添加到 .gitignore，以防意外提交密钥。

常见许可场景

场景 1：试用用户设置

1. 注册免费的 Syncfusion 账户
2. 在账户门户中开始 30 天试用
3. 从 Trial & Downloads 部分生成试用许可证密钥
4. 使用 RegisterLicense() 在应用中注册密钥
5. 试用密钥在 30 天后过期

场景 2：已获许可用户设置

1. 登录 Syncfusion 账户
2. 前往 License & Downloads 部分
3. 为指定版本和平台生成许可证密钥
4. 使用 RegisterLicense() 在应用中注册密钥
5. 密钥对指定的版本和平台有效

场景 3：NuGet.org 用户设置

1. 使用来自 nuget.org 的 Syncfusion 包需要注册许可证
2. 如果尚未注册 Syncfusion 账户，请先注册
3. 开始试用或购买许可证
4. 生成并注册许可证密钥
5. 未注册时会看到许可证验证警告

场景 4：构建服务器 / CI/CD

1. 使用 NuGet 包的构建服务器需要注册许可证
2. 使用任意开发者许可证为构建环境生成密钥
3. 在应用代码中注册密钥
4. 可选择设置 CI 许可证验证，以便及早发现错误
5. 构建期间无需互联网连接（支持离线验证）

场景 5：从试用版升级

1. 购买 Syncfusion 许可证
2. 选项 A：卸载试用版安装程序，并从 License & Downloads 安装已获许可的版本
3. 选项 B：如果使用 NuGet，请生成付费许可证密钥并替换试用密钥
4. 已获许可的安装程序程序集无需注册密钥
5. NuGet 包始终需要注册密钥

核心概念

平台和版本特定性

• 许可证密钥与版本相关：v26.1.35 的密钥无法用于 v26.2.4
• 许可证密钥与平台相关：WPF 密钥无法用于 Blazor
• 为每种平台和版本组合分别生成密钥
• 在 RegisterLicense() 调用中使用正确的版本

离线验证

• 应用运行期间会离线进行许可证验证
• 应用运行无需互联网连接
• 可以部署到隔离网络系统
• 验证会在应用启动时进行

构建服务器

• 使用 NuGet 包的构建服务器需要进行许可证注册
• 使用任何开发者许可证为 CI/CD 生成密钥
• 构建服务器上的已许可安装程序程序集不需要密钥
• 设置 CI 验证以防止部署错误

Syncfusion.Licensing.dll

• 许可证注册所需的程序集
• 确保在使用 RegisterLicense() 的项目中引用该程序集
• 将“Copy Local”设置为 true，以将其包含在输出中
• 可通过 NuGet 获取：Syncfusion.Licensing

注册最佳实践

1. 尽早注册：在初始化任何 Syncfusion 组件之前调用 RegisterLicense()
2. 每个应用注册一次：只需在启动时注册一次
3. 使用安全存储：✅ 环境变量、✅ 配置文件、✅ 密钥管理器（Azure Key Vault、AWS Secrets Manager）| ❌ 切勿使用硬编码的字符串字面量
4. 版本匹配：确保所有 Syncfusion 包使用相同版本
5. 切勿硬编码密钥：将密钥存储在环境变量或安全配置系统中
6. 使用 .gitignore：将包含机密信息的配置文件排除在版本控制之外
7. CI/CD 验证：使用程序化验证方法，而不是下载外部工具
8. 定期轮换密钥：定期更新许可证密钥并撤销旧密钥
9. 审计访问：监控并记录所有许可证密钥的访问和使用情况

⚠️ **安全警告：**有关安全处理凭据和 CI/CD 验证模式的详细指南，请参阅 SECURITY_ANALYSIS.md。

错误预防检查清单

部署应用程序前：

• 为正确的版本和平台生成许可证密钥
• 在初始化任何 Syncfusion 组件之前调用 RegisterLicense()
• 所有 Syncfusion NuGet 包的版本相同
• 已引用 Syncfusion.Licensing.dll，且“Copy Local” = true
• 许可证密钥与正在使用的 Syncfusion 包版本匹配
• 对于 CI/CD：已在构建管道中配置许可证验证
• 安全存储许可证密钥（未在公开仓库中硬编码）

相关技能

• 实现 Syncfusion WPF 组件 - 针对 WPF 的组件实现
• 实现 Syncfusion Blazor 组件 - Blazor 组件
• 实现 Syncfusion React 组件 - React 组件