PolyBot Roslyn Source Generator Internals and Design

​

Entry point: PolyBotGenerator

[Generator]
public sealed class PolyBotGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context) { ... }
}

​

Library vs executable detection

IncrementalValueProvider<bool> isLibraryProvider =
    context.AnalyzerConfigOptionsProvider.Select(
        static (options, _) =>
            options.GlobalOptions.TryGetValue("build_property.OutputType", out string? outputType) &&
            string.Equals(outputType, "Library", StringComparison.OrdinalIgnoreCase));

​

Discovery phases

​

FilterDiscovery

• TypeFqn — fully qualified type name for use in emitted code
• ShortName — the class name without any namespace prefix, used to derive the [XxxFilter] attribute name
• DtoBaseName — the name of the generated abstract DTO base the filter subclasses (e.g. MessageFilter), or null for raw IUpdateFilter implementations

​

HandlerDiscovery

1. Locates the handler attribute — looks for an attribute that inherits HandlerAttribute (or, for error-type symbols on the first pass, matches the stem against UpdateType enum member names). Stacking a second handler attribute (e.g. [UpdateHandler] + [MessageHandler]) on one method is rejected with CUR041.
2. Resolves the update type — reads UpdateHandlerDescriptorAttribute on the handler attribute class first; falls back to the naming convention (MessageHandlerAttribute → UpdateType.Message). [UpdateHandler] is special-cased: it resolves to the raw Telegram.Bot.Types.Update, reads its Types array into a (possibly empty = universal) member list, and is validated separately (CUR040 when no Update parameter exists, CUR043 on [Command]/[Pattern]/state guards).
3. Classifies the return type — Task<Result>, ValueTask<Result> → HandlerReturnKind.Result; Task/ValueTask → HandlerReturnKind.Plain; anything else → CUR001.
4. Processes [Command] and BotFather metadata — reads Aliases, Prefix, Description, Scope, LanguageCode, IsHidden. Validates alias format (CUR020), checks description length (CUR022).
5. Processes [Arg], [Rest], [Parse] — validates types and ordering, builds ArgModel and TailConsumerModel lists.
6. Resolves filter attributes — matches attribute names against the FilterClassModel list (own-assembly filters) or walks referenced assemblies on demand (library filters).
7. Processes [State<TEnum>] / [NoState<TEnum>] — folds same-pair conditions into OR groups; AND-links distinct pairs; reports CUR011 on mutual exclusion.
8. Classifies handler parameters — ITelegramBotClient, CancellationToken, Update, payload, [Arg]/[Rest]/[Parse], IStateMachine, IStateStorage, IUpdateAwaiter, [Key] keyed services, or plain DI service.
9. Extracts await sites — walks AwaitExpression nodes inside the method body, follows WaitFor*Async call chains, and records the DTO type, TextMatches patterns, WithFilter<T> types, Where lambdas, and terminal key mode (ByUserId, ByChatId, ByUserInChat). Reports CUR013–CUR016 as appropriate.
10. Processes [Pattern] — parses the template into PatternSegmentModel list, validates placeholder ↔ [Arg] bindings, checks 64-byte limit, resolves TryParse kind.
11. Processes [Throttled] — reads Limit, PeriodMilliseconds, Scope, Action; reports CUR035 on invalid values.

​

KeyboardDiscovery

​

ExceptionHandlerDiscovery

​

Emitters

​

BotRouterEmitter

• A private readonly IServiceProvider _services field
• An optional private readonly PolyBotOptions? __curatorOptions field (when any handler uses [Command])
• Per-await-site static string[] and Type[] constant fields for the declarative signature arrays
• Per-throttle-gate static ThrottleGate fields
• A constructor taking IServiceProvider
• HandleUpdateAsync — a switch on update.Type, one case per discovered update type (plus any update types referenced only via await sites), with inlined handler branches
• HandleErrorAsync — calls the [ExceptionHandler] method (if any); otherwise returns Task.CompletedTask

1. Await-site branches come first (static pre-filter conditions → TryDeliverAsync → return if claimed)
2. Handler branches follow in descending Priority order
3. A break terminates the case

​

FilterAttributesEmitter

// For NonEmptyTextFilter : MessageFilter
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public sealed class NonEmptyTextFilterAttribute : Attribute { }

​

AwaiterExtensionsEmitter

​

KeyboardMarkupEmitter

​

BotFatherSyncEmitter

​

HostingEmitter

• PolyBotHosting.g.cs — emitted when Microsoft.Extensions.Hosting.Abstractions is referenced. Contains AddPolyBotHostedPolling(...) extension and PolyBotPollingHostedService : IHostedService.
• PolyBotWebhook.g.cs — emitted when any Microsoft.AspNetCore.* assembly is referenced. Contains AddPolyBotWebhook(), MapPolyBotWebhook(string), and PolyBotWebhookHostedService : IHostedService.

​

PolyBotExtensionsEmitter

​

What gets generated: summary

​

The PolyBot.InternalsGenerators companion

• The abstract handler attribute bases (MessageHandlerAttribute, etc.), one per UpdateType, each stamped with [UpdateHandlerDescriptor(UpdateType.Message, "Message")]
• The abstract generated filter DTO bases (MessageFilter, CallbackQueryFilter, etc.) with their CanPass(Update) implementations that extract the payload
• Per-update-type narrowing filter bases for DTOs shared across multiple update types
• The WaitFor{UpdateType}Async(this IUpdateAwaiter, TimeSpan?) extension methods in namespace PolyBot.Attributes (class PolyBotAwaiterExtensions), compiled directly into the PolyBot library assembly — these are always available regardless of whether any IUpdateFilter is discovered in the consuming project

​

Cross-assembly filter resolution

1. The filter attribute class (or the With* extension type) comes from the referenced assembly.
2. The generator calls FindFilterInAssembly(assembly, stemName, filterInterface), which walks the referenced assembly’s namespace tree recursively looking for a concrete, non-generic class named stemName that implements IUpdateFilter.
3. The fully qualified type name of the found class is used in the emitted BotRouter code.