Skip to content

Developer Guide

This guide summarizes the rules from the project constitution. When this guide and the constitution disagree, the constitution wins.

Platform

  • Umbraco 18 is the minimum supported version. APIs that are obsolete or removed in Umbraco 18 are not used.
  • Use Umbraco's extension points (composers, notification handlers, Management API controllers, backoffice manifests) instead of patching Umbraco internals.
  • Legacy AngularJS backoffice code is re-implemented on the current backoffice extension model, never ported as-is.
  • The validator library does not depend on Umbraco. It runs on the .NET version of Umbraco 18 and may also target netstandard2.0 for package versions on older runtimes.

Projects

Project Responsibility
PackageGarden.Licensing License validator library: license decryption and validation rules. Shipped as a NuGet package inside every Soeteman Software package
PackageGarden.Licensing.Generator Main Umbraco project: license issuing domain model, services, data access, Management API endpoints
PackageGarden.Licensing.Generator.Client Razor Class Library with the TypeScript backoffice extension and its compiled assets (presentation only)
PackageGarden.Licensing.Example Example consumer of the validator (ProductLicense wrapper); built with the solution, never shipped
PackageGarden.Licensing.Generator.Tests Tests of the license manager (NUnit 4, SQLite in-memory); never shipped

Each project may have one <Project>.Tests test project, which is never shipped.

How a package uses the validator: Integrating the validator and the example project.

The validator library has no dependency on Umbraco, EF Core, a database or the Management API, and its public API stays compatible with the legacy validator that packages already compile against. The generator reuses the validator instead of re-implementing validation rules.

The client talks to the server only through the Management API, using the generated OpenAPI client. Licensing rules are never duplicated or decided in TypeScript. New projects are added only when a spec or plan justifies it.

Architecture

The solution does not use a Clean Architecture project layout, but its principles and SOLID apply inside the existing projects:

  • Dependencies point inward. Domain logic does not depend on controllers, UI, Umbraco presentation types or EF Core specifics. Separation uses folders, namespaces and interfaces.
  • Single responsibility. Controllers stay thin and delegate to services; services have no HTTP or UI concerns.
  • Open/closed and Liskov. Extend behavior with new implementations and composition, not by modifying stable licensing rules.
  • Interface segregation. Small, focused interfaces, for example separate read and write services.
  • Dependency inversion. Collaborators are injected through interfaces and registered in Umbraco composers. No service locator, no static state.
  • Legacy validator API wins. Where the validator's legacy public API fixes a design (for example a public constructor that builds its own collaborators), the legacy API is kept. Internal seams keep that code testable, and the plan records the exception.

Data access

Umbraco uses PetaPoco/NPoco internally. PackageGarden.Licensing.Generator uses Entity Framework Core for all of its own data access. The validator library has no data access.

  • Reads use the read-only context. Every read (queries, lookups, list and detail views, license validation) uses a dedicated read-only context. It has change tracking disabled (QueryTrackingBehavior.NoTracking) and throws when saving is attempted.
  • Writes use the read/write context inside an explicit unit of work or transaction, and are never mixed into read-only code paths.
  • No NPoco or raw SQL for package tables, except inside EF Core migrations.
  • Schema changes are EF Core migrations that run automatically on install or upgrade and preserve existing data.

Backoffice conventions

  • Build UI with the Umbraco backoffice extension model (Lit elements, manifests, contexts, repositories) and Umbraco UI Library (UUI) components.
  • Follow the Umbraco backoffice skills so the extension behaves like built-in Umbraco functionality.
  • Custom CSS is limited to layout. Colors, typography and spacing come from Umbraco/UUI design tokens.
  • All user-facing text is localizable.

Security

  • Backoffice endpoints use Umbraco backoffice authorization.
  • Licensing secrets (signing keys, private keys) are never exposed to the client or committed to source control. Secrets that must be compiled into a shipped assembly are injected at build time (environment variable or CI secret).
  • One exception: the validator's fixed generator key and IV are committed as constants, as in the legacy solution. They can never change and ship readable in every package DLL. Because they are in the source, the repository stays private; making it public first needs a constitution amendment.

License manager

Packages

NuGet package Built from Contents
PackageGarden.LicenseGenerator PackageGarden.Licensing.Generator.Client The backoffice assets under App_Plugins/PackageGardenLicensing. Sites install this one. Unlisted on nuget.org; install with an exact --version
PackageGarden.LicenseGenerator.Core PackageGarden.Licensing.Generator Services, EF Core contexts and migrations, Management API controllers, composers. Contains the validator assembly (PackageGarden.Licensing.dll); no NuGet dependency on PackageGarden.Licensing. Unlisted on nuget.org

