Kanject.Core.Annotations 3.14.0

Kanject.Core.Annotations

Roslyn incremental source generators and analyzers for the attribute-driven features of Kanject.Core: [Parallel] fan-out, [Recurring] / [RecurringHosted] schedules, [QueryableEnum] lookups, and the opt-in PrintInConsole interceptors. The generators turn attributes into ordinary C# at compile time, so these features use no runtime reflection. The analyzers catch invalid attribute usage in the editor, before the generator would otherwise produce nothing or broken code.

Kanject.Core depends on this package, so its generators normally reach your project through Kanject.Core. Reference it explicitly anyway, on the same version as Kanject.Core, so the generator version is pinned alongside the runtime.

Installation

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

Or from the CLI: dotnet add package Kanject.Core.Annotations, then add PrivateAssets="all" to the new reference. Keep its version equal to your Kanject.Core version, because the generated code calls into Kanject.Core's runtime types.

You need this package for the following:

• [Parallel] generated overloads
• [Recurring] / [RecurringHosted] generated loops, services and registrations
• [QueryableEnum] on your own enums
• the PrintInConsole interceptors and the MSBuild properties
• every diagnostic in the table below

You don't need it for the parts of Kanject.Core you call directly, such as ParallelLoop, RecurringLoop, the timezone, JSON and collection helpers, or plain PrintInConsole.

Package layout. This is not a development-dependency package. It ships the generators in analyzers/dotnet/cs, a lib/netstandard2.0 assembly, MSBuild props and targets in build/ and buildTransitive/, and a dependency on Kanject.Core.Annotations.Attributes (the attribute types). PrivateAssets="all" stops the generators from also running in projects that reference yours.

dotnet add package writes a plain reference for this package, with no IncludeAssets line. If you add an IncludeAssets line yourself, make sure it includes compile. The attribute types from Kanject.Core.Annotations.Attributes reach your project through this package, and an IncludeAssets list without compile strips them from compilation.

The analyzer assembly targets netstandard2.0, as Roslyn requires. The generated code calls into Kanject.Core and targets the same frameworks: .NET 8, .NET 9 and .NET 10.

Quick start

using Kanject.Core.Annotations.Attributes.Recurring;
using Kanject.Core.Annotations.Attributes.Recurring.Enums;

namespace Shop;

public sealed partial class HeartbeatService(IPingClient client)
{
    [Recurring(5, RecurringRateUnit.Seconds, MaxIterations = 12)]
    public Task PingAsync(CancellationToken ct) => client.PingAsync(ct);
}

At compile time, RecurringGenerator emits HeartbeatServiceRecurringExtensions.PingAsyncRecurringAsync(...), a partial IHeartbeatServiceRecurring interface, and a partial declaration of HeartbeatService that implements it. Callers write await heartbeat.PingAsyncRecurringAsync(cancellationToken: ct). If the method returned an unsupported type, or were async void, the analyzer would report KANREC001 or KANREC012 instead of leaving you with no extension method.

What it generates

Generated member names append a fixed suffix to the method name. [Parallel] drops a trailing Async first (ProcessAsync becomes ProcessParallelAsync). [Recurring] keeps the name as written (PingAsync becomes PingAsyncRecurringAsync, and AddHeartbeatServicePingAsyncRecurring for hosted registration).

Things to know when annotating code:

• Instance methods need a partial containing type. The Parallel and Recurring generators add a partial declaration of the same kind (class, record or struct) to the containing type so it implements the generated interface. The generated extension class and interface are internal when the containing type isn't public. KANPAR011 ([Parallel]) and KANREC013 ([Recurring]) report a missing partial.
• [QueryableEnum] output follows the enum. It is emitted into the enum's namespace (or the global namespace) and names the enum by its fully qualified name, so nested enums work. It is internal when the enum isn't public. A private or protected nested enum can't be reached from the generated top-level types and reports KANQE001. Aliased members (A = 1, B = 1) share one value entry, owned by the first-declared name.
• Some shapes are not generated. Generic methods (KANPAR006, KANREC004) and methods on nested types (KANPAR007, KANREC003) get a warning instead of generated code. ref/out/in parameters are errors (KANPAR008, KANREC008).
• [ParallelHosted] is validated but not generated. The analyzer checks it (KANPAR009, KANPAR010) and reports KANPAR014 because this release emits no hosting code for it.

MSBuild properties

Set these in the project file of a project that references this package. The package exposes them to the generators and analyzers as CompilerVisibleProperty items.

Opt-in convention analyzers

The package also contains optional analyzers for a strict file-organization convention: one top-level type per file, no accessible nested types, and enums kept under an Enums/ folder. They report nothing unless you opt in:

<PropertyGroup>
  <EnableKanjectDevAnalyzers>true</EnableKanjectDevAnalyzers>
  
  <KanjectDeterministicCode>true</KanjectDeterministicCode>
</PropertyGroup>

Generated code is excluded from these rules. KANDEV005 compares a type's namespace with its folder using the project's RootNamespace and ProjectDir, which the package makes visible to the compiler automatically. KANDEV006 flags ambient time (DateTime.Now/UtcNow/Today, DateTimeOffset.Now/UtcNow), current culture, Environment.TickCount and unseeded Random. Guid.NewGuid() and new Random(seed) are allowed. To change a rule's severity, use .editorconfig:

[*.cs]
dotnet_diagnostic.KANDEV001.severity = warning

Diagnostics

A code fix accompanies KAN001, KAN002 and KANJECT0021-KANJECT0024. It can keep only the first value, remove a duplicate [EnumParameter], or remove the offending name from ConstantParameters.

Release notes

3.12.7

PluralizerHelper.Singularize — the helper the generators use to derive an entity name from a table or key alias — changed in three ways that were not announced at the time:

• The unchanged-plural set is now consulted, so a word whose singular and plural coincide comes back as-is: Status → Status (was Statu), Series → Series. The set includes Settings, so a name derived from a Settings alias is now Settings, not Setting.
• A trailing ss is never treated as a plural s: Address → Address (was Addres).
• The ies → y rule keeps the input's casing: COUNTRIES → COUNTRY (was COUNTRy).

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.