.NET

The reference for KeyGrant.Licensing 0.8.0, the KeyGrant SDK for .NET, in the KeyGrant.Licensing namespace. The rules every SDK shares are in How every SDK behaves.

• .NET 8 or later: it targets net8.0.
• Runs on Windows, macOS and Linux.
• Depends on BouncyCastle.Cryptography only, which it uses for Ed25519.

Release notes

Add it

KeyGrant.Licensing is on NuGet.

dotnet add package KeyGrant.Licensing

Use it

using KeyGrant.Licensing;
var license = new License(new LicenseConfig{    Product = "my-product",    ApiBaseUrl = "https://api.keygrant.dev",    PublicJwks = PublicJwk.ParseSet("""{"keys":[...]}"""), // the keys from /pubkey    Major = 2,});
LicenseStatus status = await license.StatusAsync();if (status.State is not (LicenseState.Licensed or LicenseState.Trial or LicenseState.Unknown)){    ActivateResult result = await license.ActivateAsync(enteredKey);    if (!result.Ok) ShowError(result.Error);}

• Every call returns a Task, and every call except UpgradeUrlAsync takes an optional CancellationToken.
• Create one License per process. Calls on it run one at a time, except HasAsync, RequireAsync, UpgradeUrlAsync and the two PickUpAsync calls, which only read and run beside any call.

LicenseConfig

Calls

LicenseStatus

StatusAsync, RefreshAsync and StartTrialAsync resolve it. The activation errors are LicenseError members (LicenseError.InvalidKey).

Exceptions

Keys only their buyer can activate

When a key is locked to its buyer (Who can activate), pass what the customer typed to ActivateAsync(key, options), as an ActivateOptions with Email and Code, each optional. The steps and rules are in How every SDK behaves. Since 0.6.0.

ActivateResult result = await license.ActivateAsync(key, new ActivateOptions { Email = emailBox.Text, Code = codeBox.Text });switch (result.Error){    case LicenseError.UserEmailRequired or LicenseError.UserEmailMismatch:        AskForTheAddress();                    // then activate again with it        break;    case LicenseError.UserCodeRequired or LicenseError.UserCodeInvalid:        AskForTheCode();                       // a code was just mailed to the address        break;    case LicenseError.TooManyCodes or LicenseError.TooManyAttempts:        AskToTryLater();        break;    case LicenseError.TryAgain:        AskToRetry();                          // nothing was activated        break;}

• ActivateAsync(key) sends neither, and answers a locked key LicenseError.UserEmailRequired.
• ImportLicenseFileAsync(content, options) passes them on to a key file's key.

Restoring a license without the key

For an App Store build, which may not take a typed key: PickUpAsync(email) emails the customer a six-digit code, and RestoreByEmailAsync(email, code) activates the key that fits this build. How a pickup works is in How every SDK behaves. Since 0.8.0.

// 1. Email a code to the address the key was sold to (the answer is the same either way).await license.PickUpAsync(emailBox.Text);
// 2. The customer types the code: restore.RestoreResult restored = await license.RestoreByEmailAsync(emailBox.Text, codeBox.Text);if (!restored.Ok){    if (restored.PickupError == PickupError.WrongCode) AskAgain();    if (restored.PickupError == PickupError.CodeExpired) await license.PickUpAsync(emailBox.Text);  // a new code    if (restored.NoKey) ShowNoKeyUnderThatAddress();}

• To let the customer choose, call PickUpAsync(email, code), show each of PickUpKeysResult.Keys by its ModelName, and activate the one chosen with ActivateAsync(picked.Key, new ActivateOptions { Email = email, Code = picked.ActivationCode }).
• A RestoreResult holds a refusal in PickupError, NoKey or Error.
• The errors are the pickup errors, in this SDK's own names. The requests are on the endpoints page.

License files

A customer can be sent a .kglicense file: a key file, which activates its key, or an offline license file, which licenses the app with no network. How each behaves is in How every SDK behaves, and what each costs under Delivered as in License models. Since 0.5.0.

• LicenseFileFormat.Extension is .kglicense, for an open dialog's filter or a drop handler's test.
• LicenseFileFormat.MaxBytes is 16,384, the most a file may be, and LicenseFileFormat.MediaType is application/vnd.keygrant.license.
• List the ids of leaked files in RevokedLicenseFiles (Blocking a leaked file).

var license = new License(new LicenseConfig{    Product = "sluice",    ApiBaseUrl = "https://api.keygrant.dev",    PublicJwks = PublicJwk.ParseSet(KeygrantKeys),    Major = 3,    RevokedLicenseFiles = [], // ids of files that leaked: an update adds them here});

ImportLicenseFileAsync takes the file's content, never its path. In WPF (AllowDrop="True" on the window), a dropped file and an "Open license file..." command look like this:

private async void Window_Drop(object sender, DragEventArgs e){    if (e.Data.GetData(DataFormats.FileDrop) is not string[] paths) return;    var path = paths.FirstOrDefault(p => p.EndsWith(LicenseFileFormat.Extension, StringComparison.OrdinalIgnoreCase));    if (path is not null) await ImportAsync(path);}
private async void OpenLicenseFile_Click(object sender, RoutedEventArgs e){    var dialog = new Microsoft.Win32.OpenFileDialog { Filter = $"License file (*{LicenseFileFormat.Extension})|*{LicenseFileFormat.Extension}" };    if (dialog.ShowDialog(this) == true) await ImportAsync(dialog.FileName);}
private async Task ImportAsync(string path){    try    {        // Never more than a license file can be: a larger one is refused unread.        if (new FileInfo(path).Length > LicenseFileFormat.MaxBytes) { ShowError(LicenseFileError.Malformed); return; }        var result = await license.ImportLicenseFileAsync(await File.ReadAllBytesAsync(path));        if (result.Ok) ShowThanks(result.LicensedTo!.Name ?? result.LicensedTo.Email);        else if (result.Error is { } refused) ShowError(refused);                 // the file was not taken        else ShowActivationError(result.ActivateError!.Value);                    // a key file's key did not activate    }    catch (Exception)    {        // An async void handler must catch everything, or the app ends: the file unreadable, the        // state not saved, or a license call still running. Try again.        ShowRetry();    }}

In WinForms, set AllowDrop = true, set e.Effect = DragDropEffects.Copy in DragEnter, and read e.Data.GetData(DataFormats.FileDrop) in DragDrop.

What ImportLicenseFileAsync answers

It verifies the file offline (Importing a file). The ImportLicenseFileResult has one of:

• Ok, with its Kind (LicenseFileKind.Key or LicenseFileKind.Offline) and LicensedTo (a record with Name and Email);
• Error, a LicenseFileError below, with nothing stored;
• ActivateError, for a key file whose key did not activate: what ActivateAsync answers.

• It throws InvalidOperationException when an earlier call has not finished, and, as ActivateAsync does, when the state cannot be read or the file cannot be saved.
• RemoveLicenseFileAsync throws InvalidOperationException in the same case, and, as DeactivateAsync does, when the change cannot be saved.

The status of a stored file

A stored offline file answers every StatusAsync() with Licensed, Source = LicenseSource.File, the Key, LicensedTo and the file's Entitlements, and never asks KeyGrant, RefreshAsync() included.

• Show "Licensed to Ada Lovelace" from LicensedTo.
• A status from a file has no seat to deactivate: offer RemoveLicenseFileAsync() instead. DeactivateAsync() leaves the file alone.
• Besides RevokedFile, a status from a file can be Invalid with reason Upgrade, Outdated, Tampered or UnknownKey. What each means, and which wins when the device also holds a key, is in The status of a stored file.

Metered uses

A license model can count uses of what it sells (Metered uses). The app spends them with UseAsync(meter, n), before the work they count, and does the work only when the spend is Ok. Since 0.7.0.

UseResult spent = await license.UseAsync("exports"); // UseAsync("exports", 40) spends forty at once, whole or noneif (spent.Ok){    RunExport(); // spent.Left: what is left now, net of this device's unsynced spends}else{    switch (spent.Error)    {        case UseError.UsedUp:            OfferMoreExports(spent.Left);   // the server's word: fewer left than asked (null when it gave none)            break;        case UseError.OfflineLimit:            AskToConnect();                 // KeyGrant could not be reached, and this is past what this device may spend without it            break;        default:            ShowMeterProblem(spent.Error);  // NoMeter, NotLicensed, Revoked, Device, Upgrade, Outdated, Storage, InvalidAmount            break;    }}
LicenseStatus status = await license.StatusAsync(); // offline, from the leasestatus.Meters["exports"]; // MeterStatus { Left = 950, Total = 1000, Offline = 100, Unsynced = 0, Resets = false }

• UseResult.Offline is true when the device spent from its offline allowance.
• n is a long. Outside 1 to 1,000,000,000 it is InvalidAmount, and a meter code that is not 1 to 32 UTF-16 units is NoMeter, both without asking.
• A request waits at most 5 seconds for KeyGrant, less when HttpTimeout is shorter.
• DeactivateAsync() sends the unsynced spends with the release.
• How a spend works online and offline, and why a meter never takes the license away, is in How every SDK behaves.

It does not throw for an outcome: every one is in the UseResult. The one exception is a CancellationToken:

• Canceled while the call waits its turn, or before its request is sent: it throws OperationCanceledException, and nothing is spent.
• Canceled while the request is out: the call stops waiting, spends as for no answer, and returns its result, so read it even after canceling.

When UseAsync does not spend

LicenseStatus.Meters

A dictionary by meter code, on a Licensed status from a key's lease that names meters, and empty on every other status. Each MeterStatus has:

Buying from the trial

// The Buy button, while the app holds no key.OpenInBrowser("https://buy.stripe.com/your-payment-link");
// The customer types the key from the delivery email:ActivateResult result = await license.ActivateAsync(enteredKey);if (result.Ok) ShowThanks();

The checkout creates the key and delivers it, and the customer types it into the app. See Buying from the trial.

When StatusAsync resolves a trial, the trial reports its launch to KeyGrant at most once a day, on a thread-pool thread, so the call never waits for it. The app need not call StartTrialAsync on each launch for Analytics to count the trial as come back (Device trials).

Keeping a trial through a reinstall

The default registry stash stores nothing. On Windows, WindowsRegistryStash stores the trial's start date under HKCU\Software\KeyGrant\<product>. It is Windows-only, so guard it with OperatingSystem.IsWindows():

var license = new License(new LicenseConfig{    Product = "my-product",    ApiBaseUrl = "https://api.keygrant.dev",    PublicJwks = publicJwks,    Adapters = OperatingSystem.IsWindows()        ? new LicenseAdapters { Registry = new WindowsRegistryStash("my-product") }        : null,});