Contrôler les fonctionnalités à la compilation avec un générateur Roslyn
Arrêtez de disséminer des vérifications d'entitlements écrites à la main. Un générateur de source Roslyn émet les gardes pour vous, valide les noms d'entitlement contre un manifeste et fait échouer la compilation sur une faute de frappe.
Les vérifications d’entitlements ont tendance à se multiplier. Une fonctionnalité nécessite export.pdf, une autre nécessite reports.scheduled, une troisième nécessite une limite de seats — et chacune fait grossir son propre petit bloc de « résoudre la licence, lire l’entitlement, décider quoi faire en cas d’échec ». Copiez ce bloc à travers une base de code et il dérive : un point d’appel lève une exception, un autre retourne false, un troisième oublie de vérifier quoi que ce soit, et quelque part un littéral de chaîne dit exprot.pdf et refuse silencieusement une fonctionnalité à tous les clients payants. Les vérifications sont individuellement triviales et collectivement un risque.
C’est exactement le genre de code répétitif, propice aux erreurs et mécanique qu’un générateur de source Roslyn existe pour supprimer. Au lieu d’écrire la garde, vous déclarez le contrôle avec un attribut et laissez le générateur émettre une garde correcte et uniforme à la compilation — et, comme le générateur voit toute votre compilation, il peut valider chaque nom d’entitlement contre votre catalogue déclaré et faire échouer la compilation sur une faute de frappe. Cet article construit ce générateur sur le SDK Keyright.
Ce que nous construisons
Vous décorez une méthode partielle avec l’entitlement qu’elle requiert :
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();
}
Le générateur remplit les corps. Sur un point d’appel vous écrivez une seule ligne et la ramification disparaît :
public byte[] Export(Document doc)
{
Features.RequirePdfExport(); // lève LicenseException si non autorisé
int budget = Features.PdfPageBudget(); // la limite numérique de la licence signée
...
}
Désormais chaque contrôle se lit de la même façon, échoue fermé de la même façon, et nomme un entitlement dont le compilateur a déjà confirmé l’existence. Le schéma ci-dessous montre les deux moitiés — ce qui se passe à la compilation, et ce que fait le code émis à l’exécution.
L’attribut marqueur
Les générateurs de source embarquent leurs propres attributs pour que les consommateurs ne référencent pas un assembly séparé. Émettez-le pendant la post-initialisation, avant toute analyse du code de l’utilisateur :
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 émet une garde void qui lève une exception quand l’entitlement est absent ; Limit émet une méthode qui retourne la limite numérique que la licence signée porte pour une clé nommée.
Le générateur incrémental
Utilisez IIncrementalGenerator — le modèle mis en cache, basé sur le pull, qui ne se ré-exécute que lorsque les entrées pertinentes changent. Trois entrées l’alimentent : l’attribut (enregistré d’avance), les méthodes annotées et le manifeste d’entitlements fourni sous forme d’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 est le chemin rapide ajouté dans le Roslyn de .NET 7 : il est piloté par l’index des attributs plutôt que par le parcours de chaque nœud de syntaxe, donc une grande solution ne paie pas pour le générateur à chaque frappe. Le predicate restreint aux méthodes partielles ; le transform élève chaque correspondance en un petit GateModel record équatable — namespace, type conteneur, nom de la méthode, entitlement, kind, clé de limite et la Location de l’attribut pour les diagnostics. Garder ce modèle comme un type par valeur avec égalité structurelle est ce qui permet au pipeline incrémental de mettre en cache correctement.
Valider les noms contre le manifeste
C’est là que le générateur gagne sa place face à un simple snippet. Un unique catalogue déclaré — le même entitlements.json que possède déjà votre configuration d’émission — liste chaque entitlement que le produit connaît. Référencez-le depuis le projet consommateur pour que le générateur puisse le lire :
<ItemGroup>
<AdditionalFiles Include="entitlements.json" />
</ItemGroup>
Dans Emit, comparez l’entitlement de chaque contrôle au manifeste et signalez une erreur de compilation quand il est inconnu — mais uniquement lorsqu’un manifeste a effectivement été fourni, pour que les projets qui le refusent ne soient pas forcés de l’utiliser :
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));
}
Désormais [Gate("exprot.pdf")] est un soulignement rouge et une compilation échouée avec le message KR0001: Entitlement 'exprot.pdf' is not declared in entitlements.json, attrapé au moment de la faute de frappe et non six semaines plus tard, quand un client ne peut pas exporter. Voilà tout l’argument pour faire ceci dans un générateur : le compilateur devient ce qui maintient vos contrôles honnêtes.
Rendre la garde
Le corps émis est délibérément ennuyeux. Il résout un LicenseInfo en cache et interroge l’ensemble des entitlements — les deux mêmes appels que vous écririez à la main, désormais écrits à l’identique à chaque fois :
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 est la seule pièce de code d’exécution ordinaire, qui conserve un LicenseInfo en cache pour que chaque garde soit une lecture de champ, pas une re-vérification :
public static class LicenseGate
{
private static readonly Lazy<KeyrightClient> Client = new(() =>
KeyrightClient.Initialize(new KeyrightOptions
{
Product = "Acme.Pdf",
PublicKeyBase64 = AcmePublicKey.Base64, // vérification seule ; sûr à distribuer
ServiceUrl = "https://license.acme.example" // votre service self-hosted
}));
private static volatile LicenseInfo? _cached;
public static LicenseInfo Current => _cached ??= Client.Value.Validate();
public static void Refresh() => _cached = Client.Value.Validate();
}
Validate() est un calcul purement local contre la clé publique embarquée — il ne lève jamais d’exception et échoue fermé, retournant un LicenseInfo d’édition Free sur tout problème — donc un entitlement absent ou inconnu se lit comme désactivé et la garde lève une exception. L’activation en ligne s’exécute une fois pour mettre la licence en cache ; tout ce que font ensuite les contrôles générés est offline.
Ce que le générateur n’est pas
La mise en garde honnête compte. Un générateur de source émet du C# ; la garde compilée est aussi visible pour un décompilateur que tout ce que vous écririez vous-même, et rien dans le fait de la générer ne rend la branche IsEnabled plus difficile à retirer par patch. La sécurité ne réside pas dans le contrôle — elle réside dans la signature. Validate() vérifie la licence signée contre une clé publique qu’un attaquant ne peut pas falsifier, et cette vérification est la frontière. Le rôle du générateur est plus étroit et vaut malgré tout la peine : il rend chaque contrôle cohérent, impossible à oublier sur un point d’appel décoré et impossible à mal orthographier sans faire échouer la compilation. Si vous voulez en plus que la vérification d’exécution elle-même résiste à la falsification, c’est le travail de l’obfuscation et de l’anti-tamper superposés par-dessus — un outil différent pour une menace différente. Utilisé pour ce qu’il est, le générateur transforme un motif dispersé et propice à la dérive en une unique déclaration que le compilateur vérifie pour vous.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.