syncfusion-maui-licensing

name	syncfusion-maui-licensing
description	Sets up and validates Syncfusion .NET MAUI licensing, including license key registration, generation, and error resolution. Use when encountering trial license warnings ("This application was built using a trial version"), licensing errors, license key registration, unlock key vs license key confusion, build server or CI/CD licensing, NuGet package licensing requirements, platform mismatch errors, or version mismatch errors.
metadata	{"author":"Syncfusion Inc","version":"34.1.29"}

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

1. Log in to your Syncfusion account
2. Navigate to License & Downloads (licensed) or Trial & Downloads (trial)
3. Generate a license key for .NET MAUI platform and your specific version
4. 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:

1. Install Syncfusion NuGet packages
2. Generate license key for MAUI platform + your version
3. Register license key in MauiProgram.cs before ConfigureSyncfusionCore()
4. Ensure Syncfusion.Licensing package is installed
5. 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:

1. Verify you have a valid license key (not expired)
2. Check the license key is for correct platform (MAUI)
3. Check the license key version matches your package version
4. Register the license key before InitializeComponent() or before ConfigureSyncfusionCore()
5. 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:

1. Check your NuGet package versions (all should be same version)
2. Generate new license key for the exact version you're using
3. Replace old license key with new one
4. 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:

1. Register license key in each project's App.xaml.cs or MauiProgram.cs
2. Use same license key across all projects (if same version)
3. Ensure all projects reference Syncfusion.Licensing.dll
4. 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:

1. Read references/licensing-overview.md to understand licensing requirements
2. Read references/license-generation.md to generate appropriate key
3. 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:

1. Verify Syncfusion.Licensing.dll is included in deployment
2. Check Copy Local is set to True for Syncfusion assemblies
3. 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:

1. Read references/licensing-faq.md - "Upgrading from Trial" section
2. Generate new licensed key (not trial key)
3. Replace trial key with licensed key in RegisterLicense() call
4. 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