syncfusion-winforms-licensing

# 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](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](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](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](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](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) ```csharp 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) ```csharp 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 <?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) ```vb 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):** ```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):** ```cmd 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) 3. **Configure** validation to read license key from environment variables 4. **Integrate** validation in CI pipeline (Azure, GitHub Actions, Jenkins) 5. **Validate** license before deployment 6. **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 2. **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) 3. **Access Control** - Limit who can access license keys - Rotate keys periodically if exposed - Audit key usage in production environments 4. **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:** ```csharp // ❌ WRONG: Hardcoded key in source code SyncfusionLicenseProvider.RegisterLicense("Mgo+DSMBaFt/QHRq..."); ``` **Example - Correct Approach:** ```csharp // ✅ 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 | Assembly Source | License Registration Required? | Where to Get Key | |----------------|-------------------------------|------------------| | NuGet packages from nuget.org | ✅ Yes | License & Downloads / Trial & Downloads | | Trial installer | ✅ Yes | Trial & Downloads | | Licensed installer | ❌ No | Not applicable | ### 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` 3. **Dependencies:** Ensure `Syncfusion.Licensing.dll` is referenced with Copy Local = True 4. **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](references/licensing-overview.md) to understand requirements 2. Read [references/license-generation.md](references/license-generation.md) to generate key 3. Read [references/license-registration.md](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](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](references/licensing-overview.md) build server section 2. Determine if license registration is required based on assembly source 3. Read [references/licensing-faqs.md](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](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](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).