Back to Details

syncfusion-wpf-licensing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Licensing

Syncfusion许可实施指南

A comprehensive guide for generating, registering, and troubleshooting Syncfusion license keys across all platforms (WPF, Blazor, React, MAUI, Angular, Vue, ASP.NET Core, etc.).
一份适用于所有平台（WPF、Blazor、React、MAUI、Angular、Vue、ASP.NET Core等）的Syncfusion许可密钥生成、注册及故障排查综合指南。

Overview

概述

Starting with version 16.2.0.x, Syncfusion introduced a licensing system that applies to:
  • All evaluators using trial installers
  • Paid customers using NuGet packages from nuget.org
If you use the evaluation installer or NuGet packages, you must register a valid license key in your application to avoid license validation messages.
Key Points:
  • License keys are version and platform specific
  • Registration is done offline (no internet connection required)
  • Different from the installer unlock key
  • Required for NuGet packages from nuget.org and trial installers
  • NOT required for licensed installers (assemblies from licensed installation)
从16.2.0.x版本开始，Syncfusion推出了一套许可系统，适用于：
  • 所有使用试用安装包的评估用户
  • 使用nuget.org上NuGet包的付费客户
如果您使用评估安装包或NuGet包，必须在应用中注册有效的许可密钥，以避免出现许可验证提示。
核心要点：
  • 许可密钥与版本和平台绑定
  • 注册过程为离线操作（无需联网）
  • 与安装包解锁密钥不同
  • 使用nuget.org的NuGet包和试用安装包时必须注册
  • 无需为授权安装包（来自授权安装的程序集）注册

When to Use This Skill

何时使用此技能

Use this skill immediately when users need to:
  • Generate license keys for Syncfusion components
  • Register license keys in their applications (WPF, Blazor, React, etc.)
  • Troubleshoot licensing errors (trial expired, invalid key, platform/version mismatch)
  • Set up CI/CD license validation (Azure Pipelines, GitHub Actions, Jenkins)
  • Upgrade from trial to licensed version
  • Understand license vs unlock key differences
  • Configure build server licensing
  • Resolve "license validation message" errors
  • Register Syncfusion accounts for NuGet.org users
  • Validate licenses programmatically using 
    ValidateLicense()
    method
当用户需要以下帮助时，可立即使用此技能：
  • 生成Syncfusion组件的许可密钥
  • 在应用中注册许可密钥（WPF、Blazor、React等）
  • 排查许可错误（试用过期、密钥无效、平台/版本不匹配）
  • 设置CI/CD许可验证（Azure Pipelines、GitHub Actions、Jenkins）
  • 从试用版升级到授权版
  • 理解许可密钥与解锁密钥的区别
  • 配置构建服务器许可
  • 解决「许可验证提示」错误
  • 为NuGet.org用户注册Syncfusion账户
  • 使用
    ValidateLicense()
    方法以编程方式验证许可

Understanding License Types

理解许可类型

When License Registration is Required

何时需要注册许可

Syncfusion SourceLicense Registration Required?Notes
NuGet packages (nuget.org)✅ YESVersion and platform specific key required
Trial installer✅ YESFree 30-day trial key required
Licensed installer❌ NONo registration needed
Syncfusion获取来源是否需要注册许可？说明
NuGet包 (nuget.org)✅ 是需要对应版本和平台的专属密钥
试用安装包✅ 是需要免费30天试用密钥
授权安装包❌ 否无需注册

License Key vs Unlock Key

许可密钥与解锁密钥的区别

  • License Key: Registered in application code using 
    SyncfusionLicenseProvider.RegisterLicense()
  • Unlock Key: Used to unlock the Syncfusion installer (older system)
  • These are different keys and serve different purposes
  • 许可密钥：在应用代码中通过
    SyncfusionLicenseProvider.RegisterLicense()
    注册
  • 解锁密钥：用于解锁Syncfusion安装包（旧系统）
  • 这是两种不同的密钥，用途各异

Documentation and Navigation Guide

文档与导航指南

Getting Started with Licensing

许可入门

