Skip to content

Example project

PackageGarden.Licensing.Example is a complete, compiled example of how a package wraps the validator. It is part of the solution, so every build checks that it still compiles against the validator's public API. It is never shipped.

It is the successor of the legacy PackageGarden.LicenseExample (validator 1.0.0, .NET Framework). What changed:

Legacy example This example
new Validator(parameters, key, "~/bin/TestLicense.lic", …) with a file path The 2.x constructor: IHttpContextAccessor and the license file as a Stream (the file-path constructor no longer exists)
Static singleton (ProductLicense.Instance) A ProductLicense service registered as a singleton through dependency injection
License in ~/bin License in a configurable LicenseFolder under the site's content root, default umbraco/Licenses; bin is often wiped on publish and deploy
Referenced an obfuscated DLL from a Binaries folder References the validator project (in your package: the NuGet package)

The wrapper

using System;
using System.IO;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using PackageGarden.Licensing;

namespace PackageGarden.Licensing.Example
{
    /// <summary>
    /// Use this class in your product to validate licenses
    /// </summary>
    public sealed class ProductLicense
    {
        //Change this to your own contact information. This message will be used in exceptions
        private const string LicenseSupportInfo = "Please contact Soeteman Software on support@soetemansoftware.nl";

        //Add the Product key from the generated product Licenses type in Umbraco here
        private const string ProductKey = "Enter your product key  here";

        //Add the Product parameters from the generated product Licenses type in Umbraco here
        private const string ProductParameters = "Enter the product parameters here";

        //The major version of the package
        private const int ProductVersion = 1;

        //Folder, relative to the site's content root, where customers place the license.
        //Change it to the folder your package documents.
        private const string LicenseFolder = "umbraco/Licenses";

        //License name format is always [productlicensetypename].lic
        private const string LicenseFileName = "TestLicense.lic";

        private readonly Lazy<Validator> _validator;

        public ProductLicense(IHttpContextAccessor httpContextAccessor, IWebHostEnvironment webHostEnvironment)
        {
            _validator = new Lazy<Validator>(() => CreateValidator(httpContextAccessor, webHostEnvironment.ContentRootPath));
        }

        /// <summary>
        /// The validator of this package, created on first use.
        /// </summary>
        /// <remarks>
        /// The validation context (host name, local request) is read from the request that first
        /// uses <see cref="Instance"/>, as the legacy static singleton did. Use <see cref="Instance"/>
        /// only while handling a request: first use outside a request (background job, scheduled
        /// task, startup code) fixes the host as "Unkown" and keeps domain and server licenses
        /// invalid until the application restarts.
        /// </remarks>
        public Validator Instance => _validator.Value;

        private static Validator CreateValidator(IHttpContextAccessor httpContextAccessor, string contentRootPath)
        {
            var licensePath = Path.Combine(contentRootPath, LicenseFolder, LicenseFileName);

            //No license file: the trial rules of the product parameters apply
            using (var licenseFile = File.Exists(licensePath) ? File.OpenRead(licensePath) : null)
            {
                return new Validator(httpContextAccessor, ProductParameters, ProductKey, licenseFile, LicenseSupportInfo, ProductVersion);
            }
        }
    }
}

Replace the constants with your own values:

  • ProductKey and ProductParameters: generated for your product by the license generator.
  • LicenseSupportInfo: your support text, appended to invalid-license messages.
  • ProductVersion: the major version of your package.
  • LicenseFolder and LicenseFileName: where your package tells customers to put their license. The file name format is [productlicensetypename].lic.

Replace the placeholders first

With the placeholder product key, the first use of Instance throws LicenseKeyCorruptException. The validator is created only once (Lazy<T>), so every later use throws the same exception until the application restarts.

Registration

using Microsoft.Extensions.DependencyInjection;

namespace PackageGarden.Licensing.Example
{
    public static class ServiceCollectionExtensions
    {
        /// <summary>
        /// Registers <see cref="ProductLicense"/> as a singleton, so the package has one validator.
        /// </summary>
        /// <example>
        /// In an Umbraco 18 composer: <c>builder.Services.AddProductLicense();</c>
        /// </example>
        public static IServiceCollection AddProductLicense(this IServiceCollection services)
        {
            services.AddHttpContextAccessor();
            services.AddSingleton<ProductLicense>();
            return services;
        }
    }
}

The example has no Umbraco dependency. In an Umbraco 18 package, register it from a composer:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;

public class ProductLicenseComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder) => builder.Services.AddProductLicense();
}

Using it

Inject ProductLicense where your package needs to know its license state, for example in a controller or a view component:

public class MyPackageController(ProductLicense productLicense) : Controller
{
    public IActionResult Index()
    {
        var validator = productLicense.Instance;
        if (!validator.IsValid())
        {
            return Content(validator.GetInvalidLicenseMessage());
        }

        return View(validator.IsTrial());
    }
}

Use Instance only while handling a request

The validator reads the host name and whether the request is local from the request that first uses Instance, as the legacy static singleton did. When Instance is first used from a background job, a scheduled task or startup code, the host is Unkown for the lifetime of the application: Domain and Server licenses stay invalid until the application restarts.

Try it

The example was checked in an Umbraco 18.3 site with the legacy test license: with the license in umbraco/Licenses, a local request reports a valid license; without it, the test product's local trial applies.