syncfusion-winforms-licensing

实现 Syncfusion Windows Forms 许可

本技能全面介绍如何在 Windows Forms 应用程序中实现和管理 Syncfusion 许可，包括生成许可密钥、注册、故障排查以及 CI/CD 集成。

何时使用此技能

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

• 在使用 Syncfusion 组件的 Windows Forms 应用程序中实现许可
• 解决许可验证错误或试用版过期提示
• 为特定版本和平台生成许可密钥
• 在 C# 或 VB.NET Windows Forms 应用程序中注册许可密钥
• 排查许可问题，例如密钥无效、平台不匹配或版本不匹配
• 使用许可验证配置 CI/CD 流水线（Azure Pipelines、GitHub Actions、Jenkins）
• 了解许可要求，包括 NuGet 包、试用版安装程序或许可版安装程序
• 购买后从试用版升级到许可版
• 处理构建服务器许可场景

Syncfusion 许可概述

从版本 16.2.0.x 开始，Syncfusion 引入了新的许可系统，要求注册许可密钥，适用于：

• 使用评估版安装程序的应用程序
• 引用 nuget.org 上 Syncfusion NuGet 包的应用程序

要点：

• 许可密钥与版本和平台相关
• 许可密钥不同于安装程序解锁密钥
• 验证在应用程序运行期间离线进行（无需互联网连接）
• 许可版安装程序用户无需注册许可密钥
• 试用许可密钥在 30 天后过期

文档与导航指南

了解许可

📄 阅读： references/licensing-overview.md

适合阅读此参考文档的情况：

• 了解版本 16.2.0.x 引入的许可系统
• 了解解锁密钥与许可密钥之间的区别
• 确定何时需要注册许可
• 了解构建服务器场景（NuGet、试用版和许可版安装程序）
• 了解版本和平台的特定性

生成许可密钥

📄 阅读： references/license-generation.md

适合阅读此参考文档的情况：

• 从 License & Downloads 部分生成许可密钥
• 从 Trial & Downloads 部分生成许可密钥
• 使用 Claim License Key 功能
• 处理有效许可场景
• 处理有效试用场景
• 处理已过期的许可
• 在没有许可时开始试用

注册许可密钥

📄 阅读： references/license-registration.md

适合阅读此参考文档的情况：

• 在 C# 或 VB.NET 中实现 RegisterLicense 方法
• 在 C# 应用程序的 Main() 方法中注册密钥
• 在 VB.NET 的 Application.Designer.vb 中注册密钥
• 在 VB.NET 的 Program.vb 中注册密钥
• 了解对 Syncfusion.Licensing.dll 的引用要求
• 了解离线验证功能

排查许可错误

📄 阅读： references/licensing-errors.md

适合阅读此参考文档的情况：

• 解决“未注册许可密钥”错误
• 修复“密钥无效”错误
• 处理“试用已过期”提示
• 解决平台不匹配错误
• 修复版本不匹配错误
• 排查“无法加载 Syncfusion.Licensing.dll”错误
• 配置 Copy Local 设置
• 了解旧版错误（v16.2.0 - v20.3.0）

常见问题和 CI/CD 集成

📄 阅读： references/licensing-faqs.md

适合阅读此参考资料的情况：

• 实现 CI/CD 许可证验证（Azure Pipelines、GitHub Actions、Jenkins）
• 在构建流水线中使用 LicenseKeyValidator 实用工具
• 了解如何获取许可证密钥
• 检查验证是否需要互联网连接
• 从试用版升级到许可版
• 为 NuGet.org 用户注册 Syncfusion 帐户
• 了解许可证密钥的适用范围

快速入门示例

以下是一个在 Windows Forms 应用程序中注册 Syncfusion 许可证密钥的完整示例：

C# 示例（使用环境变量 — 推荐）

using System;
using System.Windows.Forms;
using Syncfusion.Licensing;

namespace MyWindowsFormsApp
{
    static class Program
    {
        [STAThread]
        static void Main()
        {
            // SECURITY BEST PRACTICE: Read license key from environment variable
            string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
            
            if (string.IsNullOrEmpty(licenseKey))
            {
                MessageBox.Show("Syncfusion license key not found in environment variables.", 
                    "Configuration Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
                return;
            }
            
            // Register Syncfusion license key BEFORE any Syncfusion control is initiated
            SyncfusionLicenseProvider.RegisterLicense(licenseKey);
            
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.Run(new Form1());
        }
    }
}

替代方案：使用配置文件（App.config）

using System;
using System.Configuration;
using System.Windows.Forms;
using Syncfusion.Licensing;

namespace MyWindowsFormsApp
{
    static class Program
    {
        [STAThread]
        static void Main()
        {
            // Read from app.config (ensure it's not committed to source control)
            string licenseKey = ConfigurationManager.AppSettings["SyncfusionLicenseKey"];
            
            if (string.IsNullOrEmpty(licenseKey))
            {
                MessageBox.Show("Syncfusion license key not configured.", 
                    "Configuration Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
                return;
            }
            
            SyncfusionLicenseProvider.RegisterLicense(licenseKey);
            
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.Run(new Form1());
        }
    }
}

App.config 示例：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    
    
