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:
- Update the package reference to
PackageGarden.Licensing2.1.0. - For an Umbraco 18 package (
net10.0), the package now uses the shared ASP.NET Core framework. Fornetstandard2.0, 2.1.0 declares itsMicrosoft.AspNetCore.Http.Abstractionsdependency, so a reference you added only for the validator can go. - 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.