📄 Read: references/overview-and-differences.md
  • Licensing system overview
  • License key vs unlock key differences
  • When license keys are required (NuGet, trial, licensed installers)
  • Build server licensing requirements
  • Platform and version specificity
  • Registering keys in build environments
📄 阅读： references/overview-and-differences.md
  • 许可系统概述
  • 许可密钥与解锁密钥的区别
  • 何时需要许可密钥（NuGet、试用、授权安装包）
  • 构建服务器许可要求
  • 平台与版本绑定特性
  • 在构建环境中注册密钥

Generating License Keys

生成许可密钥

📄 Read: references/generating-license-keys.md
  • Where to generate keys (License & Downloads, Trial & Downloads)
  • Using the "Claim License Key" feature
  • Handling active licenses vs active trials
  • Dealing with expired licenses (temporary 5-day keys)
  • Platform and version selection guidance
📄 阅读： references/generating-license-keys.md
  • 密钥生成位置（许可与下载、试用与下载）
  • 使用「申领许可密钥」功能
  • 处理有效许可与有效试用
  • 处理过期许可（临时5天密钥）
  • 平台与版本选择指南

Registering License Keys

注册许可密钥

📄 Read: references/registering-license-keys.md
  • Platform-specific registration code placement
  • WPF: App.xaml.cs constructor registration (C# and VB)
  • Blazor, React, Angular, Vue, MAUI registration patterns
  • Syncfusion.Licensing.dll requirements
  • Offline validation capabilities
  • Registration code examples
📄 阅读： references/registering-license-keys.md
  • 特定平台的注册代码放置位置
  • WPF：在App.xaml.cs构造函数中注册（C#和VB）
  • Blazor、React、Angular、Vue、MAUI的注册模式
  • Syncfusion.Licensing.dll的要求
  • 离线验证能力
  • 注册代码示例

Troubleshooting Licensing Errors

排查许可错误

📄 Read: references/licensing-errors.md
  • "License key not registered" error
  • "Invalid key" error
  • "Trial expired" error
  • "Platform mismatch" error
  • "Version mismatch" error
  • "Could not load Syncfusion.Licensing.dll" error
  • Solutions for each error type
  • Copy Local settings for assemblies
  • Error messages by version (16.2.0+ vs 20.3.0+)
📄 阅读： references/licensing-errors.md
  • 「未注册许可密钥」错误
  • 「密钥无效」错误
  • 「试用过期」错误
  • 「平台不匹配」错误
  • 「版本不匹配」错误
  • 「无法加载Syncfusion.Licensing.dll」错误
  • 每种错误类型的解决方案
  • 程序集的复制本地设置
  • 不同版本的错误提示（16.2.0+ vs 20.3.0+）

CI/CD License Validation

CI/CD许可验证

📄 Read: references/ci-license-validation.md
  • LicenseKeyValidator utility setup and usage
  • Azure Pipelines (YAML and Classic) integration
  • GitHub Actions integration
  • Jenkins pipeline integration
  • ValidateLicense() method for programmatic validation
  • Unit test project validation approach
  • Preventing licensing errors during deployment
📄 阅读： references/ci-license-validation.md
  • LicenseKeyValidator工具的设置与使用
  • Azure Pipelines（YAML和经典模式）集成
  • GitHub Actions集成
  • Jenkins流水线集成
  • 使用ValidateLicense()方法进行编程式验证
  • 单元测试项目验证方法
  • 防止部署过程中出现许可错误

Upgrading and Account Setup

升级与账户设置

📄 Read: references/upgrading-and-account-setup.md
  • Upgrading from trial version after purchasing a license
  • Uninstall and reinstall process
  • Replacing trial keys with paid license keys
  • Registering Syncfusion account for NuGet.org users
  • Starting free 30-day trials
  • Internet connection requirements (offline validation works)
📄 阅读： references/upgrading-and-account-setup.md
  • 购买许可后从试用版升级
  • 卸载与重新安装流程
  • 用付费许可密钥替换试用密钥
  • 为NuGet.org用户注册Syncfusion账户
  • 开启免费30天试用
  • 联网要求（离线验证可用）

Quick Start Example

快速开始示例

WPF Application

WPF应用

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

public partial class App : Application
{
    public App()
    {
        // Register Syncfusion license key BEFORE initializing any components
        SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY_HERE");
        
        InitializeComponent();
    }
}
csharp
// In App.xaml.cs
using Syncfusion.Licensing;

public partial class App : Application
{
    public App()
    {
        // Register Syncfusion license key BEFORE initializing any components
        SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY_HERE");
        
        InitializeComponent();
    }
}

Blazor Server

Blazor Server

csharp
// In Program.cs
using Syncfusion.Licensing;

var builder = WebApplication.CreateBuilder(args);

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

// ... rest of your configuration
csharp
// In Program.cs
using Syncfusion.Licensing;

var builder = WebApplication.CreateBuilder(args);

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

// ... rest of your configuration

React/Angular/Vue

React/Angular/Vue

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

// Register license key before rendering components
registerLicense('YOUR_LICENSE_KEY_HERE');
javascript
// In your main entry point (e.g., index.js, main.ts)
import { registerLicense } from '@syncfusion/ej2-base';

// Register license key before rendering components
registerLicense('YOUR_LICENSE_KEY_HERE');

Common Licensing Scenarios

常见许可场景

Scenario 1: Trial User Setup

场景1：试用用户设置

  1. Register for a free Syncfusion account
  2. Start a 30-day trial from the account portal
  3. Generate trial license key from Trial & Downloads section
  4. Register the key in your application using 
    RegisterLicense()
  5. Trial key expires after 30 days
  1. 注册免费Syncfusion账户
  2. 从账户门户开启30天试用
  3. 从试用与下载板块生成试用许可密钥
  4. 使用
    RegisterLicense()
    在应用中注册密钥
  5. 试用密钥30天后过期

Scenario 2: Licensed User Setup

场景2：授权用户设置

  1. Log in to your Syncfusion account
  2. Go to License & Downloads section
  3. Generate license key for your specific version and platform
  4. Register the key in your application using 
    RegisterLicense()
  5. Key is valid for the specified version and platform
  1. 登录您的Syncfusion账户
  2. 进入许可与下载板块
  3. 为特定版本和平台生成许可密钥
  4. 使用
    RegisterLicense()
    在应用中注册密钥
  5. 密钥对指定版本和平台有效

Scenario 3: NuGet.org User Setup

场景3：NuGet.org用户设置

  1. Using Syncfusion packages from nuget.org requires license registration
  2. Register for a Syncfusion account if you don't have one
  3. Start a trial or purchase a license
  4. Generate and register the license key
  5. Without registration, you'll see license validation warnings
  1. 使用nuget.org上的Syncfusion包需要注册许可
  2. 若没有账户，注册Syncfusion账户
  3. 开启试用或购买许可
  4. 生成并注册许可密钥
  5. 未注册会显示许可验证警告

Scenario 4: Build Server / CI/CD

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

  1. License registration is required on build servers using NuGet packages
  2. Use any developer license to generate keys for build environments
  3. Register the key in your application code
  4. Optionally set up CI license validation to catch errors early
  5. No internet connection needed during build (offline validation)
  1. 使用NuGet包的构建服务器需要注册许可
  2. 使用任意开发者许可为构建环境生成密钥
  3. 在应用代码中注册密钥
  4. 可选择设置CI许可验证以提前发现错误
  5. 构建过程无需联网（离线验证）

Scenario 5: Upgrading from Trial

场景5：从试用版升级

  1. Purchase a Syncfusion license
  2. Option A: Uninstall trial installer, install licensed version from License & Downloads
  3. Option B: If using NuGet, generate paid license key and replace trial key
  4. Licensed installer assemblies don't require key registration
  5. NuGet packages always require key registration
  1. 购买Syncfusion许可
  2. 选项A：卸载试用安装包，从许可与下载板块安装授权版本
  3. 选项B：若使用NuGet，生成付费许可密钥并替换试用密钥
  4. 授权安装包的程序集无需注册密钥
  5. NuGet包始终需要注册密钥

Key Concepts

核心概念

Platform and Version Specificity

平台与版本绑定

  • License keys are version-specific: Key for v26.1.35 won't work for v26.2.4
  • License keys are platform-specific: WPF key won't work for Blazor
  • Generate separate keys for each platform/version combination
  • Use the correct version in your 
    RegisterLicense()
    call
  • 许可密钥与版本绑定：v26.1.35的密钥无法用于v26.2.4
  • 许可密钥与平台绑定：WPF密钥无法用于Blazor
  • 为每个平台/版本组合生成单独的密钥
  • 在
    RegisterLicense()
    调用中使用正确的版本

Offline Validation

离线验证

  • License validation happens offline during application execution
  • No internet connection required for apps to run
  • You can deploy to air-gapped systems
  • Validation checks happen at application startup
  • 许可验证在应用运行时离线进行
  • 应用运行无需联网
  • 可部署到隔离网络环境
  • 验证在应用启动时进行

Build Servers

构建服务器

  • Build servers using NuGet packages need license registration
  • Use any developer license to generate keys for CI/CD
  • Licensed installer assemblies on build servers don't need keys
  • Set up CI validation to prevent deployment errors
  • 使用NuGet包的构建服务器需要注册许可
  • 使用任意开发者许可为CI/CD生成密钥
  • 构建服务器上的授权安装包程序集无需密钥
  • 设置CI验证以防止部署错误

Syncfusion.Licensing.dll

Syncfusion.Licensing.dll

  • Required assembly for license registration
  • Ensure it's referenced in projects using 
    RegisterLicense()
  • Set "Copy Local" to 
    true
    to include in output
  • Available via NuGet: 
    Syncfusion.Licensing
  • 许可注册所需的程序集
  • 确保使用
    RegisterLicense()
    的项目已引用此程序集
  • 将「复制本地」设置为
    true
    以包含在输出中
  • 可通过NuGet获取：
    Syncfusion.Licensing

Registration Best Practices

注册最佳实践

  1. Register early: Call 
    RegisterLicense()
    before initializing any Syncfusion components
  2. One registration per app: Only need to register once at startup
  3. Use string literal: Place license key between double quotes in code
  4. Version matching: Ensure all Syncfusion packages use the same version
  5. Environment variables: Consider storing keys in environment variables or secure configuration
  6. Don't commit keys: Avoid committing license keys to public repositories
  7. CI/CD validation: Set up automated validation in build pipelines
  1. 尽早注册：在初始化任何Syncfusion组件之前调用
    RegisterLicense()
  2. 每个应用注册一次：仅需在启动时注册一次
  3. 使用字符串字面量：将许可密钥放在代码的双引号中
  4. 版本匹配：确保所有Syncfusion包使用相同版本
  5. 环境变量：考虑将密钥存储在环境变量或安全配置中
  6. 不要提交密钥：避免将许可密钥提交到公共仓库
  7. CI/CD验证：在构建流水线中设置自动验证

Error Prevention Checklist

错误预防检查清单

Before deploying your application:
  • License key generated for correct version and platform
  • RegisterLicense()
    called before any Syncfusion component initialization
  • All Syncfusion NuGet packages are the same version
  • Syncfusion.Licensing.dll is referenced and has "Copy Local" = true
  • License key matches the version of Syncfusion packages in use
  • For CI/CD: License validation configured in build pipeline
  • License key stored securely (not hardcoded in public repos)
部署应用前：
  • 已为正确版本和平台生成许可密钥
  • 在初始化任何Syncfusion组件之前调用了
    RegisterLicense()
  • 所有Syncfusion NuGet包版本相同
  • 已引用Syncfusion.Licensing.dll且「复制本地」= true
  • 许可密钥与使用的Syncfusion包版本匹配
  • 针对CI/CD：已在构建流水线中配置许可验证
  • 许可密钥已安全存储（未硬编码到公共仓库）

Related Skills

相关技能

  • Implementing Syncfusion WPF Components - WPF-specific component implementation
  • Implementing Syncfusion Blazor Components - Blazor components
  • Implementing Syncfusion React Components - React components
  • Implementing Syncfusion WPF Components - WPF特定组件实施
  • Implementing Syncfusion Blazor Components - Blazor组件
  • Implementing Syncfusion React Components - React组件