Kanject.Core.Features.Annotations 3.13.0

Kanject.Core.Features.Annotations

Roslyn source generators, analyzers, and MSBuild targets for Kanject edition-locking. From an [EditionLadder] enum and the <KanjectEdition> build property they emit compile-time Editions.Has* constants, an AddLockedFeatures() DI extension that omits locked services, prune points that vanish from lower editions, runtime IFeatureGate guards, and a post-publish check that proves locked code is absent from a trimmed or Native AOT artifact.

Install it next to the runtime package Kanject.Core.Features; the concepts and end-to-end guide live in that package's README.

Installation

<ItemGroup>
  <PackageReference Include="Kanject.Core.Features" />                       
  <PackageReference Include="Kanject.Core.Features.Annotations" PrivateAssets="all" />
</ItemGroup>

or:

dotnet add package Kanject.Core.Features
dotnet add package Kanject.Core.Features.Annotations

dotnet add package writes an IncludeAssets line for this package that omits compile. Delete that line (keep PrivateAssets="all") — otherwise the attribute types from Kanject.Core.Features.Annotations.Attributes can be stripped from compilation.

The package targets netstandard2.0 because it runs inside the C# compiler, and is marked as a development dependency. Code it generates calls into Kanject.Core.Features (.NET 8, .NET 9 and .NET 10), which does not reference this package — reference both. The attribute types come from Kanject.Core.Features.Annotations.Attributes, a dependency of this package.

Reference it as a package. The package's build/ props make <KanjectEdition> and the other switches visible to the compiler, and its targets implement locked references, the publish guard, and pruning verification. Wired any other way (a ProjectReference or a bare <Analyzer> item), those files aren't imported: <KanjectEdition> is never seen and the generators silently build the lowest edition. If you must, import the .props and .targets yourself.

Quick start

using Kanject.Core.Features.Annotations.Attributes;

[EditionLadder]
public enum Edition { Free, Pro, Enterprise }

[LockedBehind(Edition.Pro)]
public sealed class AdvancedExportEngine : IExportEngine
{
    public ExportResult Export(Project project) => /* premium implementation */;
}

services.AddLockedFeatures();   // generated into your project's root namespace

if (Editions.HasEnterprise)     // generated const; the false branch is removed by the trimmer
{
    services.AddSingleton<IAuditSink, SiemAuditSink>();
}

dotnet publish -p:KanjectEdition=Free -p:PublishTrimmed=true
dotnet publish -p:KanjectEdition=Pro  -p:PublishTrimmed=true

With KanjectEdition=Pro, the generator emits:

public static class Editions
{
    public const Edition Current = Edition.Pro;
    public const bool HasFree = true;
    public const bool HasPro = true;
    public const bool HasEnterprise = false;
}

and AddLockedFeatures() registers AdvancedExportEngine as itself and as IExportEngine. With KanjectEdition=Free, those registration lines are omitted.

What gets generated

For a runtime gate such as

public sealed partial class Dashboard
{
    private readonly IFeatureGate _gate;
    public Dashboard(IFeatureGate gate) => _gate = gate;

    [LockedBehind("beta.export", Fallback = nameof(Locked))]
    public partial string Render();

    private string RenderCore() => "high-res export";
    private string Locked() => "Upgrade to export.";
}

the guard generator emits (header comments omitted):

partial class Dashboard
{
    public partial string Render()
        => _gate.IsEnabled(new global::Kanject.Core.Features.Models.FeatureKey("beta.export"))
            ? RenderCore()
            : Locked();
}

For typed license claims:

using System.Collections.Immutable;
using Kanject.Core.Features.Annotations.Attributes;

[EntitlementClaims]
public sealed partial class LicenseClaims
{
    [Claim("seats")]   public int Seats { get; init; }
    [Claim("tier")]    public string Tier { get; init; } = "";
    [Claim("modules")] public ImmutableArray<string> Modules { get; init; }
}

// claimsJson: a JSON object such as {"seats":25,"tier":"gold","modules":["reports"]}
LicenseClaims claims = LicenseClaims.FromClaimsJson(claimsJson);

Shape rules the generators enforce

The generators report a diagnostic rather than silently skipping an input shape they can't handle.

• Method guard / edition prune: the containing type must be a non-generic, non-nested, non-static class; the locked method must be an instance partial method; {Method}Core must be an instance method whose signature matches (return type, parameters, ref/in/out, generic arity, constraints) — otherwise KANFL004. A Fallback must be an instance method with the same signature (KANFL002). out parameters are rejected.
• Edition prune only: the method must be void, have no out parameter, and carry no accessibility or virtual/override/sealed/new/extern/async/abstract modifier (KANFL007). A stateless seam trips CA1822 (on the partial declaration and {Method}Core) and IDE0051 ({Method}Core is unreferenced below the lock) under TreatWarningsAsErrors; suppress those three on the seam.
• Method guard only: the class (or a base) needs an IFeatureGate field or property.
• Interceptors: the locked method, gate member, and fallback must be non-private; generic or static methods, calls without an explicit receiver, ?. calls, and method-group conversions are KANFL004.
• Entitlement claims: the claims type may be nested or generic. It and every containing type must be partial (KANFL010, KANFL015), and it must have no primary constructor (KANFL013); each [Claim] property must be a settable instance property (KANFL014) of type int, long, bool, string, or ImmutableArray<string> (KANFL011) with a unique key (KANFL012). Missing, wrong-typed, or malformed claims resolve to defaults (0, false, "", empty array) rather than throwing.

Assembly boundaries

• Edition generators are assembly-local to the [EditionLadder]. They only see a ladder declared in the same compilation. With no ladder, the partial-void prune reports KANFL004, the [PrunedBelow] manifest reports KANFL001, an edition-locked service reports KANFL001, and nothing is emitted for them. Keep prunable code in the ladder's assembly and gate other assemblies with the generated Editions.HasX constants (make the enum public and build every project with the same -p:KanjectEdition=...). String-flag and Binding = FeatureBinding.Runtime method locks don't need the ladder.
• Exactly one [EditionLadder] per assembly (KANFL005).
• VerifyEditionPruning is single-project. It reads the manifest generated in the publishing project and inspects that project's own published assembly (or .mstat), so the ladder, markers, generator, and trimmed/AOT publish must share one project.

MSBuild properties and items

<PropertyGroup>
  <KanjectEditionLadder>Free;Pro;Enterprise</KanjectEditionLadder>
  <RequireExplicitEditionOnPublish>true</RequireExplicitEditionOnPublish>
  <VerifyEditionPruning>true</VerifyEditionPruning>
</PropertyGroup>

<ItemGroup>
  <LockedReference Include="..\App.Pro\App.Pro.csproj" MinEdition="Pro" />
</ItemGroup>

Pruning verification notes: it fails closed (a missing or unreadable artifact is an error), and it self-checks its detector on every run. The Native AOT (.mstat) backend verifies non-generic types only; verify member-level and generic [PrunedBelow] markers against a trimmed (PublishTrimmed) artifact.

Analyzers

Diagnostics

KANFL050 is the runtime code carried by FeatureLockedException in Kanject.Core.Features.

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.