Skip to content
← Todas las publicaciones
· Delta1 Labs Licensing.NETKeyright

Controlar funciones en tiempo de compilación con un generador Roslyn

Deja de esparcir comprobaciones de entitlements escritas a mano. Un generador de código Roslyn emite las guardas por ti, valida los nombres de entitlement contra un manifiesto y hace fallar la compilación ante una errata.

Las comprobaciones de entitlements tienen la costumbre de multiplicarse. Una función necesita export.pdf, otra necesita reports.scheduled, una tercera necesita un límite de seats — y cada una hace crecer su propio bloque de «resuelve la licencia, lee el entitlement, decide qué hacer ante el fallo». Copia ese bloque por una base de código y deriva: una llamada lanza una excepción, otra devuelve false, una tercera se olvida de comprobar nada, y en algún sitio un literal de cadena dice exprot.pdf y deniega en silencio una función a todos los clientes de pago. Las comprobaciones son individualmente triviales y colectivamente un riesgo.

Este es exactamente el tipo de código repetitivo, propenso a errores y mecánico que un generador de código Roslyn existe para eliminar. En lugar de escribir la guarda, declaras el control con un atributo y dejas que el generador emita una guarda correcta y uniforme en tiempo de compilación — y, como el generador ve toda tu compilación, puede validar cada nombre de entitlement contra tu catálogo declarado y hacer fallar la compilación ante una errata. Este artículo construye ese generador sobre el SDK de Keyright.

Qué vamos a construir

Decoras un método parcial con el entitlement que requiere:

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();
}

El generador completa los cuerpos. En una llamada escribes una sola línea y la ramificación desaparece:

public byte[] Export(Document doc)
{
    Features.RequirePdfExport();          // lanza LicenseException si no está habilitado
    int budget = Features.PdfPageBudget(); // el límite numérico de la licencia firmada
    ...
}

Ahora cada control se lee igual, falla cerrado igual y nombra un entitlement que el compilador ya ha confirmado que existe. El diagrama de abajo muestra las dos mitades — lo que ocurre en tiempo de compilación y lo que hace el código emitido en tiempo de ejecución.

Un generador de código emite guardas de entitlement en tiempo de compilación; la guarda impone la licencia firmada en tiempo de ejecución Tiempo de compilación Tiempo de ejecución [Gate("export.pdf")] método parcial entitlements.json catálogo declarado Generador de código Guarda emitida Features.g.cs nombre desconocido → error de compilación KR0001 punto de llamada LicenseGate.Current LicenseInfo cacheado Validate() firma + clave pública permitir lanzar se compila dentro

El atributo marcador

Los generadores de código traen sus propios atributos para que los consumidores no referencien un ensamblado aparte. Emítelo durante la post-inicialización, antes de analizar cualquier código del usuario:

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 emite una guarda void que lanza una excepción cuando el entitlement está ausente; Limit emite un método que devuelve el límite numérico que la licencia firmada lleva para una clave con nombre.

El generador incremental

Usa IIncrementalGenerator — el modelo cacheado, basado en pull, que solo se vuelve a ejecutar cuando cambian las entradas relevantes. Lo alimentan tres entradas: el atributo (registrado por adelantado), los métodos anotados y el manifiesto de entitlements suministrado como un 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));
    }
}

ForAttributeWithMetadataName es el camino rápido añadido en el Roslyn de .NET 7: lo dirige el índice de atributos en lugar de recorrer cada nodo de sintaxis, así que una solución grande no paga por el generador en cada pulsación de tecla. El predicate acota a métodos parciales; el transform eleva cada coincidencia a un pequeño GateModel record equatable — namespace, tipo contenedor, nombre del método, entitlement, kind, clave de límite y la Location del atributo para los diagnósticos. Mantener ese modelo como un tipo por valor con igualdad estructural es lo que permite que el pipeline incremental cachee correctamente.

Validar nombres contra el manifiesto

Aquí es donde el generador se gana su sitio frente a un simple snippet. Un único catálogo declarado — el mismo entitlements.json que ya posee tu configuración de emisión — lista cada entitlement que el producto conoce. Referéncialo desde el proyecto consumidor para que el generador pueda leerlo:

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

En Emit, compara el entitlement de cada control contra el manifiesto y reporta un error de compilación cuando es desconocido — pero solo cuando realmente se ha suministrado un manifiesto, para que los proyectos que lo rechazan no queden obligados a usarlo:

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));
}

Ahora [Gate("exprot.pdf")] es un subrayado rojo y una compilación fallida con el mensaje KR0001: Entitlement 'exprot.pdf' is not declared in entitlements.json, detectado en el momento de la errata y no seis semanas después, cuando un cliente no puede exportar. Ese es todo el argumento para hacer esto en un generador: el compilador se convierte en lo que mantiene tus controles honestos.

Renderizar la guarda

El cuerpo emitido es deliberadamente aburrido. Resuelve un LicenseInfo cacheado y consulta el conjunto de entitlements — las mismas dos llamadas que escribirías a mano, ahora escritas de forma idéntica cada vez:

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 es la única pieza de código de ejecución corriente, que mantiene un LicenseInfo cacheado para que cada guarda sea una lectura de campo, no una reverificación:

public static class LicenseGate
{
    private static readonly Lazy<KeyrightClient> Client = new(() =>
        KeyrightClient.Initialize(new KeyrightOptions
        {
            Product         = "Acme.Pdf",
            PublicKeyBase64 = AcmePublicKey.Base64,          // solo verificación; seguro de distribuir
            ServiceUrl      = "https://license.acme.example" // tu servicio self-hosted
        }));

    private static volatile LicenseInfo? _cached;

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

Validate() es computación puramente local contra la clave pública incrustada — nunca lanza una excepción y falla cerrado, devolviendo un LicenseInfo de edición Free ante cualquier problema — así que un entitlement ausente o desconocido se lee como deshabilitado y la guarda lanza una excepción. La activación en línea se ejecuta una vez para cachear la licencia; todo lo que hacen después los controles generados es offline.

Lo que el generador no es

La advertencia honesta importa. Un generador de código emite C#; la guarda compilada es tan visible para un decompilador como cualquier cosa que escribieras tú mismo, y nada en generarla hace que la rama IsEnabled sea más difícil de parchear para eliminarla. La seguridad no vive en el control — vive en la firma. Validate() verifica la licencia firmada contra una clave pública que un atacante no puede falsificar, y esa comprobación es la frontera. La tarea del generador es más estrecha y aun así merece la pena: hace que cada control sea coherente, imposible de olvidar en un punto de llamada decorado e imposible de malescribir sin que falle la compilación. Si además quieres que la propia comprobación de ejecución resista la manipulación, eso es tarea de la ofuscación y el anti-tamper superpuestos encima — una herramienta distinta para una amenaza distinta. Usado para lo que es, el generador convierte un patrón disperso y propenso a la deriva en una única declaración que el compilador verifica por ti.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.