Skip to content

Integrating the validator

Every Soeteman Software package validates its license with the PackageGarden.Licensing library. This page explains how a package uses it. The rules it applies are described in Licensing Concepts; a complete, compiled wrapper is the example project.

Install

dotnet add package PackageGarden.Licensing --version 2.1.0
Target Used by
net10.0 Umbraco 18 sites. Uses the shared ASP.NET Core framework; no extra packages
netstandard2.0 Package versions that run on older runtimes. Brings Microsoft.AspNetCore.Http.Abstractions 2.2.0

The library has no dependency on Umbraco. Version 2.1.0 has the same assembly version (2.0.0.0) and the same public API as 2.0.0, so packages built against either version can run side by side in one site. Package versions come from release tags (see Releasing); the assembly version stays 2.0.0.0 in every release.

What a package needs

Value Where it comes from
Product key Generated once per product by the license generator; compiled into the package
Product parameters Generated with the product key; holds the trial settings; compiled into the package
Support text Your own text, appended to every invalid-license message
Package version The package's major version, compared with the license's validUntilVersion
License file The customer's .lic file, read as a stream; null when there is none

The product key and parameters are secrets of your package: do not publish them in documentation or issue trackers.

Create the validator

var validator = new Validator(
    httpContextAccessor,   // IHttpContextAccessor
    productParameters,
    productKey,
    licenseStream,         // Stream, or null when there is no license file
    licenseSupportInfo,
    packageMajorVersion);

The constructor reads the host name, whether the request is local and the machine's IP addresses once, from the current request. Create the validator while handling a request; without one the host is Unkown and Domain and Server licenses are invalid.

The license stream is read as UTF-8 inside the constructor, so you can dispose it right after.

Ask the validator

Method Returns
IsValid() true for a valid license or a valid trial
IsTrial() true when there is no license file and the product parameters allow a trial for this request
GetInvalidLicenseMessage() Why the last check failed (HTML), or an empty string
LicensedDomainsOrIps() The domains or IP addresses the license covers, for display

Typical use:

if (!validator.IsValid())
{
    // Show validator.GetInvalidLicenseMessage() and run in unlicensed mode.
}
else if (validator.IsTrial())
{
    // Show a trial notice.
}

IsValid() remembers a valid result; an invalid result is checked again on the next call. IsTrial() remembers its first result. Keep one validator per package, for example as a singleton; the example project shows how.

Exceptions

All exceptions derive from PackageGarden.Licensing.Exceptions.LicensingException.

Exception When
LicenseKeyCorruptException The product key or product parameters are empty or corrupt (a packaging error)
LicenseDllCorruptException The validator library was tampered with

An invalid, expired or foreign license file never throws: IsValid() returns false.

Upgrading a package

See Upgrading a package for moving from 1.0.0 or 2.0.0 to 2.1.0.