    <add key="SyncfusionLicenseKey" value="" />
  </appSettings>
</configuration>

VB.NET 示例（使用环境变量 — 推荐）

Imports Syncfusion.Licensing

Namespace My
    Partial Friend Class MyApplication
        Public Sub New()
            MyBase.New(Global.Microsoft.VisualBasic.ApplicationServices.AuthenticationMode.Windows)
            
            ' SECURITY BEST PRACTICE: Read license key from environment variable
            Dim licenseKey As String = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY")
            
            If String.IsNullOrEmpty(licenseKey) Then
                MessageBox.Show("Syncfusion license key not found in environment variables.", _
                    "Configuration Error", MessageBoxButtons.OK, MessageBoxIcon.Error)
                Return
            End If
            
            ' Register Syncfusion License
            SyncfusionLicenseProvider.RegisterLicense(licenseKey)
            
            Me.IsSingleInstance = False
            Me.EnableVisualStyles = True
            Me.SaveMySettingsOnExit = True
            Me.ShutdownStyle = Global.Microsoft.VisualBasic.ApplicationServices.ShutdownMode.AfterMainFormCloses
        End Sub
    End Class
End Namespace

设置环境变量

Windows（PowerShell）：

# For current session
$env:SYNCFUSION_LICENSE_KEY = "your-license-key-value"

# Permanent (User level)
[System.Environment]::SetEnvironmentVariable("SYNCFUSION_LICENSE_KEY", "your-license-key-value", "User")

# Permanent (System level - requires admin)
[System.Environment]::SetEnvironmentVariable("SYNCFUSION_LICENSE_KEY", "your-license-key-value", "Machine")

Windows（命令提示符）：

setx SYNCFUSION_LICENSE_KEY "your-license-key-value"

常见模式

模式 1：许可证密钥注册工作流

实现 Syncfusion 许可时：

1. 生成 Syncfusion 帐户中的许可证密钥
2. 添加引用，指向 Syncfusion.Licensing.dll
3. 注册 应用程序入口点处的许可证密钥（在初始化任何 Syncfusion 控件之前）
4. 验证 未出现许可证验证错误

模式 2：许可证错误排查

遇到许可证验证错误时：

1. 识别 具体的错误消息
2. 确认 许可证密钥适用于正确的版本和平台
3. 检查 注册位置（必须在控件初始化之前）
4. 确保 已引用 Syncfusion.Licensing.dll，且 Copy Local = True
5. 重新生成 许可证密钥（如有需要）

模式 3：CI/CD 许可证验证

在 CI 流水线中实现许可证验证时：

1. 将 许可证密钥安全存储在 CI/CD 机密中（绝不要放入源代码管理）
2. 选择验证方法：
   • 推荐： 在单元测试中使用 ValidateLicense() 方法
   • 替代方案： 使用 LicenseKeyValidator 实用工具（并进行安全验证）
3. 配置 验证流程，从环境变量中读取许可证密钥
4. 集成 CI 流水线中的验证（Azure、GitHub Actions、Jenkins）
5. 验证 部署前的许可证
6. 妥善处理 验证失败

安全要求：

• ✅ 使用 CI/CD 机密管理（Azure Key Vault、GitHub Secrets、Jenkins Credentials）
• ✅ 仅从环境变量读取密钥
• ❌ 绝不要在脚本中硬编码密钥
• ❌ 绝不要将密钥提交到源代码管理中

模式 4：从试用版升级到许可版

试用后购买许可证时：

1. 选项 A： 卸载试用版，从 License & Downloads 安装许可版
2. 选项 B：（适用于 NuGet 用户）将试用许可证密钥替换为付费许可证密钥
3. 确认 应用程序中的许可证注册
4. 测试 确认不再出现试用版消息

核心概念

许可证密钥安全最佳实践

1. 绝不要硬编码许可证密钥

   • ❌ 不要将密钥直接嵌入源代码
   • ❌ 不要将密钥提交到版本控制（Git、SVN 等）
   • ❌ 不要将密钥包含在已提交到源代码管理的构建脚本中

2. 使用安全的存储方式

