syncfusion-winforms-licensing（Synfusion winforms 许可）

Implementing Syncfusion Windows Forms Licensing

This skill provides comprehensive guidance for implementing and managing Syncfusion licensing in Windows Forms applications, including license key generation, registration, troubleshooting, and CI/CD integration.

When to Use This Skill

Use this skill immediately when you need to:

• Implement licensing in a Windows Forms application using Syncfusion components
• Resolve license validation errors or trial expiration messages
• Generate license keys for specific versions and platforms
• Register license keys in C# or VB.NET Windows Forms applications
• Troubleshoot licensing issues such as invalid keys, platform mismatches, or version mismatches
• Configure CI/CD pipelines with license validation (Azure Pipelines, GitHub Actions, Jenkins)
• Understand licensing requirements for NuGet packages, trial installers, or licensed installers
• Upgrade from trial to licensed version after purchasing
• Handle build server licensing scenarios

Overview of Syncfusion Licensing

Starting with version 16.2.0.x, Syncfusion introduced a new licensing system that requires license key registration for:

• Applications using evaluation installers
• Applications referencing Syncfusion NuGet packages from nuget.org

Key Points:

• License keys are version and platform specific
• License keys are different from installer unlock keys
• Validation happens offline during application execution (no internet required)
• Licensed installer users do not need to register license keys
• Trial license keys expire after 30 days

Documentation and Navigation Guide

Understanding Licensing

📄 Read: references/licensing-overview.md

When to read this reference:

• Understanding the licensing system introduced in version 16.2.0.x
• Learning the difference between unlock keys and license keys
• Determining when license registration is required
• Understanding build server scenarios (NuGet vs Trial vs Licensed installers)
• Learning about version and platform specificity

Generating License Keys

📄 Read: references/license-generation.md

When to read this reference:

• Generating license keys from License & Downloads section
• Generating license keys from Trial & Downloads section
• Using the Claim License Key feature
• Handling active license scenarios
• Handling active trial scenarios
• Dealing with expired licenses
• Starting a trial when no license exists

Registering License Keys

📄 Read: references/license-registration.md

When to read this reference:

• Implementing the RegisterLicense method in C# or VB.NET
• Registering keys in Main() method for C# applications
• Registering keys in Application.Designer.vb for VB.NET
• Registering keys in Program.vb for VB.NET
• Understanding Syncfusion.Licensing.dll reference requirements
• Learning about offline validation capabilities

Troubleshooting Licensing Errors

📄 Read: references/licensing-errors.md

When to read this reference:

• Resolving "License key not registered" errors
• Fixing "Invalid key" errors
• Handling "Trial expired" messages
• Resolving platform mismatch errors
• Fixing version mismatch errors
• Troubleshooting "Could not load Syncfusion.Licensing.dll" errors
• Configuring Copy Local settings
• Understanding legacy errors (v16.2.0 - v20.3.0)

Common Questions and CI/CD Integration

📄 Read: references/licensing-faqs.md

When to read this reference:

• Implementing CI/CD license validation (Azure Pipelines, GitHub Actions, Jenkins)
• Using LicenseKeyValidator utility in build pipelines
• Understanding where to get license keys
• Checking if internet connection is required for validation
• Upgrading from trial to licensed version
• Registering Syncfusion account for NuGet.org users
• Understanding license key specificity

Quick Start Example

Here's a complete example of registering a Syncfusion license key in a Windows Forms application:

C# Example (Using Environment Variable - Recommended)

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());
        }
    }
}

