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.