Skip to content
← Alle Beiträge
· Delta1 Labs Licensing.NETKeyright

Features zur Compile-Zeit absichern mit einem Roslyn-Generator

Schluss mit handgeschriebenen Entitlement-Prüfungen überall im Code. Ein Roslyn-Source-Generator emittiert die Guards für Sie, validiert Entitlement-Namen gegen ein Manifest und lässt den Build bei einem Tippfehler scheitern.

Entitlement-Prüfungen neigen dazu, sich zu vermehren. Ein Feature braucht export.pdf, ein anderes braucht reports.scheduled, ein drittes braucht ein seats-Limit — und jedes lässt seinen eigenen kleinen Block aus „Lizenz auflösen, Entitlement lesen, bei Fehlschlag entscheiden, was zu tun ist” wachsen. Kopieren Sie diesen Block durch eine Codebasis, driftet er: Eine Aufrufstelle wirft eine Ausnahme, eine andere gibt false zurück, eine dritte vergisst die Prüfung ganz, und irgendwo sagt ein String-Literal exprot.pdf und verweigert stillschweigend ein Feature allen zahlenden Kunden. Die Prüfungen sind einzeln trivial und zusammengenommen ein Risiko.

Genau das ist die Art von repetitivem, fehleranfälligem, mechanischem Code, den ein Roslyn-Source-Generator zu beseitigen existiert. Statt den Guard zu schreiben, deklarieren Sie die Absicherung mit einem Attribut und lassen den Generator zur Compile-Zeit einen korrekten, einheitlichen Guard emittieren — und da der Generator Ihre gesamte Kompilierung sieht, kann er jeden Entitlement-Namen gegen Ihren deklarierten Katalog validieren und den Build bei einem Tippfehler scheitern lassen. Dieser Artikel baut diesen Generator auf dem Keyright-SDK.

Was wir bauen

Sie dekorieren eine partielle Methode mit dem Entitlement, das sie benötigt:

public static partial class Features
{
    [Gate("export.pdf")]
    public static partial void RequirePdfExport();

    [Gate("export.pdf", Kind = GateKind.Limit, Limit = "pages-per-day")]
    public static partial int PdfPageBudget();
}

Der Generator füllt die Rümpfe aus. An einer Aufrufstelle schreiben Sie eine einzige Zeile, und die Verzweigung ist verschwunden:

public byte[] Export(Document doc)
{
    Features.RequirePdfExport();          // wirft LicenseException, wenn nicht berechtigt
    int budget = Features.PdfPageBudget(); // das numerische Limit aus der signierten Lizenz
    ...
}

Nun liest sich jede Absicherung gleich, schlägt gleich fail-closed fehl und benennt ein Entitlement, dessen Existenz der Compiler bereits bestätigt hat. Das folgende Diagramm zeigt die beiden Hälften — was zur Compile-Zeit geschieht und was der emittierte Code zur Laufzeit tut.

Ein Source-Generator emittiert Entitlement-Guards zur Compile-Zeit; der Guard erzwingt die signierte Lizenz zur Laufzeit Compile-Zeit Laufzeit [Gate("export.pdf")] partielle Methode entitlements.json deklarierter Katalog Source- Generator Emittierter Guard Features.g.cs unbekannter Name → Build-Fehler KR0001 Aufrufstelle LicenseGate.Current gecachtes LicenseInfo Validate() Signatur + öffentl. Schlüssel erlauben werfen kompiliert in

Das Marker-Attribut

Source-Generatoren liefern ihre eigenen Attribute aus, damit Konsumenten keine separate Assembly referenzieren. Emittieren Sie es während der Post-Initialisierung, bevor irgendein Nutzercode analysiert wird:

private const string AttributeSource = """
    namespace Acme.Licensing;
    [System.AttributeUsage(System.AttributeTargets.Method)]
    internal sealed class GateAttribute : System.Attribute
    {
        public GateAttribute(string entitlement) => Entitlement = entitlement;
        public string Entitlement { get; }
        public GateKind Kind { get; set; } = GateKind.Require;
        public string? Limit { get; set; }
    }
    internal enum GateKind { Require, Limit }
    """;