Alternative: Using Configuration File (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 example:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <!-- DO NOT commit actual license key to source control -->
    <!-- Use environment-specific config files or CI/CD secrets -->
    <add key="SyncfusionLicenseKey" value="" />
  </appSettings>
</configuration>

VB.NET Example (Using Environment Variable - Recommended)

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

Setting Environment Variable

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 (Command Prompt):

setx SYNCFUSION_LICENSE_KEY "your-license-key-value"

Common Patterns

Pattern 1: License Key Registration Workflow

When implementing Syncfusion licensing:

1. Generate license key from Syncfusion account
2. Add reference to Syncfusion.Licensing.dll
3. Register license key at application entry point (before any Syncfusion control initialization)
4. Verify no license validation errors appear

Pattern 2: Troubleshooting License Errors

When encountering license validation errors:

1. Identify the specific error message
2. Verify license key is for correct version and platform
3. Check registration location (must be before control initialization)
4. Ensure Syncfusion.Licensing.dll is referenced and Copy Local = True
5. Regenerate license key if needed

Pattern 3: CI/CD License Validation

When implementing license validation in CI pipelines:

1. Store license key securely in CI/CD secrets (never in source control)
2. Choose validation method:

- Recommended: Use ValidateLicense() method in unit tests - Alternative: Use LicenseKeyValidator utility (with security verification)

1. Configure validation to read license key from environment variables
2. Integrate validation in CI pipeline (Azure, GitHub Actions, Jenkins)
3. Validate license before deployment
4. Handle validation failures appropriately

Security Requirements:

• ✅ Use CI/CD secret management (Azure Key Vault, GitHub Secrets, Jenkins Credentials)
• ✅ Read keys from environment variables only
• ❌ Never hardcode keys in scripts
• ❌ Never commit keys to source control

Pattern 4: Upgrading from Trial to Licensed

When purchasing a license after trial:

1. Option A: Uninstall trial, install licensed version from License & Downloads
2. Option B: (For NuGet users) Replace trial license key with paid license key
3. Verify license registration in application
4. Test to ensure no trial messages appear

Key Concepts

Security Best Practices for License Keys

1. Never Hardcode License Keys

- ❌ Don't embed keys directly in source code - ❌ Don't commit keys to version control (Git, SVN, etc.) - ❌ Don't include keys in build scripts checked into source control

1. Use Secure Storage Methods

- ✅ Environment variables (recommended for local development) - ✅ Configuration files excluded from source control (.gitignore) - ✅ CI/CD secret management (GitHub Secrets, Azure Key Vault, Jenkins Credentials) - ✅ Secure configuration management systems (Azure App Configuration, AWS Secrets Manager)

1. Access Control

- Limit who can access license keys - Rotate keys periodically if exposed - Audit key usage in production environments

1. CI/CD Security

- Use pipeline secret variables - Never echo/log license keys in build output - Inject keys at runtime through environment variables

Example - What NOT to Do:

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

Example - Correct Approach:

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

License Key Characteristics

• Version-specific: License key must match Syncfusion assembly version
• Platform-specific: Windows Forms keys only work for Windows Forms platform
• Offline validation: No internet connection required during runtime
• String format: License key is a string registered via RegisterLicense()
• Sensitive data: Treat as confidential credential (like passwords or API keys)

Registration Requirements

Critical Registration Rules

1. Timing: Register license key BEFORE initializing any Syncfusion control
2. Location:

- C#: In Main() method before Application.Run() - VB.NET: In Application.Designer.vb constructor or Program.vb

1. Dependencies: Ensure Syncfusion.Licensing.dll is referenced with Copy Local = True
2. Format: Place license key string between double quotes

Common Use Cases

Use Case 1: First-Time Syncfusion License Setup

Scenario: Developer setting up Syncfusion in a new Windows Forms project using NuGet packages.

Approach:

1. Read references/licensing-overview.md to understand requirements
2. Read references/license-generation.md to generate key
3. Read references/license-registration.md to implement registration
4. Test application to verify no license errors

Use Case 2: Resolving License Validation Error

Scenario: Application shows "License key not registered" or "Invalid key" error.

Approach:

1. Read references/licensing-errors.md to identify specific error
2. Verify license key version and platform match
3. Check registration code location and timing
4. Regenerate license key if needed
5. Verify Syncfusion.Licensing.dll reference

Use Case 3: Build Server Configuration

Scenario: Setting up Syncfusion licensing for automated builds or CI/CD.

Approach:

1. Read references/licensing-overview.md build server section
2. Determine if license registration is required based on assembly source
3. Read references/licensing-faqs.md CI/CD section for pipeline setup
4. Implement license validation in CI pipeline
5. Test build process

Use Case 4: Trial to Licensed Upgrade

Scenario: Developer purchased license after using trial version.

Approach:

1. Read references/licensing-faqs.md upgrade section
2. Choose upgrade approach (reinstall or key replacement)
3. Generate new paid license key
4. Update registration code with new key
5. Verify trial message is removed

Use Case 5: Version Upgrade

Scenario: Upgrading Syncfusion components to a new version.

Approach:

1. Generate new license key for target version from License & Downloads
2. Update NuGet packages or installer to new version
3. Replace old license key with new version-specific key
4. Test application to ensure compatibility
5. If errors occur, read references/licensing-errors.md

Additional Resources

• Syncfusion Account: https://www.syncfusion.com/account/manage-trials/downloads
• License & Downloads: https://www.syncfusion.com/account/downloads
• Support: https://support.syncfusion.com/

Summary

This skill covers the complete lifecycle of Syncfusion Windows Forms licensing:

• Understanding licensing requirements and scenarios
• Generating license keys for specific versions and platforms
• Registering license keys in C# and VB.NET applications
• Troubleshooting common licensing errors
• Implementing CI/CD license validation
• Handling trial and licensed version transitions

Always start by reading the appropriate reference file based on your specific need (overview, generation, registration, errors, or FAQs).