Licensing for Syncfusion.NET MAUI
Comprehensive guide for managing Syncfusion.NET MAUI licenses, from generation to registration and troubleshooting.
When to Use This Skill
Use this skill immediately when you encounter:
Licensing Errors:
- "This application was built using a trial version" message
- "The included Syncfusion license key is invalid" error
- License validation failures
- Platform mismatch errors
- Version mismatch errors
- Trial expired messages
License Key Tasks:
- Generating license keys from Syncfusion account
- Registering license keys in applications
- Understanding trial vs licensed installations
- Differentiating unlock key from license key
- Configuring licensing for build servers
- Setting up CI/CD license validation
Common Scenarios:
- Initial app setup with Syncfusion components
- Resolving license warnings during development
- Deploying applications with proper licensing
- Upgrading from trial to licensed version
- Managing licenses for multiple projects
- Troubleshooting "Could not load Syncfusion.Licensing.dll" errors
Licensing System Overview
Starting with version 20.2.0.x, Syncfusion introduced a new licensing system that applies to:
- NuGet packages from nuget.org
- Evaluation installers
- Trial licenses
Key Points:
- License keys are version and platform specific
- Registration is required for NuGet packages and trial installers
- Licensed installers do NOT require license key registration
- License validation is offline (no internet required)
- License keys are different from installer unlock keys
Documentation and Navigation Guide
Understanding Licensing
When to Read: First-time setup, understanding licensing requirements, or clarifying trial vs licensed installations.
📄 Read: references/licensing-overview.md
- Licensing system introduction (v20.2.0.x changes)
- When license key registration is required
- Trial vs licensed installation differences
- Unlock key vs license key distinction
- Build server licensing scenarios
- NuGet package licensing requirements
- Version and platform specificity
Generating License Keys
When to Read: Need to obtain a new license key, working with trial licenses, or managing license for different versions/platforms.
📄 Read: references/license-generation.md
- Accessing License & Downloads section
- Accessing Trial & Downloads section
- Using Claim License Key feature
- Generating keys for active licenses
- Generating keys for active trials
- Handling expired licenses (temporary 5-day keys)
- Setting up accounts for NuGet.org users
- Platform and version-specific key generation
Registering License Keys
When to Read: Need to register a license key in your application, choosing registration location, or implementing proper licensing.
📄 Read: references/license-registration.md
- RegisterLicense() method syntax
- Registration in App.xaml.cs constructor
- Registration in MauiProgram.cs
- Syncfusion.Licensing.dll reference requirements
- Best practices for registration location
- Multiple registration scenarios
- Complete code examples for each approach
Troubleshooting Licensing Errors
When to Read: Encountering license validation errors, trial expiration messages, platform/version mismatches, or assembly loading issues.
📄 Read: references/licensing-errors.md
- License key not registered error
- Invalid key error messages
- Trial expired errors
- Platform mismatch errors
- Version mismatch errors
- "Could not load Syncfusion.Licensing.dll" issues
- Solutions for each error type
- Version-specific error variations
- Copy Local configuration for assemblies
Advanced Topics and FAQ
When to Read: Setting up CI/CD pipelines, programmatic license validation, offline deployment questions, or upgrading from trial.
📄 Read: references/licensing-faq.md
- CI/CD license validation (Azure Pipelines, GitHub Actions, Jenkins)
- ValidateLicense() method for programmatic checks
- Unit testing with license validation
- Internet connection requirements (offline validation)
- Upgrading from trial to licensed version
- NuGet.org user account registration
- Where to obtain license keys
- Common frequently asked questions
Quick Start Guide
Step 1: Generate License Key
- Log in to your Syncfusion account
- Navigate to License & Downloads (licensed) or Trial & Downloads (trial)
- Generate a license key for .NET MAUI platform and your specific version
- Copy the generated license key
Step 2: Register License Key
Choose one of these registration methods:
Option A: Register in App.xaml.cs
public App()
{
// Register Syncfusion license
string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
if (!string.IsNullOrEmpty(licenseKey))
{
Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(licenseKey);
}
InitializeComponent();
MainPage = new AppShell();
}Option B: Register in MauiProgram.cs
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
// Register the Syncfusion license key
string licenseKey = Environment.GetEnvironmentVariable("SYNCFUSION_LICENSE_KEY");
if (!string.IsNullOrEmpty(licenseKey))
{
Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(licenseKey);
}
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureSyncfusionCore()
.ConfigureFonts(fonts =>
{
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
});
return builder.Build();
}
}Step 3: Verify Registration
Run your application. If properly registered, you should NOT see any licensing warning messages.
Common Patterns
Pattern 1: Initial Setup for New Projects
Scenario: Starting a new.NET MAUI project with Syncfusion components from NuGet.
Steps:
- Install Syncfusion NuGet packages
- Generate license key for MAUI platform + your version
- Register license key in MauiProgram.cs before ConfigureSyncfusionCore()
- Ensure Syncfusion.Licensing package is installed
- Build and run to verify no licensing warnings
Pattern 2: Resolving "Trial Version" Warning
Scenario: Application shows "This application was built using a trial version" message.
Solution:
- Verify you have a valid license key (not expired)
- Check the license key is for correct platform (MAUI)
- Check the license key version matches your package version
- Register the license key before InitializeComponent() or before ConfigureSyncfusionCore()
- Clean and rebuild the application
Pattern 3: Version Mismatch Error
Scenario: Error message shows "included Syncfusion license ({Registered Version}) is invalid for version {Required version}"
Solution:
- Check your NuGet package versions (all should be same version)
- Generate new license key for the exact version you're using
- Replace old license key with new one
- Clean solution and rebuild
Pattern 4: Build Server / CI/CD Setup
Scenario: Need to validate licensing during continuous integration.
Approaches:
- Use LicenseKeyValidator utility in CI pipeline
- Implement ValidateLicense() method with unit tests
- Configure environment variables for license key
- Fail build if validation fails
Read: references/licensing-faq.md for detailed CI/CD setup instructions.
Pattern 5: Multiple Projects in Solution
Scenario: Solution has multiple MAUI projects using Syncfusion components.
Solution:
- Register license key in each project's App.xaml.cs or MauiProgram.cs
- Use same license key across all projects (if same version)
- Ensure all projects reference Syncfusion.Licensing.dll
- Consider using shared constant for license key string
Key Concepts
License Key vs Unlock Key
- Unlock Key: Used to unlock the Syncfusion installer during installation
- License Key: Required in your application code when using NuGet packages or trial installer
- These are different keys with different purposes
Version and Platform Specificity
License keys are tied to:
- Platform: MAUI, WPF, Blazor, etc. (use MAUI license for MAUI apps)
- Version: Major.Minor.Patch (e.g., 26.2.4)
A MAUI 26.2.4 license key will NOT work for:
- Different platform (e.g., Blazor)
- Different version (e.g., 26.1.0 or 27.0.0)
When License Registration is Required
Required:
- NuGet packages from nuget.org
- Trial installer assemblies
- Evaluation scenarios
NOT Required:
- Licensed installer assemblies (license embedded in assemblies)
Offline Validation
- License validation happens offline during application execution
- No internet connection required for validation
- Apps can be deployed to systems without internet access
Common Use Cases
Use Case 1: First-Time Developer Setup
User: "I just installed Syncfusion MAUI components from NuGet and I'm getting a trial license warning."
Solution:
- Read references/licensing-overview.md to understand licensing requirements
- Read references/license-generation.md to generate appropriate key
- Read references/license-registration.md to register in your app
Use Case 2: Deployment Issues
User: "My app works fine in development but shows licensing errors when deployed."
Solution:
- Verify Syncfusion.Licensing.dll is included in deployment
- Check Copy Local is set to True for Syncfusion assemblies
- Read references/licensing-errors.md for "Could not load" troubleshooting
Use Case 3: Trial to Licensed Upgrade
User: "I purchased a license, how do I remove the trial warning?"
Solution:
- Read references/licensing-faq.md - "Upgrading from Trial" section
- Generate new licensed key (not trial key)
- Replace trial key with licensed key in RegisterLicense() call
- Clean and rebuild application
Use Case 4: CI/CD Integration
User: "How do I validate licensing in Azure DevOps pipeline?"
Solution: Read references/licensing-faq.md for complete CI/CD setup including:
- Azure Pipelines (YAML and Classic)
- GitHub Actions
- Jenkins
- Unit test approach with ValidateLicense()
Important Notes
- Always register license key before InitializeComponent() in App.xaml.cs or before ConfigureSyncfusionCore() in MauiProgram.cs
- Keep license keys secure (don't commit to public repositories)
- Use the same license key for all Syncfusion packages in your project
- Ensure all Syncfusion packages are the same version
- License validation errors are shown at runtime, not compile time