Kanject.Core.Channels.Annotations 3.14.0

Kanject.Core.Channels.Annotations

Roslyn source generator, analyzer, and code fix for Kanject channels. Annotate a batch handler with [Channel] and this package generates, at compile time, a typed writer interface, a DI registration extension, and either a hosted BackgroundService consumer or an AWS Lambda invocation-local drain helper — all running on the Kanject.Core.Channels engine. The analyzer reports handler-shape and configuration mistakes as build diagnostics (KANCHN…).

Installation

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

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

This is a development-only package (DevelopmentDependency): it ships the generator under analyzers/ and adds no runtime assembly to your output. Kanject.Core.Channels does not reference it, so add it explicitly to every project that declares [Channel] handlers. The runtime does reference Kanject.Core.Channels.Annotations.Attributes, which supplies the attribute types.

The generator targets netstandard2.0 and runs inside the compiler. The code it emits uses Kanject.Core.Channels, which targets .NET 8, .NET 9 and .NET 10.

Quick start

using Kanject.Core.Channels.Annotations.Attributes;

namespace Shop.Orders;

public sealed record OrderPlaced(string OrderId, decimal Total);

public sealed partial class OrderProjector(IOrderReadModel readModel)
{
    [Channel(Capacity = 5000, BatchSize = 25, FlushIntervalMs = 200)]
    public async ValueTask ProjectAsync(ReadOnlyMemory<OrderPlaced> batch, CancellationToken ct)
    {
        await readModel.UpsertAsync(batch.ToArray(), ct);
    }
}

// Composition root
builder.Services.AddOrderProjectorProjectAsyncChannel();

// Producer
public sealed class CheckoutService(IOrderProjectorProjectAsyncChannelWriter orders)
{
    public ValueTask OnOrderPlacedAsync(OrderPlaced order, CancellationToken ct) =>
        orders.WriteAsync(order, ct);
}

The handler is an ordinary method with a body; only its containing type must be partial. The generated files fully qualify every type and DI extension call, so they compile without any using in your project — including a plain Microsoft.NET.Sdk project with ImplicitUsings off.

What gets generated

For a [Channel] method M on type T with item type TItem (hint names are T_M.*.g.cs):

Everything is emitted into the handler's namespace. ChannelName defaults to T_M and can be overridden with [Channel(ChannelName = "…")]; it does not change the generated type names.

The DI extension copies the attribute values into a ChannelOptions (Capacity, FullMode, BatchSize, FlushInterval, RestartOnFault, MaxRestartAttempts, SafetyMargin), runs your configure callback, and creates the bounded channel. FullMode is mapped to the BoundedChannelFullMode member of the same name. The extension then registers:

• ChannelOptions, Channel<TItem>, ChannelReader<TItem> and ChannelWriter<TItem> as keyed singletons under T{M}ChannelServiceCollectionExtensions.ServiceKey (the handler's fully qualified Namespace.Type.Method). Several channels — including several over the same item type — therefore coexist in one container. Resolve them with GetRequiredKeyedService<ChannelWriter<TItem>>(T{M}ChannelServiceCollectionExtensions.ServiceKey) or [FromKeyedServices(…)]. Nothing is registered unkeyed.
• The writer interface IT{M}ChannelWriter as a singleton bound to this channel.
• In InProcess mode, the hosted consumer (built over this channel's reader and options) and the handler type with the lifetime from Lifetime (Scoped by default, which gives each batch its own async DI scope).

Calling the same AddT{M}Channel twice on one IServiceCollection throws InvalidOperationException: the host de-duplicates the hosted consumer by type, so a second registration would leave a writer feeding a channel nobody drains.

Mode resolution

ChannelMode.Default is resolved when the project compiles: InvocationLocal if the compilation references Kanject.Core.CloudFunction.Provider.AwsLambda, otherwise InProcess. Distributed emits only the writer interface and the DI extension — no consumer.

Handler shape the generator expects

• An ordinary method (not a local function, lambda, operator, accessor or explicit interface implementation — KANCHN024), non-generic and on a non-generic type (KANCHN019).
• public, internal or protected internal, on containing types that are too (KANCHN022): the generated consumer is a separate type that calls it.
• Returns Task or ValueTask (KANCHN003; async void included).
• The partition is the first parameter that isn't a CancellationToken: TItem for per-item handlers, or ReadOnlyMemory<TItem> / IReadOnlyList<TItem> for batched ones (KANCHN004). ReadOnlyMemory<TItem> is passed through without copying; an IReadOnlyList<TItem> handler receives a copy of each batch as an array, in every mode. TItem can't be a ref struct or pointer (KANCHN023).
• A CancellationToken is optional and may appear in any position; the consumer forwards its token to the first one.
• Generated consumers bind arguments by name, so any other parameter must be optional or params and keeps its default (KANCHN021). No parameter may be ref, out, in or ref readonly (KANCHN020).

The generator emits nothing for a method that breaks any of these rules; the analyzer reports why.

Things the generated wiring does not do

• In InvocationLocal mode the DI extension does not register the handler type — register it yourself.
• [ChannelProducer] generates nothing; every use is reported as KANCHN017. Use a [Channel(Mode = ChannelMode.Distributed)] handler for a producer-only port.

See the Kanject.Core.Channels package for the drain contracts, the Lambda guidance, and ChannelOptions.

Diagnostics

If the generator itself throws while emitting code, it reports KANJECTGEN001 (Error) with the exception message instead of failing silently.

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.