Пакеты TeleFlow разделены по ответственности. В application code обычно используется один namespace:
using TeleFlow.Telegram;NuGet package IDs используют prefix IWF.TeleFlow.*. C# namespaces остаются короткими для пользовательского кода.
Большинство приложений ставит небольшой набор входных пакетов. Остальная часть package graph нужна для чистых внутренних границ и обычно подтягивается транзитивно.
| Сценарий | Package reference | Что даёт |
|---|---|---|
| Handler framework с long polling | IWF.TeleFlow.Framework.LongPolling |
Handler framework плюс long-polling transport |
| Handler framework с webhooks | IWF.TeleFlow.Framework.Webhooks |
Handler framework плюс ASP.NET Core webhook transport |
| Прямой доступ к Telegram Bot API | IWF.TeleFlow.Telegram |
Low-level ITelegramClient, generated Bot API methods, defaults, JSON, transport, exceptions, deep links |
| Generated handler metadata | IWF.TeleFlow.Generators |
Source generator и analyzer package для build-time handler registration. Подключай напрямую с PrivateAssets="all" |
| In-memory state storage | IWF.TeleFlow.Storage.Memory |
Process-local state, state data, wizard history и регистрация state middleware |
| Generic Host integration | IWF.TeleFlow.Framework.Hosting |
Optional IHostedService adapter для запуска настроенного TeleFlow application через Microsoft.Extensions.Hosting |
| Project Fluent localization | IWF.TeleFlow.Framework.I18n.Fluent |
Optional startup-loaded Fluent catalogs, scoped Telegram locale resolution, безопасное HTML/MarkdownV2 formatting и explicit-locale formatting для background jobs |
| Сценарий | Package reference | Когда подключать напрямую |
|---|---|---|
| Framework runtime без bundled transport | IWF.TeleFlow.Framework |
Только если ты делаешь custom framework update source или transport package |
| Framework primitives | IWF.TeleFlow.Framework.Core |
В обычных bot projects почти никогда. Storage и framework packages подтягивают его транзитивно |
| Direct client runtime boundary | IWF.TeleFlow.Telegram.Client |
Только если намеренно нужен явный lower-level client package вместо owner package IWF.TeleFlow.Telegram |
| Generated Telegram schema | IWF.TeleFlow.Telegram.Schema |
Только если намеренно работаешь с generated Telegram DTOs и method models без client/framework runtime |
| Handler attributes | IWF.TeleFlow.Annotations |
Обычно подтягивается framework packages. Подключай напрямую только для advanced compile-only сценариев |
| Raw long polling без handlers | IWF.TeleFlow.Telegram.LongPolling |
Когда нужны getUpdates и acknowledged update streaming поверх raw Telegram Update values |
| Raw ASP.NET Core webhooks без handlers | IWF.TeleFlow.Telegram.Webhooks |
Когда нужны ASP.NET Core endpoint helpers поверх raw Telegram Update values |
| Localization engine boundary | IWF.TeleFlow.Framework.I18n |
Когда нужен localization adapter не на Fluent. Обычное Fluent-приложение получает пакет транзитивно |
TeleFlow сейчас опубликован как public alpha. Используй --prerelease с dotnet add package или фиксируй конкретную alpha version в project file.
Рекомендуемая alpha-установка для маленького long polling bot:
dotnet add package IWF.TeleFlow.Framework.LongPolling --prerelease
dotnet add package IWF.TeleFlow.Generators --prerelease
dotnet add package IWF.TeleFlow.Storage.Memory --prereleaseGeneric Host integration добавляй только если приложение является worker service или ASP.NET Core host:
dotnet add package IWF.TeleFlow.Framework.Hosting --prereleaseFluent localization подключай только когда боту нужны переведённые user-facing messages:
dotnet add package IWF.TeleFlow.Framework.I18n.Fluent --prereleaseСтруктура ресурсов, locale resolution, безопасный formatting и background services описаны в гайде по Fluent localization.
Для handler-based long polling bot:
<PackageReference Include="IWF.TeleFlow.Framework.LongPolling" Version="..." />
<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />
<PackageReference Include="IWF.TeleFlow.Storage.Memory" Version="..." />Для worker-service style приложения добавь hosting:
<PackageReference Include="IWF.TeleFlow.Framework.Hosting" Version="..." />using Microsoft.Extensions.Hosting;
using TeleFlow.Framework.Hosting;
using TeleFlow.Storage.Memory;
using TeleFlow.Telegram;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddMemoryStateStorage();
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddLongPolling();
builder.Services.AddTeleFlowHostedService();
await builder.Build().RunAsync();Для более маленького console-style long polling bot без Generic Host:
<PackageReference Include="IWF.TeleFlow.Framework.LongPolling" Version="..." />
<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />
<PackageReference Include="IWF.TeleFlow.Storage.Memory" Version="..." />using TeleFlow.Framework.Application;
using TeleFlow.Storage.Memory;
using TeleFlow.Telegram;
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();Для handler-based webhook bot:
<PackageReference Include="IWF.TeleFlow.Framework.Webhooks" Version="..." />
<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />using TeleFlow.Telegram;
using TeleFlow.Telegram.Webhooks;
builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddWebhook(options => options.Path = "/telegram");
app.MapTelegramWebhook();Для прямого доступа к Bot API:
<PackageReference Include="IWF.TeleFlow.Telegram" Version="..." />using Microsoft.Extensions.DependencyInjection;
using TeleFlow.Telegram;
services.AddTelegramClient(options => options.Token = token);
var bot = provider.GetRequiredService<ITelegramClient>();
var me = await bot.GetMeAsync();Используй package IWF.TeleFlow.Generators, когда приложение вызывает:
services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);Этот API ожидает generated metadata в целевой assembly. Если metadata нет, startup падает с понятной ошибкой. Silent fallback на reflection не происходит.
Explicit direct registration не требует generator:
services.AddTelegramHandler<StartHandler>();
services.AddTelegramModule<AdminModule>();Direct registration регистрирует только указанный type. Он строит metadata для
этого type на startup и не сканирует containing assembly. AddTelegramModule<T>()
использует generated metadata, когда она доступна, а затем fallback на direct
metadata только для указанного module type.
Reflection assembly registration объявлен deprecated и будет удалён до 1.0:
services.AddTelegramHandlersFromAssemblyReflection(typeof(Program).Assembly);Не используй его в новых проектах. Используй generated assembly registration, либо регистрируй handlers/modules явно, если список должен быть ручным.
Используй package IWF.TeleFlow.Telegram, когда приложению нужно только вызывать Telegram Bot API methods без handlers, dispatcher, filters, state, long polling или webhooks.
<PackageReference Include="IWF.TeleFlow.Telegram" Version="..." />IWF.TeleFlow.Telegram.Client нужен только если хочется явно указать owner package name:
<PackageReference Include="IWF.TeleFlow.Telegram.Client" Version="..." />Оба пакета используют обычный namespace:
using TeleFlow.Telegram;Raw transport packages нужны, когда ты хочешь получать Telegram Update values напрямую и не хочешь handler framework.
Raw long polling:
<PackageReference Include="IWF.TeleFlow.Telegram.LongPolling" Version="..." />Raw webhooks:
<PackageReference Include="IWF.TeleFlow.Telegram.Webhooks" Version="..." />Raw long polling использует Telegram allowed_updates string values. Framework long polling использует TelegramAllowedUpdates и handler metadata для выбора update types.
Package IWF.TeleFlow.Storage.Memory подходит для local development, examples и process-local bots:
using TeleFlow.Storage.Memory;
services.AddMemoryStateStorage();Он регистрирует:
IStateStoreIStateDataStoreIStateDataSerializerIStateHistoryStore- state middleware
Для production deployment с несколькими процессами, рестартами или внешними workers заменяй storage contracts своей реализацией.
Runtime-пакеты сейчас target net10.0. Package IWF.TeleFlow.Generators target netstandard2.0, потому что analyzer/generator packages запускаются внутри C# compiler.