All three packages, including the validator, share one version computed from a git tag; see Releasing. The generator's project reference to the validator is PrivateAssets="all", so projects that use validator types (such as the generator tests) reference the validator project themselves.

The client project references the generator only so that one package installs everything; it uses none of its types.

Management API

The section's client talks to its own backoffice API under /umbraco/packagegarden-licensing/api/v1 (licenses, downloads, products, tree). Every endpoint requires a backoffice user whose user group has access to the Licensing section (policy PackageGardenLicensing.SectionAccess); others get 403. The OpenAPI document is served at /umbraco/openapi/packagegarden-licensing.json.

Validation failures return 400 with the legacy messages per field. With Umbraco's backoffice JSON settings the field errors are a list of { "$.field": [messages] } entries. Product keys and parameters are returned only by GET /products/{id}.

Storage

Three tables in the site's database (SQL Server), created and updated by EF Core migrations on start: PackageGardenLicensing_Product, PackageGardenLicensing_License and PackageGardenLicensing_LicenseDomainOrIp. Licenses store the member's key; the member's name and email are always read from Umbraco's member service.

Reads go through LicensingReadOnlyDbContext (no tracking; saving throws), writes through LicensingDbContext. Services reach both through ILicensingDatabase, which wraps Umbraco's EF Core scopes. Deleting a license or product only marks it as deleted. The mapping from the legacy tables is in Upgrading.

Creating licenses from site code

Every licensing rule lives in C# services. Site code can create or change a license for a member by email without the backoffice, with the same rules and messages as the editor, for example to issue a license for an order:

public class OrderLicenseIssuer(ILicenseCommandService licenses, ILicenseFileGenerator files)
{
    public async Task<LicenseFile?> IssueAsync(string email, string company, int productId, string domain)
    {
        var result = await licenses.CreateAsync(new LicenseInput
        {
            CompanyName = company,
            Email = email,
            ProductId = productId,
            LicenseType = LicenseType.Domain,
            DomainsOrIps = [domain],
        });

        // result.Validation.Errors holds the field errors when saving was refused.
        return result.Succeeded ? (await files.GenerateAsync(result.Value)).Value : null;
    }
}

ILicenseQueryService and IProductQueryService read licenses and products. All services are registered by the package's composer.

Backoffice client

The client in PackageGarden.Licensing.Generator.Client/Client follows the Umbraco backoffice extension model: section, tree, collection, workspaces, entity actions and a modal. Every API call goes through a repository and its data source over the generated client (src/license/repository, src/product/repository, the collection and tree repositories); elements and actions never call the client directly. Server field errors are added to the workspace's validation context on $.field paths, and inputs bound with umbBindToValidation show them.

Local development site

The repository has no Umbraco site. Develop against a local Umbraco 18.3 site outside the repository, on SQL Server LocalDB or Express:

  1. Create the site (dotnet new install Umbraco.Templates::18.3.0, then dotnet new umbraco in a folder outside the repository) with an unattended install.
  2. Add a project reference from the site to PackageGarden.Licensing.Generator.Client/PackageGarden.Licensing.Generator.Client.csproj in this repository, and run the site.
  3. Set the site's URL, for example $env:LICENSING_SITE_URL = 'https://localhost:44331'.

While working on the client, run npm run watch in PackageGarden.Licensing.Generator.Client/Client. The backoffice caches bundle.manifests.js per package version, so do a hard refresh after a rebuild.

Regenerating the API client

After changing a controller, regenerate the TypeScript client with the site running and commit the result in Client/src/api (never edit it by hand):

cd PackageGarden.Licensing.Generator.Client/Client
npm run generate-client

Tests

dotnet test PackageGarden.Licensing.Generator.Tests

The service tests run on SQLite in-memory with a fake member lookup; generated licenses are checked with the validator.

The overview performance test (10,000 licenses, each page within 2 seconds) needs SQL Server and runs only on request. It uses LocalDB unless LICENSING_PERF_CONNECTION is set:

dotnet test PackageGarden.Licensing.Generator.Tests --filter TestCategory=Performance

The Playwright end-to-end tests drive the local site. Set LICENSING_SITE_URL, UMBRACO_USER_LOGIN and UMBRACO_USER_PASSWORD (a backoffice administrator), and optionally LICENSING_TEST_MEMBER (default licensee@example.com, created when missing). Then run, in the client folder:

npx playwright install chromium   # once
npm run test:e2e

Every run uses new names, so it can run against a site that already has data.