Skip to content

Upgrading from the Legacy Version

The Umbraco 18 version keeps the behavior of the previous version:

  • Licenses issued by the previous version keep validating with identical results.
  • Existing licensing data is preserved; schema changes ship as migrations that keep existing records.

Existing licenses

Customers need to do nothing. .lic files issued by the previous version keep working unchanged with the 2.0.0 validator:

  • The license format, the product keys and the product parameters are unchanged.
  • Every validation rule is the same: version, expiry, domain and IP matching, trials and the messages for invalid licenses. See Licensing Concepts.
  • The legacy test licenses are part of the automated tests and validate with the same results as before.

What changed, without effect on validation results:

Change Reason
The validator is no longer obfuscated Removes a licensed build tool from the build; can be added back later
The decryption uses Aes instead of RijndaelManaged RijndaelManaged is obsolete on current .NET; with these settings both are the same cipher, so every license decrypts to the same result
The Umbraco project is named PackageGarden.Licensing.Generator The name PackageGarden.Licensing stays with the validator that packages reference

Upgrading a package

Package authors move to PackageGarden.Licensing 2.1.0. The assembly name, namespaces, public API and assembly version (2.0.0.0) are unchanged.

From 2.0.0 or 2.0.0-alpha-2

No code changes:

  1. Update the package reference to PackageGarden.Licensing 2.1.0.
  2. For an Umbraco 18 package (net10.0), the package now uses the shared ASP.NET Core framework. For netstandard2.0, 2.1.0 declares its Microsoft.AspNetCore.Http.Abstractions dependency, so a reference you added only for the validator can go.
  3. Rebuild. Product key, product parameters and license files stay the same.

From 1.0.0 (.NET Framework)

1.0.0 took the license as a file path; that constructor does not exist since 2.0.0:

// 1.0.0
new Validator(productParameters, productKey, "~/bin/MyProduct.lic", supportInfo, version);

// 2.x
using var license = File.Exists(path) ? File.OpenRead(path) : null;
new Validator(httpContextAccessor, productParameters, productKey, license, supportInfo, version);

Replace the static singleton with a service that gets IHttpContextAccessor injected; the example project shows the complete wrapper. The product key, product parameters and license files stay the same.

Moving from the legacy license manager

The Licensing section replaces the license manager of the old Umbraco backoffice. It has the same fields, rules, messages and downloaded files, so a license issued from the new section validates exactly like one issued from the old system.

What changed

Legacy license manager New Licensing section
D-01 Delete No working delete Delete on each overview row, with confirmation; the record is kept and hidden
D-02 Technology WebForms pages in the old backoffice Umbraco 18 backoffice extension; same fields and behavior
D-03 Not carried over "Convert Deli license", the "My licenses" member helper, the website license helpers Not part of the section. Creating a license for a member by email is available to site code (ILicenseCommandService, see the Developer Guide)
D-04 Create Asked for the company name first Create license opens an empty editor whose first field is the company name
D-05 Missing member on download Failed with an error Refused with the message that the member can't be found
D-06 Several members with the email Used the first member found Saving is refused
D-07 Deleted product on a license Had to choose another product before saving The license keeps its deleted product, shown as "{name} (deleted)"
D-08 Product names Duplicates allowed Unique among products that are not deleted, ignoring letter case
D-09 Tree A Licenses node opened the overview The root Licensing opens the overview and has Create license
D-10 Paging 100 newest without search; all matches on one page with a search 100 per page with Umbraco's paging, with and without search; page 1 without search is the legacy view
D-11 Valid until version 1–50 1–99
D-12 Only entries the file leaves out A Domain or Server license with only localhost (or *.) entries was saved; its download failed Saving is refused; an imported record like that is refused on download with a message

Importing the legacy data

The new tables can hold every legacy record. An SQL script copies the data from the legacy database into the new tables; the mapping below is all the script needs. Run it after the site has started once with the package installed (so the tables exist), and before anyone creates licenses in the new section.

Legacy table New table Notes
LicenseGenerator_LicenseType PackageGardenLicensing_Product Keep the ids: SET IDENTITY_INSERT PackageGardenLicensing_Product ON
LicenseGenerator_License PackageGardenLicensing_License Keep the ids: SET IDENTITY_INSERT PackageGardenLicensing_License ON
LicenseGenerator_License_DomainsIps PackageGardenLicensing_LicenseDomainOrIp Keep the ids, so domains keep their order

Columns:

Legacy column New column Conversion
LicenseGenerator_LicenseType.Id Product.Id
ProductName Product.Name
ProductKey Product.ProductKey Unchanged
SupportsTrial Product.SupportsTrial NULL → 0
TrialSupportsLocalhostOnly Product.TrialSupportsLocalhostOnly NULL → 1
Deleted Product.IsDeleted NULL → 0
LicenseGenerator_License.Id License.Id
ProductLicenseTypelId License.ProductId
MemberId License.MemberKey The member's key: umbracoNode.uniqueId of the node with that id
Name License.CompanyName
LicenseType License.LicenseType domain/Domain → 0, server/Server → 1, unlimited/Unlimited → 2 (ignore letter case)
AlwaysAllowLocalhost License.AlwaysAllowLocalhost
LicenseValidUntilVersion License.ValidUntilVersion NULL = version independent
LicenseExpireDate License.ExpireDate
LicenseCreated License.CreatedDate
Deleted License.IsDeleted NULL → 0
LicenseGenerator_License_DomainsIps.Id LicenseDomainOrIp.Id
LicenseId LicenseDomainOrIp.LicenseId
DomainOrIP LicenseDomainOrIp.DomainOrIp Unchanged

All new tables are prefixed PackageGardenLicensing_. The member must exist in the new site's member data with the same key (the website's members move with the site). A license whose member no longer exists cannot be mapped: skip it, or map it to a placeholder member.

Imported licenses download as files that validate with the same results as the files the legacy system produced for them; the automated tests check this with the legacy test licenses.