Benötigte und gewährte Berechtigungen beim Upgrade vergleichen
Wenn eine neue Version Berechtigungen braucht, die die Lizenz des Kunden nie gewährt hat, ist ein bloßes „Funktion gesperrt" eine Sackgasse. So vergleichen Sie Benötigtes und Gewährtes und sagen genau, was zu kaufen ist.
Ein Kunde Ihrer 3.x-Linie wechselt auf 4.0. Die neue Version ergänzt SSO, einen Exporter für das Audit-Log und eine höhere Projektgrenze — drei Dinge, die seine aktuelle Lizenz, gegen die 3.x-Tier-Vorlage ausgestellt, nie abdecken sollte. Er startet, klickt auf Audit-Log exportieren und erhält eine knappe FeatureLockedException. Er klickt auf SSO-Einstellungen und bekommt die nächste. Jeder fehlgeschlagene Klick ist ein eigenes Support-Ticket, und keines beantwortet die einzige Frage, die der Kunde wirklich hat: Was muss ich kaufen, damit diese Version vollständig ist?
Das Problem ist nicht die Sperre. Jede Funktion fehlersicher zu gaten ist richtig, und das sollten Sie beibehalten. Das Problem ist, dass IsEnabled-Prüfungen pro Funktion eine Frage der falschen Größe beantworten. Sie sagen Ihnen im Moment der Nutzung, ob eine Fähigkeit aktiv ist. Sie sagen Ihnen nie im Voraus die Form der Lücke zwischen dem, was diese Version der Anwendung braucht, und dem, was diese Lizenz gewährt. Diese Form ist eine Mengendifferenz, und sie einmal beim Start zu berechnen, verwandelt ein Rinnsal rätselhafter Sperren in einen ehrlichen Satz.
Eine Berechtigung ist eine benannte Fähigkeit; eine Version braucht eine Menge davon
Wenn Sie Berechtigungen versus Feature-Flags gelesen haben, wissen Sie, dass eine Keyright-Berechtigung eine benannte Fähigkeit ist, in die signierte Lizenz eingebrannt: ein Boolean wie audit-export oder ein numerisches Limit wie max-projects: 50. Die Lizenz trägt die Menge, die der Kunde erhalten hat. Was sie nicht trägt und nicht tragen soll, ist die Menge, die Ihr aktueller Build benötigt — denn diese Menge ändert sich bei jedem Release.
Deklarieren Sie sie also in der Anwendung. Ein Fähigkeitsmanifest ist eine kleine, statische Beschreibung jeder Berechtigung, von der eine bestimmte Version abhängt, versioniert neben dem Code, der davon abhängt. Es reist in der Assembly mit; es ist weder ein Geheimnis noch ein Lizenzartefakt.
public sealed record Requirement(string Key, RequirementKind Kind, long Min = 0);
public enum RequirementKind { Flag, Limit }
public static class AppManifest
{
// Everything THIS build needs the license to grant. Grows as the product grows.
public static readonly IReadOnlyList<Requirement> Required = new[]
{
new Requirement("audit-export", RequirementKind.Flag),
new Requirement("sso", RequirementKind.Flag),
new Requirement("max-projects", RequirementKind.Limit, Min: 25),
};
}
Wenn Sie in 4.0 eine Funktion ergänzen, die sich auf sso stützt, fügen Sie hier im selben Commit eine Zeile hinzu. Das Manifest ist der einzige Ort, der weiß „diese Version braucht diese Fähigkeiten”, und es liegt neben dem Code, kann also nie wie eine externe Konfiguration von einem Release wegdriften.
Die gewährte Menge kommt aus der validierten Lizenz
Die andere Hälfte des Vergleichs ist, was die Lizenz tatsächlich gewährt, und das ist reine lokale Berechnung. Das SDK hat die signierte Lizenz beim Start offline gegen Ihren eingebetteten öffentlichen Schlüssel validiert; ihre Berechtigungen zu lesen bedeutet nur, das Ergebnis zu inspizieren.
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = AcmeKeys.LicensePublicKey, // public key only; safe to ship
ServiceUrl = "https://licensing.acme.example",
});
LicenseInfo info = client.Validate(); // never throws; fails closed to Free on any problem
Validate() greift auf dem heißen Pfad nie aufs Netzwerk zu, wirft nie eine Ausnahme und gibt bei jedem Fehler ein LicenseInfo in der Free-Edition zurück, dessen Berechtigungsmenge leer ist. Diese letzte Eigenschaft zählt für den Vergleich: Eine ungültige oder fehlende Lizenz bricht den Vergleich nicht, sie gewährt schlicht nichts, sodass alle Anforderungen als fehlend erscheinen — genau der Bericht, den Sie in diesem Fall wollen.
Der Vergleich ist Mengenarithmetik
Gehen Sie nun die benötigte Menge gegen die gewährte Lizenz durch und sammeln Sie, was nicht erfüllt ist. Ein Boolean ist erfüllt, wenn die Lizenz ihn aktiviert; ein Limit ist erfüllt, wenn die Obergrenze der Lizenz das von dieser Version benötigte Minimum erreicht oder übersteigt.
public sealed record Gap(Requirement Need, long? Granted);
public static IReadOnlyList<Gap> Diff(LicenseInfo info, IEnumerable<Requirement> required)
{
var gaps = new List<Gap>();
foreach (var r in required)
{
switch (r.Kind)
{
case RequirementKind.Flag:
if (!info.Entitlements.IsEnabled(r.Key))
gaps.Add(new Gap(r, Granted: null));
break;
case RequirementKind.Limit:
long granted = info.Entitlements.GetLimit(r.Key); // 0 when absent
if (granted < r.Min)
gaps.Add(new Gap(r, Granted: granted));
break;
}
}
return gaps;
}
Da IsEnabled und GetLimit beide fehlersicher fehlschlagen — ein unbekannter Boolean liest sich als aus, ein fehlendes Limit als 0 — ist der Vergleich auch gegen eine Free- oder fehlerhafte Lizenz korrekt, ohne einen einzigen Sonderfall. Die Lückenliste ist die Antwort: leer bedeutet, diese Version ist vollständig abgedeckt; nicht leer ist eine präzise, kaufbare Einkaufsliste.
Melden Sie es einmal, beim Start
Führen Sie den Vergleich beim Hochfahren der Anwendung aus und zeigen Sie die gesamte Lücke an einer Stelle — ein Banner, ein blockierender Dialog, eine Log-Zeile für einen Host ohne Oberfläche — statt den Nutzer über jede Sperre einzeln stolpern zu lassen. Die Meldung benennt, was fehlt, und verweist auf das Upgrade, die Aktion, die alles auf einmal löst.
var gaps = EntitlementDiff.Diff(info, AppManifest.Required);
if (gaps.Count > 0)
{
var lines = gaps.Select(g => g.Granted is null
? $" • {g.Need.Key} (not included in your license)"
: $" • {g.Need.Key}: need {g.Need.Min}, your license allows {g.Granted}");
_log.LogWarning(
"This version of acme-suite needs entitlements your current license ({Tier}) does " +
"not cover:\n{Gaps}\nUpgrade your license to enable them: {Url}",
info.Tier, string.Join('\n', lines), "https://acme.example/account/license");
_startup.ShowUpgradeNotice(gaps); // one notice, the full shopping list, a real next step
}
Beachten Sie, was dies nicht tut: Es deaktiviert die Anwendung nicht. Eine Lücke bedeutet, dass einige 4.0-Funktionen nicht verfügbar sind, nicht dass das Produkt unlizenziert ist. Alles, was die Lizenz tatsächlich gewährt, läuft weiter; die Sperren auf Funktionsebene bleiben genau dort, wo sie waren, und schließen am Nutzungspunkt weiterhin fehlersicher. Der Vergleich ist eine Upgrade-Aufforderung, kein Notausschalter: Beide leben auf unterschiedlichen Ebenen und ersetzen einander nie.
Machen Sie den Vergleich auch zu einer Vorabprüfung
Dasselbe Manifest zahlt sich aus, bevor auch nur ein Byte der neuen Version einen Kunden erreicht. Ein Partner, der an eine Flotte ausliefert, oder Ihre eigene CI, kann eine Probe-Lizenz auf dem aktuellen Tier ausstellen und sicherstellen, dass der Vergleich leer ist — und so „4.0 braucht stillschweigend eine Berechtigung, die die Pro-Tier-Vorlage nie gewährt” zur Build-Zeit abfangen statt in einer Support-Warteschlange.
[Fact]
public void ProTier_covers_everything_v4_requires()
{
LicenseInfo pro = TestIssuer.Mint(product: "acme-suite", tier: "Pro");
var gaps = EntitlementDiff.Diff(pro, AppManifest.Required);
Assert.True(gaps.Count == 0,
"Pro tier is missing: " + string.Join(", ", gaps.Select(g => g.Need.Key)));
}
Wenn dieser Test rot wird, sobald Sie eine Funktion ergänzen, haben Sie vor dem Release eine Entscheidung zu treffen: die Tier-Vorlage erweitern, sodass Pro die neue Berechtigung gewährt, oder akzeptieren, dass die Funktion ein Upsell auf ein höheres Tier ist. In jedem Fall haben Sie die Entscheidung bewusst getroffen, mit der Lücke vor Augen, statt sie vom ersten Kunden zu erfahren, der aktualisiert und einen gesperrten Button vorgefunden hat.
Die Form der Lücke ist das Ergebnis des Vergleichs
Gaten pro Funktion sagt dem Nutzer, dass eine Tür verschlossen ist. Das Manifest gegen die Lizenz zu vergleichen sagt ihm, welche Türen, warum und welcher eine Kauf sie alle öffnet — der Unterschied zwischen einem frustrierenden Rinnsal von Sperren und einer einzigen, ehrlichen, handlungsfähigen Aufforderung. Behalten Sie die fehlersicheren Sperren: Sie sind Ihre Durchsetzung. Legen Sie den Start-Vergleich obendrauf: Er ist Ihre Erklärung. Das eine ist, wie die Software das Geschäft schützt; das andere ist, wie das Geschäft den Kunden davon abhält, ein Upgrade wütend abzubrechen, für das er gern bezahlt hätte.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.