IWF.TeleFlow.Annotations 1.0.0-alpha.2

TeleFlow

TeleFlow is an explicit Telegram bot framework for .NET.

It is built for the normal lifecycle of a Telegram bot: a first command, then callbacks, state, role checks, background services, retries, storage, diagnostics, deployment, and a codebase that still needs to be readable after it grows.

Starts like a script. Grows like a system.

Documentation

The repository documentation is split like a small product site and is ready to be moved to GitHub Pages later.

• Documentation home
• English documentation
• Russian documentation
• Quickstart
• Configuration and secrets
• Recommended paths
• Package guide
• Support desk tutorial
• Enterprise guide
• Feature reference
• Roadmap

Community

• Telegram chat for quick questions, ideas, and alpha feedback.
• GitHub Issues for reproducible bugs and tracked feature requests.

What TeleFlow Gives You

• Handler routing with attributes such as [Command], [Text], [Callback], [State], [SceneStep], and media filters.
• Build-time generated handler metadata through the IWF.TeleFlow.Generators package.
• A deliberate failure when generated metadata is missing. No silent reflection fallback on the recommended path.
• Direct Telegram Bot API access through ITelegramClient and generated ctx.Bot.*Async extension methods.
• Message and callback helpers for common flows: answers, replies, edits, deletion, media, keyboards, and chat actions.
• Typed callback payloads with compact callback data serialization.
• State, state data, wizard navigation, and replaceable storage contracts.
• Long polling and ASP.NET Core webhook framework adapters.
• Raw long polling and raw webhook packages for applications that do not want the handler framework.
• Normal .NET dependency injection for handlers, services, repositories, filters, storage, and infrastructure.

Install

TeleFlow is currently published as a public alpha. Use --prerelease or pin an exact alpha version.

For a handler-based long polling bot:

dotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling --prerelease
dotnet add package IWF.TeleFlow.Generators --prerelease
dotnet add package IWF.TeleFlow.Storage.Memory --prerelease

Keep the generator as a private build-time dependency:

<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />

For direct Bot API access without the framework:

dotnet add package IWF.TeleFlow.Telegram --prerelease

First Bot

Create a console app, install the packages above, and set TELEFLOW_BOT_TOKEN:

export TELEFLOW_BOT_TOKEN=123456:token

PowerShell:

$env:TELEFLOW_BOT_TOKEN = "123456:token"

Replace Program.cs with this:

using TeleFlow.Annotations;
using TeleFlow.Core.Application;
using TeleFlow.Storage.Memory;
using TeleFlow.Telegram;

var token = Environment.GetEnvironmentVariable("TELEFLOW_BOT_TOKEN")
    ?? throw new InvalidOperationException("TELEFLOW_BOT_TOKEN is not set.");

var builder = TeleFlowApplication.CreateBuilder(args);

builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddMemoryStateStorage();
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddLongPolling();

await using var app = builder.Build();
await app.RunAsync();

public sealed class StartHandler
{
    [Command("start")]
    public Task Handle(MessageContext ctx, CancellationToken ct)
    {
        return ctx.Message.AnswerAsync("Hello from TeleFlow.", ct);
    }
}

This example uses generated assembly registration. If the IWF.TeleFlow.Generators package is not referenced by the application project, AddTelegramHandlersFromAssembly(...) fails during startup with a clear configuration error.

Recommended Reading Order

If you are new to bot frameworks, read:

1. Quickstart
2. Configuration and secrets
3. Recommended paths
4. Handlers and routing
5. Callbacks and keyboards
6. State and wizard

If you already build production .NET services, read:

1. Packages
2. Configuration and secrets
3. Application model
4. Project structure
5. Dependency injection
6. Transports
7. Deployment
8. Performance and scaling
9. Versioning and releases
10. Enterprise guide

Project Status

TeleFlow is in active development. The documentation describes APIs that exist in the current repository. Planned features belong in roadmap documents, not in user-facing API documentation.

Planned framework work is tracked in the roadmap.

Runtime packages currently target net10.0. The IWF.TeleFlow.Generators package targets netstandard2.0 because analyzers and source generators run inside the compiler.

Benchmarks

The repository includes an isolated BenchmarkDotNet project for no-network runtime measurements:

• Benchmark methodology and commands

Benchmark dependencies are intentionally kept outside TeleFlow.sln and do not affect normal library builds or package graphs.

License

TeleFlow is released under the MIT License.