Require emittiert einen void-Guard, der eine Ausnahme wirft, wenn das Entitlement fehlt; Limit emittiert eine Methode, die das numerische Limit zurückgibt, das die signierte Lizenz für einen benannten Schlüssel trägt.

Der inkrementelle Generator

Verwenden Sie IIncrementalGenerator — das gecachte, pull-basierte Modell, das nur neu läuft, wenn sich relevante Eingaben ändern. Drei Eingaben speisen ihn: das Attribut (vorab registriert), die annotierten Methoden und das als AdditionalFile bereitgestellte Entitlement-Manifest.

[Generator]
public sealed class EntitlementGateGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(ctx =>
            ctx.AddSource("GateAttribute.g.cs", AttributeSource));

        IncrementalValuesProvider<GateModel> gates = context.SyntaxProvider
            .ForAttributeWithMetadataName(
                "Acme.Licensing.GateAttribute",
                predicate: static (node, _) => node is MethodDeclarationSyntax m
                    && m.Modifiers.Any(SyntaxKind.PartialKeyword),
                transform: static (ctx, _) => GateModel.From(ctx))
            .Where(static m => m is not null)!;

        IncrementalValueProvider<ImmutableHashSet<string>> manifest = context
            .AdditionalTextsProvider
            .Where(static f => Path.GetFileName(f.Path) == "entitlements.json")
            .Select(static (f, ct) => f.GetText(ct)?.ToString())
            .Collect()
            .Select(static (texts, _) => ManifestParser.Names(texts));

        context.RegisterSourceOutput(gates.Combine(manifest),
            static (spc, pair) => Emit(spc, pair.Left, pair.Right));
    }
}

ForAttributeWithMetadataName ist der schnelle Pfad, der im Roslyn von .NET 7 hinzugefügt wurde: Er wird vom Attribut-Index gesteuert statt vom Durchlaufen jedes Syntaxknotens, sodass eine große Solution den Generator nicht bei jedem Tastendruck bezahlt. Das predicate grenzt auf partielle Methoden ein; das transform hebt jeden Treffer in einen kleinen, gleichheitsfähigen GateModel-Record — Namespace, umschließender Typ, Methodenname, Entitlement, Kind, Limit-Schlüssel und die Location des Attributs für Diagnosen. Dieses Modell als Werttyp mit struktureller Gleichheit zu halten, ist das, was der inkrementellen Pipeline korrektes Caching ermöglicht.

Namen gegen das Manifest validieren

Hier verdient sich der Generator seinen Platz gegenüber einem bloßen Snippet. Ein einziger deklarierter Katalog — dieselbe entitlements.json, die Ihre Ausstellungskonfiguration bereits besitzt — listet jedes Entitlement auf, das das Produkt kennt. Referenzieren Sie ihn aus dem konsumierenden Projekt, damit der Generator ihn lesen kann:

<ItemGroup>
  <AdditionalFiles Include="entitlements.json" />
</ItemGroup>

Vergleichen Sie in Emit das Entitlement jeder Absicherung gegen das Manifest und melden Sie einen Build-Fehler, wenn es unbekannt ist — aber nur, wenn tatsächlich ein Manifest bereitgestellt wurde, damit Projekte, die es ablehnen, nicht dazu gezwungen werden:

private static readonly DiagnosticDescriptor UnknownEntitlement = new(
    id: "KR0001",
    title: "Unknown entitlement",
    messageFormat: "Entitlement '{0}' is not declared in entitlements.json",
    category: "Keyright",
    DiagnosticSeverity.Error,
    isEnabledByDefault: true);

private static void Emit(SourceProductionContext spc, GateModel g,
                         ImmutableHashSet<string> manifest)
{
    if (!manifest.IsEmpty && !manifest.Contains(g.Entitlement))
    {
        spc.ReportDiagnostic(Diagnostic.Create(
            UnknownEntitlement, g.Location, g.Entitlement));
        return;
    }
    spc.AddSource($"{g.TypeName}_{g.MethodName}.g.cs", Render(g));
}