   • ✅ 环境变量（推荐用于本地开发）
   • ✅ 从源代码管理中排除的配置文件（.gitignore）
   • ✅ CI/CD 机密管理（GitHub Secrets、Azure Key Vault、Jenkins Credentials）
   • ✅ 安全配置管理系统（Azure App Configuration、AWS Secrets Manager）

3. 访问控制

   • 限制能够访问许可证密钥的人员
   • 如果密钥泄露，请定期轮换密钥
   • 审计生产环境中的密钥使用情况

4. CI/CD 安全

   • 使用流水线机密变量
   • 绝不要在构建输出中回显或记录许可证密钥
   • 通过环境变量在运行时注入密钥

示例 — 错误做法：

// ❌ WRONG: Hardcoded key in source code
SyncfusionLicenseProvider.RegisterLicense("Mgo+DSMBaFt/QHRq...");

示例 — 正确做法：

// ✅ CORRECT: Key from environment variable
string key = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
SyncfusionLicenseProvider.RegisterLicense(key);

许可证密钥的主要特点

• **特定版本：**许可证密钥必须与 Syncfusion 程序集版本匹配
• **特定平台：**Windows Forms 密钥仅适用于 Windows Forms 平台
• **离线验证：**运行时无需连接互联网
• **字符串格式：**许可证密钥是通过 RegisterLicense() 注册的字符串
• **敏感数据：**应作为机密凭据妥善保管（如密码或 API 密钥）

注册要求

程序集来源	是否需要注册许可证？	密钥获取位置
nuget.org 上的 NuGet 包	✅ 是	License & Downloads / Trial & Downloads
试用版安装程序	✅ 是	Trial & Downloads
已授权的安装程序	❌ 否	不适用

关键注册规则

1. **时机：**在初始化任何 Syncfusion 控件之前注册许可证密钥
2. 位置：
   • C#：在 Main() 方法中、Application.Run() 之前
   • VB.NET：在 Application.Designer.vb 构造函数或 Program.vb 中
3. **依赖项：**确保已引用 Syncfusion.Licensing.dll，且 Copy Local = True
4. **格式：**将许可证密钥字符串放在双引号之间

常见用例

用例 1：首次设置 Syncfusion 许可证

**场景：**开发者在新的 Windows Forms 项目中使用 NuGet 包设置 Syncfusion。

方法：

1. 阅读 references/licensing-overview.md，了解相关要求
2. 阅读 references/license-generation.md，生成密钥
3. 阅读 references/license-registration.md，实现注册
4. 测试应用程序，确认没有许可证错误

用例 2：解决许可证验证错误

**场景：**应用程序显示“License key not registered”或“Invalid key”错误。

方法：

1. 阅读 references/licensing-errors.md，确定具体错误
2. 确认许可证密钥的版本和平台匹配
3. 检查注册代码的位置和时机
4. 如有需要，重新生成许可证密钥
5. 确认 Syncfusion.Licensing.dll 引用无误

用例 3：配置构建服务器

**场景：**为自动构建或 CI/CD 配置 Syncfusion 许可。

方法：

1. 阅读 references/licensing-overview.md 中的构建服务器部分
2. 根据程序集来源确定是否需要注册许可证
3. 阅读 references/licensing-faqs.md 中的 CI/CD 部分，了解管道设置
4. 在 CI 管道中实现许可证验证
5. 测试构建流程

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

**场景：**开发者在使用试用版后购买了许可证。

方法：

1. 阅读 references/licensing-faqs.md 中的升级部分
2. 选择升级方式（重新安装或替换密钥）
3. 生成新的付费许可证密钥
4. 使用新密钥更新注册代码
5. 确认试用提示已移除

用例 5：升级版本

**场景：**将 Syncfusion 组件升级到新版本。

方法：

1. 从 License & Downloads 为目标版本生成新的许可证密钥
2. 将 NuGet 包或安装程序更新到新版本
3. 将旧许可证密钥替换为适用于新版本的密钥
4. 测试应用程序，确保兼容性
5. 如果出现错误，请阅读 references/licensing-errors.md

其他资源

• **Syncfusion 帐户：**https://www.syncfusion.com/account/manage-trials/downloads
• **License & Downloads：**https://www.syncfusion.com/account/downloads
• **支持：**https://support.syncfusion.com/

概述

此技能涵盖 Syncfusion Windows Forms 许可的完整生命周期：

• 了解许可要求和使用场景
• 为特定版本和平台生成许可证密钥
• 在 C# 和 VB.NET 应用程序中注册许可证密钥
• 排查常见的许可错误
• 实施 CI/CD 许可证验证
• 处理试用版和许可版本之间的切换

请始终根据具体需求（概述、生成、注册、错误或常见问题）先阅读相应的参考文件。