Kanject.Core.Queue.Provider.AwsSqs.Annotations 3.9.0

Kanject.Core.Queue.Provider.AwsSqs.Annotations

Roslyn incremental source generators, an analyzer and a code fix for Kanject.Core.Queue.Provider.AwsSqs. The generators turn [QueueMessage], [QueueConsumer] and [RouteQueueConsumer] declarations into four kinds of output:

• DI registration methods.
• Typed send methods.
• Consumer base-class wiring.
• Lambda SQSEvent dispatch methods.

The package also writes a Markdown catalog of the project's queues at build time.

Installation

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

Kanject.Core.Queue.Provider.AwsSqs already depends on this package, so the generators normally reach your project through it. Reference this package directly anyway, so the generator version is explicit and pinned alongside the provider.

This package isn't marked as a development dependency, so dotnet add package writes a plain reference. Add PrivateAssets="all" yourself so the generator doesn't flow on to projects that reference yours. If you add an IncludeAssets line to this reference, keep compile in it or delete the line. Otherwise the attribute types from Kanject.Core.Queue.Provider.AwsSqs.Annotations.Attributes can be stripped from compilation.

The package targets netstandard2.0 because it runs inside the C# compiler. The code it generates compiles against Kanject.Core.Queue.Provider.AwsSqs, which targets .NET 8, .NET 9 and .NET 10. The generators only process types declared in the project that references them.

Quick start

using Amazon.Lambda.SQSEvents;
using Kanject.Core.Queue.Abstractions.Models;
using Kanject.Core.Queue.Provider.AwsSqs.Annotations.Attributes;

namespace Shop.Orders;

[QueueMessage("orders")]
public sealed class OrderPlaced
{
    public string OrderId { get; set; } = string.Empty;
}

[QueueConsumer(Message = typeof(OrderPlaced))]
[QueueConsumerDependency(typeof(IFulfilmentService))]
public partial class OrderPlacedConsumer
{
    protected override async Task ConsumeAsync(
        List<MessageContext<OrderPlaced>> messages, CancellationToken cancellationToken)
    {
        foreach (var context in messages)
        {
            await FulfilmentService.ShipAsync(context.Message, cancellationToken);
            await AcknowledgeAsync(context);
        }
    }
}

With these declarations, you can write:

services
    .AddAwsSqsGlobalQueueConfiguration(options => { /* credentials, region */ })
    .AddOrdersQueue()            // from [QueueMessage("orders")]
    .AddOrderPlacedConsumer();   // from [QueueConsumer]

await queueManagerService.EnqueueOrderPlacedAsync(new OrderPlaced { OrderId = "o-1" });

// Lambda handler body:
return await serviceProvider.ProcessOrderPlacedEventAsync(sqsEvent, cancellationToken);

The generated extension classes are emitted in the namespace of the annotated type.

What gets generated

[QueueMessage("orders")] on a message type

Apply it to a class, record, record struct or struct. The queue name is converted to a method-name stem by PascalCasing its - / _ segments and appending Queue, so orders becomes OrdersQueue and order-events becomes OrderEventsQueue.

A cluster node on the attribute ([QueueMessage("orders", 2)]) is sent as the cNode metadata entry by every Enqueue…Async overload, single or batch, on each message. Metadata you pass in is copied, not modified, and a cNode entry you supply yourself is kept.

[QueueConsumer] on a partial class

The generator writes the base class and a constructor that takes IQueueRegistry plus one parameter per [QueueConsumerDependency(typeof(T))]. Each dependency is also exposed as a protected get-only property. An interface loses its leading I, so IFulfilmentService becomes FulfilmentService, and the optional second argument overrides the name. Don't declare a base class or constructor yourself.

For a class named OrderPlacedConsumer, it also generates:

[QueueConsumerFilter]: several consumers on one queue

When the [QueueConsumer] classes on one queue carry a [QueueConsumerFilter] on the same message property, the generator adds one dispatcher for the queue. For orders, that's ProcessOrdersQueueEventAsync(SQSEvent, CancellationToken = default):

// OrderEvent carries [QueueMessage("orders")]
[QueueConsumer(Message = typeof(OrderEvent))]
[QueueConsumerFilter("Kind", new[] { "created", "updated" })]
public partial class OrderChangedConsumer { /* ConsumeAsync */ }

[QueueConsumer(Message = typeof(OrderEvent))]
[QueueConsumerFilter("Kind", new[] { "cancelled" })]
public partial class OrderCancelledConsumer { /* ConsumeAsync */ }

The dispatcher reads the property from each record's JSON body, either at the top level or inside an SNS-style Message envelope. It matches values case-insensitively and passes each group of records to its consumer, then returns the combined failures, or null when nothing failed.

The enum form is [QueueConsumerFilter<OrderKind>("Kind", new[] { OrderKind.Cancelled }, EnumComparisonMode.Name)]. EnumComparisonMode.Name compares member names (for JsonStringEnumConverter), and the default EnumComparisonMode.Value compares numeric values. All consumers that filter the same property must use the same form and mode.

A record whose property is missing or has an unlisted value makes the dispatcher throw InvalidOperationException, which fails the whole invocation.

[RouteQueueConsumer] on a partial class

[RouteQueueConsumer] takes the same QueueName / QueueNamespace / Message properties. Add one or more [QueueConsumerRoute("route")] attributes. The class derives from AbstractRouteQueueConsumer<TMessage>, or AbstractRouteRawQueueConsumer when Message is omitted, and gets the same dependency-injecting constructor. Route consumers are registered as scoped services.

For every queue that has route consumers (for example order-events), the generator adds:

Publish to a route with queueManagerService["order-events"].EnqueueAsync("order.created", message).

Queue schema file

After each build, the package's MSBuild target writes $(AssemblyName).queueschema.md next to the project file. The file is a Markdown catalog of the project's queue messages, consumers, route consumers and subscriptions, which is useful as reference or AI-prompt context. dotnet clean deletes it.

While GenerateQueueSchema is on, the target also sets EmitCompilerGeneratedFiles=true unless you set it yourself, because it reads the generated source from disk.

Event-hub integration attributes

[EventQueue], [SubscribeToQueue] and [EventHubQueueRouter] are hooks for event-hub integrations that this SDK doesn't ship:

• [EventQueue] generates Create…EventQueue / Acknowledge… helpers only when the same type also carries a [HubEvent] or [EventHubTopic] attribute.
• [SubscribeToQueue] is recorded in the queue schema only.
• [EventHubQueueRouter] on a route consumer suppresses the generated router methods for it.

Diagnostics

The generators also report KANJECTGEN002 (error) in three cases:

• Two consumers of one queue declare the same [QueueConsumerFilter] value.
• Consumers that filter the same property mix enum comparison modes.
• A [QueueConsumerFilter] is placed on a route consumer, which isn't supported.

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.