Jetzt ist [Gate("exprot.pdf")] eine rote Unterschlängelung und ein fehlgeschlagener Build mit der Meldung KR0001: Entitlement 'exprot.pdf' is not declared in entitlements.json, abgefangen im Moment des Tippfehlers und nicht sechs Wochen später, wenn ein Kunde nicht exportieren kann. Das ist das ganze Argument dafür, dies in einem Generator zu tun: Der Compiler wird zu dem, was Ihre Absicherungen ehrlich hält.

Den Guard rendern

Der emittierte Rumpf ist bewusst langweilig. Er löst ein gecachtes LicenseInfo auf und befragt den Entitlement-Satz — dieselben zwei Aufrufe, die Sie von Hand schreiben würden, nun jedes Mal identisch geschrieben:

private static string Render(GateModel g) => g.Kind switch
{
    GateKind.Require => $$"""
        // <auto-generated/>
        namespace {{g.Namespace}};
        partial class {{g.TypeName}}
        {
            static partial void {{g.MethodName}}()
            {
                var info = LicenseGate.Current;
                if (!info.Entitlements.IsEnabled("{{g.Entitlement}}"))
                    throw new LicenseException("{{g.Entitlement}}", info.Status);
            }
        }
        """,
    GateKind.Limit => $$"""
        // <auto-generated/>
        namespace {{g.Namespace}};
        partial class {{g.TypeName}}
        {
            static partial int {{g.MethodName}}()
                => (int)LicenseGate.Current.Entitlements.GetLimit("{{g.Limit}}");
        }
        """,
    _ => ""
};

LicenseGate ist das einzige Stück gewöhnlicher Laufzeitcode, das ein gecachtes LicenseInfo hält, sodass jeder Guard ein Feldzugriff ist und keine erneute Verifikation:

public static class LicenseGate
{
    private static readonly Lazy<KeyrightClient> Client = new(() =>
        KeyrightClient.Initialize(new KeyrightOptions
        {
            Product         = "Acme.Pdf",
            PublicKeyBase64 = AcmePublicKey.Base64,          // nur Verifikation; sicher auszuliefern
            ServiceUrl      = "https://license.acme.example" // Ihr self-hosted-Dienst
        }));

    private static volatile LicenseInfo? _cached;

    public static LicenseInfo Current => _cached ??= Client.Value.Validate();
    public static void Refresh() => _cached = Client.Value.Validate();
}

Validate() ist rein lokale Berechnung gegen den eingebetteten öffentlichen Schlüssel — es wirft nie eine Ausnahme und schlägt fail-closed fehl und gibt bei jedem Problem ein LicenseInfo der Free-Edition zurück — also liest sich ein fehlendes oder unbekanntes Entitlement als deaktiviert, und der Guard wirft eine Ausnahme. Die Online-Aktivierung läuft einmal, um die Lizenz zu cachen; alles, was die generierten Absicherungen danach tun, ist offline.

Was der Generator nicht ist

Der ehrliche Vorbehalt zählt. Ein Source-Generator emittiert C#; der kompilierte Guard ist für einen Decompiler genauso sichtbar wie alles, was Sie selbst schreiben würden, und nichts am Generieren macht den IsEnabled-Zweig schwerer herauszupatchen. Die Sicherheit lebt nicht in der Absicherung — sie lebt in der Signatur. Validate() verifiziert die signierte Lizenz gegen einen öffentlichen Schlüssel, gegen den ein Angreifer nicht fälschen kann, und diese Prüfung ist die Grenze. Die Aufgabe des Generators ist enger und dennoch lohnend: Er macht jede Absicherung konsistent, an einer dekorierten Aufrufstelle unmöglich zu vergessen und unmöglich falsch zu schreiben, ohne den Build scheitern zu lassen. Wenn Sie zusätzlich wollen, dass die Laufzeitprüfung selbst Manipulation widersteht, ist das Aufgabe von Obfuskation und Anti-Tamper, darübergelegt — ein anderes Werkzeug für eine andere Bedrohung. Für das eingesetzt, was er ist, verwandelt der Generator ein verstreutes, driftanfälliges Muster in eine einzige Deklaration, die der Compiler für Sie verifiziert.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.