DEV Community

Zero Heartbeat
Zero Heartbeat

Posted on Edited on Originally published at delta1labs.com

Gating features at compile time with a Roslyn generator

Entitlement checks have a way of multiplying. One feature needs export.pdf, another needs reports.scheduled, a third needs a seats limit — and each one grows its own little block of "resolve the license, read the entitlement, decide what to do on failure." Copy that block around a codebase and it drifts: one call site throws, another returns false, a third forgets to check at all, and somewhere a string literal says exprot.pdf and silently denies a feature to every paying customer. The checks are individually trivial and collectively a liability.

This is exactly the kind of repetitive, error-prone, mechanical code a Roslyn source generator exists to remove. Instead of writing the guard, you declare the gate with an attribute and let the generator emit a correct, uniform guard at compile time — and, because the generator sees your whole compilation, it can validate every entitlement name against your declared catalog and fail the build on a typo. This post builds that generator against the Keyright SDK.

What we are building

You decorate a partial method with the entitlement it requires:

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();
}
Enter fullscreen mode Exit fullscreen mode

The generator fills in the bodies. At a call site you write one line and the branching is gone:

public byte[] Export(Document doc)
{
    Features.RequirePdfExport();          // throws LicenseException if not entitled
    int budget = Features.PdfPageBudget(); // the numeric limit from the signed license
    ...
}
Enter fullscreen mode Exit fullscreen mode

Every gate now reads the same way, fails closed the same way, and names an entitlement the compiler has already confirmed exists. The diagram below shows the two halves — what happens at build time, and what the emitted code does at runtime.


A source generator emits entitlement guards at compile time; the guard enforces the signed license at runtime
Compile time
Runtime


[Gate("export.pdf")]
partial method

entitlements.json
declared catalog

Source
generator

Emitted guard
Features.g.cs



unknown name → build error KR0001

guard call site

LicenseGate.Current
cached LicenseInfo

Validate()
signature + public key

allow

throw

compiles in





The marker attribute

Source generators ship their own attributes so consumers do not reference a separate assembly. Emit it during post-initialization, before any user code is analyzed:

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 }
    """;
Enter fullscreen mode Exit fullscreen mode

Require emits a void guard that throws when the entitlement is absent; Limit emits a method returning the numeric limit the signed license carries for a named key.

The incremental generator

Use IIncrementalGenerator — the cached, pull-based model that only re-runs when relevant inputs change. Three inputs feed it: the attribute (registered up front), the annotated methods, and the entitlement manifest supplied as an AdditionalFile.

[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));
    }
}
Enter fullscreen mode Exit fullscreen mode

ForAttributeWithMetadataName is the fast path added in .NET 7's Roslyn: it is driven by the attribute index rather than by walking every syntax node, so a large solution does not pay for the generator on every keystroke. The predicate narrows to partial methods; the transform lifts each match into a small, equatable GateModel record — namespace, containing type, method name, entitlement, kind, limit key, and the attribute's Location for diagnostics. Keeping that model a value type with structural equality is what lets the incremental pipeline cache correctly.

Validating names against the manifest

This is where the generator earns its place over a snippet. A single declared catalog — the same entitlements.json your issuing configuration already owns — lists every entitlement the product knows about. Reference it from the consuming project so the generator can read it:

<ItemGroup>
  <AdditionalFiles Include="entitlements.json" />
</ItemGroup>
Enter fullscreen mode Exit fullscreen mode

In Emit, compare each gate's entitlement against the manifest and report a build error when it is unknown — but only when a manifest was actually supplied, so projects that opt out are not forced into it:

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));
}
Enter fullscreen mode Exit fullscreen mode

Now [Gate("exprot.pdf")] is a red squiggle and a failed build with message KR0001: Entitlement 'exprot.pdf' is not declared in entitlements.json, caught at the moment of the typo rather than six weeks later when a customer cannot export. That is the whole argument for doing this in a generator: the compiler becomes the thing that keeps your gates honest.

Rendering the guard

The emitted body is deliberately boring. It resolves a cached LicenseInfo and asks the entitlement set — the same two calls you would write by hand, now written identically every time:

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}}");
        }
        """,
    _ => ""
};
Enter fullscreen mode Exit fullscreen mode

LicenseGate is the one piece of ordinary runtime code, holding a cached LicenseInfo so each guard is a field read, not a re-verification:

public static class LicenseGate
{
    private static readonly Lazy<KeyrightClient> Client = new(() =>
        KeyrightClient.Initialize(new KeyrightOptions
        {
            Product         = "Acme.Pdf",
            PublicKeyBase64 = AcmePublicKey.Base64,          // verify-only; safe to ship
            ServiceUrl      = "https://license.acme.example" // your self-hosted service
        }));

    private static volatile LicenseInfo? _cached;

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

Validate() is pure local computation against the embedded public key — it never throws and fails closed, returning a Free edition LicenseInfo on any problem — so an absent or unknown entitlement reads as disabled and the guard throws. Online activation runs once to cache the lease; everything the generated gates do after that is offline.

What the generator is not

The honest caveat matters. A source generator emits C#; the compiled guard is as visible to a decompiler as anything you would write yourself, and nothing about generating it makes the IsEnabled branch harder to patch out. The security does not live in the gate — it lives in the signature. Validate() verifies the signed license against a public key an attacker cannot forge against, and that check is the boundary. The generator's job is narrower and still worth doing: it makes every gate consistent, impossible to forget at a decorated call site, and impossible to misname past a build. If you also want the runtime check itself resistant to tampering, that is a job for obfuscation and anti-tamper layered on top — a different tool for a different threat. Used for what it is, the generator turns a scattered, drift-prone pattern into one declaration the compiler verifies for you.

Top comments (0)