FrigaT/BotPages
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 25 Wiki Activity

Новый api отправки сообщений

Browse Source
This commit is contained in:
FrigaT
2025-12-24 08:43:46 +03:00
parent 833d8c80d9
commit 37cb6599ba
19 changed files with 478 additions and 338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
BotPages.Core/Abstractions/AdapterOptionsBag.cs Normal file
View File

@@ -0,0 +1,44 @@
namespace BotPages.Core.Abstractions;
/// <summary>
/// Êîíòåéíåð äëÿ àäàïòåð-ñïåöèôè÷íûõ îïöèé, ïîçâîëÿþùèé õðàíèòü ïàðàìåòðû äëÿ íåñêîëüêèõ àäàïòåðîâ.
/// Èñïîëüçóåòñÿ âíóòðè `SendRequest.AdapterOptions`.
/// </summary>
public sealed class AdapterOptionsBag
{
private readonly Dictionary<string, object?> _map = new(StringComparer.OrdinalIgnoreCase);
/// <summary>
/// Óñòàíîâèòü îïöèè äëÿ àäàïòåðà.
/// </summary>
public void Set<T>(string adapterKey, T options)
{
if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
_map[adapterKey] = options;
}
/// <summary>
/// Ïîïðîáîâàòü ïîëó÷èòü îïöèè äëÿ àäàïòåðà.
/// </summary>
public bool TryGet<T>(string adapterKey, out T? options)
{
if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
if (_map.TryGetValue(adapterKey, out var o) && o is T t)
{
options = t;
return true;
}
options = default;
return false;
}
/// <summary>
/// Ïîëó÷èòü îïöèè èëè âåðíóòü null.
/// </summary>
public T? GetOrDefault<T>(string adapterKey)
{
TryGet(adapterKey, out T? v);
return v;
}
}

22
BotPages.Core/Abstractions/IMessengerAdapter.cs
View File

@@ -15,27 +15,9 @@ public interface IMessengerAdapter
Capabilities Capabilities { get; }
/// <summary>
/// Отправить текстовое сообщение в чат.
/// Универсальный метод отправки с использованием общего описания запроса.
/// </summary>
Task<string?> SendTextAsync(string chatId,
string text,
MessageFormat format = MessageFormat.Plain,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
string? messageId = null,
CancellationToken ct = default
);
/// <summary>
/// Отправить файл в чат.
/// </summary>
Task SendFileAsync(string chatId,
FileDescriptor file,
string? caption = null,
MessageFormat? captionFormat = null,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
CancellationToken ct = default);
Task<string?> SendAsync(SendRequest request, CancellationToken ct = default);
/// <summary>
/// Создать билдер альбома для отправки медиагруппы.

43
BotPages.Core/Abstractions/SendRequest.cs Normal file
View File

@@ -0,0 +1,43 @@
using BotPages.Core.Messaging;
namespace BotPages.Core.Abstractions;
/// <summary>
/// Óíèâåðñàëüíàÿ ñòðóêòóðà çàïðîñà íà îòïðàâêó ñîîáùåíèÿ/ôàéëà, èñïîëüçóåìàÿ àäàïòåðàìè.
/// Ïîìåùåíà â Core ÷òîáû áûòü äîñòóïíîé äëÿ âñåõ àäàïòåðîâ.
/// </summary>
public sealed class SendRequest
{
/// <summary>Èäåíòèôèêàòîð ÷àòà/ñåññèè â ìåññåíäæåðå.</summary>
public required string ChatId { get; init; }
/// <summary>Òåêñò ñîîáùåíèÿ (åñëè îòïðàâëÿåòñÿ òåêñò).</summary>
public string? Text { get; init; }
/// <summary>Ôîðìàò òåêñòà (HTML/Markdown/Plain).</summary>
public MessageFormat? TextFormat { get; init; }
/// <summary>Inline êíîïêè (ñòðîêè êíîïîê).</summary>
public IEnumerable<IEnumerable<InlineButton>>? Inline { get; init; }
/// <summary>Reply êëàâèàòóðà (ñòðîêè êíîïîê).</summary>
public IEnumerable<IEnumerable<ReplyButton>>? Reply { get; init; }
/// <summary>Id ðåäàêòèðóåìîãî ñîîáùåíèÿ (åñëè ðåäàêòèðóåì).</summary>
public string? MessageId { get; init; }
/// <summary>Ôàéë äëÿ îòïðàâêè (åñëè îòïðàâëÿåòñÿ ôàéë).</summary>
public FileDescriptor? File { get; init; }
/// <summary>Ïîäïèñü äëÿ ôàéëà.</summary>
public string? Caption { get; init; }
/// <summary>Ôîðìàò ïîäïèñè/ïîäïèñè äëÿ ôàéëà.</summary>
public MessageFormat? CaptionFormat { get; init; }
/// <summary>
/// Êîíòåéíåð àäàïòåð-ñïåöèôè÷íûõ îïöèé.
/// Ñîäåðæèò èìåíà/êëþ÷è àäàïòåðîâ è ñîîòâåòñòâóþùèå îáúåêòû îïöèé.
/// </summary>
public AdapterOptionsBag? AdapterOptions { get; init; }
}

66
BotPages.Core/Context/PageContextAdapterExtensions.cs
View File

@@ -4,12 +4,19 @@ using BotPages.Core.Messaging;
namespace BotPages.Core;
/// <summary>
/// Расширения <see cref="PageContext"/> для работы с <see cref="IMessengerAdapter"/>
/// Расширения <see cref="PageContext"/> для работы с адаптером.
/// Упрощают создание универсального `SendRequest`.
/// </summary>
public static class PageContextAdapterExtensions
{
/// <summary>
/// Отправить текстовое сообщение.
/// Отправить универсальный запрос через привязанный адаптер.
/// </summary>
public static Task<string?> SendAsync(this PageContext ctx, SendRequest request, CancellationToken ct = default)
=> ctx.Adapter.SendAsync(request, ct);
/// <summary>
/// Удобная оболочка: отправить текстовое сообщение.
/// </summary>
public static Task<string?> SendTextAsync(this PageContext ctx,
string text,
@@ -17,25 +24,56 @@ public static class PageContextAdapterExtensions
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
string? messageId = null,
object? adapterOptions = null,
CancellationToken ct = default)
=> ctx.Adapter.SendTextAsync(ctx.Update.Chat.Id, text, format, inline, reply, messageId, ct);
{
var bag = adapterOptions switch
{
null => null,
AdapterOptionsBag b => b,
_ => throw new ArgumentException("adapterOptions must be an AdapterOptionsBag or null. Use MessageBuilder extensions to set adapter options.", nameof(adapterOptions))
};
return ctx.SendAsync(new SendRequest
{
ChatId = ctx.Update.Chat.Id,
Text = text,
TextFormat = format,
Inline = inline,
Reply = reply,
MessageId = messageId,
AdapterOptions = bag
}, ct);
}
/// <summary>
/// Отправить файл.
/// Удобная оболочка: отправить файл.
/// </summary>
public static Task SendFileAsync(this PageContext ctx,
public static Task<string?> SendFileAsync(this PageContext ctx,
FileDescriptor file,
string? caption = null,
MessageFormat? captionFormat = null,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
CancellationToken ct = default
)
=> ctx.Adapter.SendFileAsync(chatId: ctx.Update.Chat.Id,
file: file,
caption: caption,
captionFormat: captionFormat,
inline: inline,
reply: reply,
ct: ct);
object? adapterOptions = null,
CancellationToken ct = default)
{
var bag = adapterOptions switch
{
null => null,
AdapterOptionsBag b => b,
_ => throw new ArgumentException("adapterOptions must be an AdapterOptionsBag or null. Use MessageBuilder extensions to set adapter options.", nameof(adapterOptions))
};
return ctx.SendAsync(new SendRequest
{
ChatId = ctx.Update.Chat.Id,
File = file,
Caption = caption,
CaptionFormat = captionFormat,
Inline = inline,
Reply = reply,
AdapterOptions = bag
}, ct);
}
}

32
BotPages.Core/Messaging/MessageBuilder.cs
View File

@@ -4,6 +4,7 @@ namespace BotPages.Core.Messaging;
/// <summary>
/// Fluent‑билдер для отправки сообщений (текст, кнопки, файлы, альбомы, прогресс).
/// Поддерживает указание адаптер-специфичных опций через `WithAdapterOption`.
/// </summary>
public sealed class MessageBuilder
{
@@ -16,10 +17,21 @@ public sealed class MessageBuilder
private readonly List<(FileDescriptor file, string? caption, MessageFormat? captionFormat)> _album = new();
private bool _disableReplyKeyboard;
private string? _editMessageId = null;
private AdapterOptionsBag? _adapterOptions = null;
/// <summary>Создать билдер сообщений.</summary>
public MessageBuilder(PageContext ctx) => _ctx = ctx;
/// <summary>
/// Установить опции для конкретного адаптера. Ключ адаптера определяется адаптером (напр., "telegram").
/// </summary>
public MessageBuilder WithAdapterOption<T>(string adapterKey, T options)
{
if (_adapterOptions is null) _adapterOptions = new AdapterOptionsBag();
_adapterOptions.Set(adapterKey, options);
return this;
}
/// <summary>Текст сообщения.</summary>
public MessageBuilder Text(string text, MessageFormat format = MessageFormat.Plain)
{
@@ -63,7 +75,7 @@ public sealed class MessageBuilder
return this;
}
/// <summary>Добавить строку inline‑кнопок.</summary>
/// <summary>Добавить строки inline‑кнопок.</summary>
public MessageBuilder Inline(IEnumerable<IEnumerable<InlineButton>> row)
{
_inline.AddRange(row.Select(t => t.ToList()).ToList());
@@ -73,7 +85,6 @@ public sealed class MessageBuilder
/// <summary>
/// Отключение Reply клавиатуры.
/// </summary>
/// <returns></returns>
public MessageBuilder DisableReply()
{
_disableReplyKeyboard = true;
@@ -96,7 +107,7 @@ public sealed class MessageBuilder
return this;
}
/// <summary>Добавить строку reply‑кнопок.</summary>
/// <summary>Добавить строки reply‑кнопок.</summary>
public MessageBuilder Reply(IEnumerable<IEnumerable<ReplyButton>> row)
{
_disableReplyKeyboard = false;
@@ -130,18 +141,16 @@ public sealed class MessageBuilder
// Текст
if (!string.IsNullOrWhiteSpace(_text))
{
messageId = await _ctx.SendTextAsync(_text, _format, _inline, reply, _editMessageId, ct);
messageId = await _ctx.SendTextAsync(_text, _format, _inline, reply, _editMessageId, _adapterOptions, ct);
}
// Файлы
foreach (var (file, caption, captionFormat) in _files)
await _ctx.SendFileAsync(file: file
, caption: caption
, captionFormat: captionFormat
, reply: reply
, inline: _inline
, ct: ct
);
{
var res = await _ctx.SendFileAsync(file, caption, captionFormat, _inline, reply, _adapterOptions, ct);
// сохранить первый возвращённый id сообщения
if (messageId is null && res is not null) messageId = res;
}
// Альбом
if (_album.Count > 0)
@@ -157,6 +166,7 @@ public sealed class MessageBuilder
_album.Clear();
_editMessageId = null;
_adapterOptions = null;
return messageId;
}

8
BotPages.Core/Middleware/ErrorHandlingMiddleware.cs
View File

@@ -27,8 +27,12 @@ public sealed class ErrorHandlingMiddleware : IPageMiddleware
{
_logger.Log(LogLevel.Critical, "Unhandled exception in middleware pipeline.", ex);
// Теперь можно напрямую использовать PageContext для ответа
await ctx.SendTextAsync("Произошла ошибка при обработке запроса. Попробуйте ещё раз.", ct: ct);
// Отправляем универсальный запрос с текстом об ошибке
await ctx.SendAsync(new SendRequest
{
ChatId = ctx.Update.Chat.Id,
Text = "Произошла ошибка при обработке запроса. Попробуйте ещё раз."
}, ct);
}
}
}

8
BotPages.Telegram/BotPagesAppExtension.cs
View File

@@ -15,8 +15,14 @@ public static class BotPagesAppExtension
/// <param name="messengerType"></param>
/// <returns></returns>
public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, string messengerType = "")
=> app.AddTelegramAdapter(token, null, messengerType);
/// <summary>
/// Добавление адаптера для телеграмм с опциями.
/// </summary>
public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, TelegramOptions? options, string messengerType = "")
{
var telegram = new TelegramAdapter(app.Logger, token);
var telegram = new TelegramAdapter(app.Logger, token, options);
if (!string.IsNullOrWhiteSpace(messengerType)) telegram.MessengerType = messengerType;

43
BotPages.Telegram/MessageBuilderExtensions.cs Normal file
View File

@@ -0,0 +1,43 @@
using BotPages.Core.Abstractions;
using BotPages.Core.Messaging;
namespace BotPages.Telegram;
/// <summary>
/// Ðàñøèðåíèÿ äëÿ `MessageBuilder` ñïåöèôè÷íûå äëÿ Telegram.
/// Ïîçâîëÿþò óäîáíî çàäàòü `TelegramOptions` äëÿ êîíêðåòíîãî ñîîáùåíèÿ
/// áåç èçìåíåíèÿ ñàìîãî áèëäåðà.
/// </summary>
public static class MessageBuilderExtensions
{
/// <summary>
/// Óñòàíîâèòü îïöèè Telegram äëÿ êîíêðåòíîãî ñîîáùåíèÿ (ïåðåîïðåäåëÿþò îïöèè àäàïòåðà).
/// </summary>
public static MessageBuilder WithTelegramOptions(this MessageBuilder builder, TelegramOptions options)
{
// Ensure bag exists
var bag = (builder as object) switch
{
MessageBuilder mb => GetAdapterBag(mb) ?? CreateAndSetAdapterBag(mb),
_ => null
};
bag?.Set("telegram", options);
return builder;
}
// Reflection helpers to access private adapterOptions field on MessageBuilder
private static AdapterOptionsBag? GetAdapterBag(MessageBuilder builder)
{
var fi = typeof(MessageBuilder).GetField("_adapterOptions", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
return fi?.GetValue(builder) as AdapterOptionsBag;
}
private static AdapterOptionsBag CreateAndSetAdapterBag(MessageBuilder builder)
{
var fi = typeof(MessageBuilder).GetField("_adapterOptions", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
var bag = new AdapterOptionsBag();
fi?.SetValue(builder, bag);
return bag;
}
}

330
BotPages.Telegram/TelegramAdapter.cs
View File

@@ -21,11 +21,12 @@ namespace BotPages.Telegram;
/// Адаптер для Telegram на базе Telegram.Bot.
/// Реализует отправку текста, кнопок, файлов, альбомов и прогресса.
/// </summary>
public sealed class TelegramAdapter : IMessangerAdapterSetup
public sealed class TelegramAdapter : IMessengerAdapterSetup
{
private readonly ILogger _logger;
private TelegramBotClient? _client;
private string _token;
private readonly TelegramOptions _options;
private static Capabilities _capabilities = new()
{
SupportsInlineButtons = true,
@@ -37,10 +38,11 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
};
/// <summary>Создать адаптер Telegram.</summary>
public TelegramAdapter(ILogger logger, string token)
public TelegramAdapter(ILogger logger, string token, TelegramOptions? options = null)
{
_logger = logger;
_token = token;
_options = options ?? new TelegramOptions();
}
/// <summary>
@@ -81,6 +83,7 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
cancellationToken: ct
);
await _client.SetMyCommands(commands.Where(t => t.Publish).Select(t => new BotCommand(t.Name, t.Description ?? t.Name.TrimStart('/'))), cancellationToken: ct);
var me = await _client.GetMe();
@@ -89,13 +92,11 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
return;
}
/// <inheritdoc />
public async Task<string?> SendTextAsync(string chatId, string text,
MessageFormat format = MessageFormat.Plain,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
string? messageId = null,
CancellationToken ct = default)
/// <summary>
/// Универсальный внутренний метод отправки — определяет, нужно ли отправлять текст или файл по параметрам.
/// Возвращает id сообщения (или null).
/// </summary>
public async Task<string?> SendAsync(SendRequest req, CancellationToken ct)
{
if (_client is null)
{
@@ -103,23 +104,29 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
return null;
}
// determine adapter-specific options (TelegramOptions) from bag or use adapter default
TelegramOptions telegramOptions = _options;
if (req.AdapterOptions is AdapterOptionsBag bag && bag.TryGet("telegram", out TelegramOptions? opt) && opt is not null)
{
telegramOptions = opt;
}
var disableNotification = !telegramOptions.NotifyOnSend;
// Build markup
InlineKeyboardMarkup? inlineMarkup = null;
ReplyMarkup? markup = null;
if (inline is not null && inline.Any())
if (req.Inline is not null && req.Inline.Any())
{
inlineMarkup = new InlineKeyboardMarkup(
inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
.ToArray()
req.Inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray()).ToArray()
);
}
else if (reply is not null)
else if (req.Reply is not null)
{
if (reply.Any())
if (req.Reply.Any())
{
markup = new ReplyKeyboardMarkup(
reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
)
markup = new ReplyKeyboardMarkup(req.Reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray())
{
ResizeKeyboard = true
};
@@ -130,180 +137,169 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
}
}
var parseMode = ParseMode.None;
switch (format)
// If there is a file — send file
if (req.File is not null)
{
case MessageFormat.Html:
{
var file = req.File;
// Получаем поток, если он задан
Stream? stream = null;
if (file.GetStreamAsync is not null)
{
stream = await file.GetStreamAsync(ct);
if (stream is not null) stream.Position = 0;
}
InputFile inputFile;
if (stream is not null && stream != Stream.Null)
{
inputFile = new InputFileStream(stream, file.Name);
}
else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
{
inputFile = new InputFileUrl(file.Id);
}
else
{
inputFile = new InputFileId(file.Id);
}
var parseMode = ParseMode.None;
switch (req.CaptionFormat)
{
case MessageFormat.Html:
parseMode = ParseMode.Html;
break;
}
case MessageFormat.Plain:
{
parseMode = ParseMode.None;
break;
}
case MessageFormat.Markdown:
{
case MessageFormat.Markdown:
parseMode = ParseMode.MarkdownV2;
break;
}
default:
{
_logger.Log(LogLevel.Warn, $"MessageFormat '{format}' not supported. Degraded to plain text.");
case MessageFormat.Plain:
case null:
parseMode = ParseMode.None;
break;
}
}
}
// Длина сообщения
if (text.Length > Capabilities.MaxMessageLength)
{
_logger.Log(LogLevel.Warn, $"Message too long ({text.Length}). Truncated to {Capabilities.MaxMessageLength}.");
text = text.Substring(0, Capabilities.MaxMessageLength);
}
if (!string.IsNullOrWhiteSpace(messageId))
{
await _client.EditMessageText(
messageId: int.Parse(messageId),
chatId: long.Parse(chatId),
text: text,
parseMode: parseMode,
replyMarkup: inlineMarkup,
cancellationToken: ct
);
return messageId;
}
else
{
if (inlineMarkup is not null) markup = inlineMarkup;
var message = await _client.SendMessage(
chatId: long.Parse(chatId),
text: text,
parseMode: parseMode,
replyMarkup: markup,
cancellationToken: ct
);
Message? sentMessage = req.File.Kind switch
{
FileKind.Photo => await _client.SendPhoto(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
FileKind.Video => await _client.SendVideo(long.Parse(req.ChatId), inputFile, caption: req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
FileKind.Audio => await _client.SendAudio(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
_ => await _client.SendDocument(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
};
return message.Id.ToString();
return sentMessage?.MessageId.ToString();
}
// Otherwise treat as text
if (!string.IsNullOrWhiteSpace(req.Text))
{
var format = req.TextFormat ?? MessageFormat.Plain;
var parseMode = ParseMode.None;
switch (format)
{
case MessageFormat.Html:
parseMode = ParseMode.Html;
break;
case MessageFormat.Markdown:
parseMode = ParseMode.MarkdownV2;
break;
case MessageFormat.Plain:
default:
parseMode = ParseMode.None;
break;
}
// Длина сообщения
var text = req.Text!;
if (text.Length > Capabilities.MaxMessageLength)
{
_logger.Log(LogLevel.Warn, $"Message too long ({text.Length}). Truncated to {Capabilities.MaxMessageLength}.");
text = text.Substring(0, Capabilities.MaxMessageLength);
}
if (!string.IsNullOrWhiteSpace(req.MessageId))
{
await _client.EditMessageText(
messageId: int.Parse(req.MessageId),
chatId: long.Parse(req.ChatId),
text: text,
parseMode: parseMode,
replyMarkup: inlineMarkup,
cancellationToken: ct
);
return req.MessageId;
}
else
{
if (inlineMarkup is not null) markup = inlineMarkup;
var message = await _client.SendMessage(
chatId: long.Parse(req.ChatId),
text: text,
parseMode: parseMode,
replyMarkup: markup,
disableNotification: disableNotification,
cancellationToken: ct
);
return message.MessageId.ToString();
}
}
return null;
}
/// <inheritdoc />
public async Task SendFileAsync(string chatId,
public Task<string?> SendTextAsync(string chatId, string text,
MessageFormat format = MessageFormat.Plain,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
string? messageId = null,
object? adapterOptions = null,
CancellationToken ct = default)
{
var req = new SendRequest
{
ChatId = chatId,
Text = text,
TextFormat = format,
Inline = inline,
Reply = reply,
MessageId = messageId,
AdapterOptions = adapterOptions as AdapterOptionsBag
};
return SendAsync(req, ct);
}
/// <inheritdoc />
public Task SendFileAsync(string chatId,
FileDescriptor file,
string? caption = null,
MessageFormat? captionFormat = null,
IEnumerable<IEnumerable<InlineButton>>? inline = null,
IEnumerable<IEnumerable<ReplyButton>>? reply = null,
object? adapterOptions = null,
CancellationToken ct = default
)
{
if (_client is null)
var req = new SendRequest
{
_logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
return;
}
ChatId = chatId,
File = file,
Caption = caption,
CaptionFormat = captionFormat,
Inline = inline,
Reply = reply,
AdapterOptions = adapterOptions as AdapterOptionsBag
};
// Получаем поток, если он задан
Stream? stream = null;
if (file.GetStreamAsync is not null)
{
stream = await file.GetStreamAsync(ct);
stream.Position = 0;
}
InputFile inputFile;
if (stream is not null && stream != Stream.Null)
{
inputFile = new InputFileStream(stream, file.Name);
}
else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
{
inputFile = new InputFileUrl(file.Id);
}
else
{
inputFile = new InputFileId(file.Id);
}
var parseMode = ParseMode.None;
switch (captionFormat)
{
case MessageFormat.Html:
{
parseMode = ParseMode.Html;
break;
}
case MessageFormat.Plain:
{
parseMode = ParseMode.None;
break;
}
case MessageFormat.Markdown:
{
parseMode = ParseMode.MarkdownV2;
break;
}
case null:
{
parseMode = ParseMode.None;
break;
}
default:
{
_logger.Log(LogLevel.Warn, $"MessageFormat '{captionFormat}' not supported. Degraded to plain text.");
break;
}
}
ReplyMarkup? markup = null;
if (inline is not null && inline.Any())
{
markup = new InlineKeyboardMarkup(
inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
.ToArray()
);
}
else if (reply is not null)
{
if (reply.Any())
{
markup = new ReplyKeyboardMarkup(
reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
)
{
ResizeKeyboard = true
};
}
else
{
markup = new ReplyKeyboardRemove();
}
}
// В зависимости от FileKind выбираем подходящий метод
switch (file.Kind)
{
case FileKind.Photo:
await _client.SendPhoto(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
break;
case FileKind.Video:
await _client.SendVideo(long.Parse(chatId), inputFile, caption: caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
break;
case FileKind.Audio:
await _client.SendAudio(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
break;
default:
await _client.SendDocument(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
break;
}
return SendAsync(req, ct);
}
/// <inheritdoc />

14
BotPages.Telegram/TelegramOptions.cs Normal file
View File

@@ -0,0 +1,14 @@
namespace BotPages.Telegram;
/// <summary>
/// Настройки адаптера Telegram, применяемые по умолчанию при отправке сообщений.
/// </summary>
public sealed class TelegramOptions
{
/// <summary>
/// Отправлять ли уведомление (sound) при отправке сообщения. По умолчанию true.
/// </summary>
public bool NotifyOnSend { get; set; } = true;
// В будущем можно добавить: default parse mode, disable web page preview и т.д.
}

17
Demo/Pages/DetailsPage.cs
View File

@@ -6,7 +6,6 @@ namespace Demo.Pages;
/// <summary>
/// Страница ввода деталей заявки.
/// Страница с параметрами и получением состояния.
/// </summary>
public sealed class DetailsPage : StatefullPage<string>
{
@@ -32,19 +31,14 @@ public sealed class DetailsPage : StatefullPage<string>
switch (payload)
{
case "next":
{
await SaveState(ctx, ct);
await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
break;
}
await SaveState(ctx, ct);
await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
break;
case "back":
{
await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
break;
}
await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
break;
}
;
}
public override async Task OnText(PageContext ctx, string text, CancellationToken ct)
@@ -61,7 +55,6 @@ public sealed class DetailsPage : StatefullPage<string>
string? title = "";
args?.TryGetValue("title", out title);
// Навигация на страницу по имени
await ctx.Navigation.GoToAsync<DetailsPage, string>(ctx, title ?? "", ct);
};
}

2
Demo/Pages/FileSendPage.cs
View File

@@ -15,7 +15,7 @@ public sealed class FileSendPage : SingletonPage
var demoFile = new FileDescriptor
{
Id = "", // не используется при отправке нового файла
Id = "",
Name = "demo.txt",
Extension = "txt",
Size = stream.Length,

10
Demo/Pages/FilesPage.cs
View File

@@ -6,7 +6,7 @@ namespace Demo.Pages;
/// <summary>
/// Страница загрузки файлов.
/// Обычная страница с полученим и сохранением состояния.
/// Обычная страница с получением и сохранением состояния.
/// </summary>
public sealed class FilesPage : SingletonPage
{
@@ -18,15 +18,17 @@ public sealed class FilesPage : SingletonPage
public override async Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct)
{
// Пересылаем каждый файл обратно с подтверждением
foreach (var file in files)
{
await ctx.SendFileAsync(file, $"Файл '{file.Name}' получен и отправлен обратно.", ct: ct);
await new MessageBuilder(ctx)
.File(file, $"Файл '{file.Name}' получен и отправлен обратно.")
.SendAsync(ct);
}
//Обращение через Storage
// Сохраняем данные в хранилище состояния
var request = await ctx.StateStorage.GetAsync<Models.Request>(ctx.SessionKey, "Request", ct);
request.FilesCount = files.Count;
//Обращение через Context
await ctx.SetStorageAsync("Request", request, ct);
await new MessageBuilder(ctx)

6
Demo/Pages/SubmitPage.cs
View File

@@ -10,9 +10,7 @@ public sealed class SubmitPage : SingletonPage
{
public override async Task OnEnter(PageContext ctx, CancellationToken ct)
{
var progress = new MessageBuilder(ctx);
var messageId = await progress
var messageId = await new MessageBuilder(ctx)
.Text("Отправка заявки\n7%")
.SendAsync(ct);
@@ -21,7 +19,7 @@ public sealed class SubmitPage : SingletonPage
{
i += 25;
Thread.Sleep(TimeSpan.FromMilliseconds(200));
await progress
await new MessageBuilder(ctx)
.Text($"Отправка заявки\n{i}%")
.EditMessage(messageId!)
.SendAsync(ct);

1
Demo/Pages/TitlePage.cs
View File

@@ -5,7 +5,6 @@ using BotPages.Core.Messaging;
namespace Demo.Pages;
/// <summary>
/// Страница ввода заголовка заявки.
/// Обычная страница вводом текста.
/// </summary>
public sealed class TitlePage : SingletonPage
{

13
Demo/Pages/WelcomePage.cs
View File

@@ -7,7 +7,6 @@ namespace Demo.Pages;
/// <summary>
/// Стартовая страница демо‑бота.
/// Обычная страница с кнопками
/// </summary>
[Route("Welcome")]
public sealed class WelcomePage : SingletonPage
@@ -31,19 +30,13 @@ public sealed class WelcomePage : SingletonPage
switch (button)
{
case WelcomePageButtons.CreateRequest:
{
return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
}
return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
case WelcomePageButtons.Help:
{
return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
}
return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
case WelcomePageButtons.SendFile:
{
return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
}
return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
}
return base.OnText(ctx, text, ct);

48
README.md
View File

@@ -1,6 +1,6 @@
# BotPages
BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с системой страниц (page‑based conversational framework).
BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с моделью страниц (page‑based conversational framework).
Цели проекта:
- Простая модель страниц и навигации.
@@ -11,7 +11,7 @@ BotPages — кроссплатформенный фреймворк для со
Структура репозитория
- `BotPages.Core` — ядро фреймворка: навигация, страницы, маршрутизация, реестр команд, middleware, абстракции адаптеров и хранилища состояния.
- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessangerAdapterSetup`/`IMessengerAdapter`).
- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessengerAdapter`).
- `Demo` — пример приложения с несколькими страницами и конфигурацией адаптера.
- `BotPages` — мета‑проект для упаковки библиотек.
- `docs/` — внутренняя документация проекта (Quickstart, API reference и т.д.).
@@ -51,14 +51,24 @@ export TELEGRAM_TOKEN="<token>" # Linux/macOS
dotnet run --project Demo
```
Основные концепции
Простой пример конфигурации
- `BotPagesApp` — точка конфигурации приложения: регистрация адаптеров, middleware, маршрутов и команд, запуск.
```csharp
var app = new BotPagesApp(stateStorage, logger)
.AddTelegramAdapter(token)
.AddDefaultPage<WelcomePage>()
.MapCommand<WelcomePage>('/start')
.AddMiddleware(new LoggingMiddleware(logger));
await app.Build(CancellationToken.None);
```
Ключевые концепции
- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, опции). Адаптеры реализуют `IMessengerAdapter.SendAsync(SendRequest)`.
- `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
- `NavigationService` — управление переходами между страницами и определение текущей страницы по сессии.
- `CommandsRegistry` — шаблоны команд вида `/cmd {arg} {opt?}` с поддержкой именованных и опциональных аргументов.
- `NavigationService` — управление переходами между страницами.
- `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
- `IMessangerAdapterSetup` / `IMessengerAdapter` — интерфейсы, позволяющие подключать новые мессенджеры.
Документация
@@ -67,30 +77,6 @@ dotnet run --project Demo
- `docs/API_REFERENCE.md` — краткий reference публичных API.
- `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.
XML‑документация генерируется при сборке (опция `GenerateDocumentationFile` в `.csproj`), её можно использовать для генерации HTML‑референса (docfx, MkDocs и т.п.).
Примеры использования
```csharp
var app = new BotPagesApp(stateStorage, logger)
.AddAdapter("telegram", new TelegramAdapterSetup(token))
.AddDefaultPage<WelcomePage>()
.MapCommand<WelcomePage>("/start")
.AddMiddleware(new LoggingMiddleware(logger));
await app.Build(CancellationToken.None);
```
Вклад и тестирование
- Принимам пулл‑реквесты. Описание PR должно содержать цель и краткое описание изменения.
- Следуйте единому стилю кода и включённым nullable-аннотациям.
Лицензия
Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.
Контакты
Автор: FrigaT
Репозиторий: https://git.frigat.duckdns.org/FrigaT/BotPages

63
docs/API_REFERENCE.md
View File

@@ -1,50 +1,39 @@
# API Reference (краткий)
# Справочник API
Документ перечисляет публичные API фреймворка и их назначение.
Ниже краткое описание публичных API проекта BotPages.
## BotPages.Core
### `BotPagesApp`
- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
- `AddTelegramAdapter(string token)` — регистрирует Telegram адаптер с заданным токеном.
- `AddAdapter(string messengerType, IMessengerAdapter adapter)` — регистрирует произвольный адаптер.
- `AddMiddleware(IPageMiddleware middleware)` — добавляет middleware в pipeline.
- `MapCommand<TPage>(string template)` — привязать команду к странице.
- `MapRoute<TPage>(string template)` — зарегистрировать маршрут.
- `AutoMapRoute()` — выполнить автопоиск Page?классов и зарегистрировать их маршруты.
- `Build(CancellationToken ct)` — подготовить и запустить приложение.
### Страницы
- `Page` — абстрактный базовый класс.
- `StatefulPage` — страница с сохранением состояния.
- `SingletonPage` — одноэкземплярная страница.
### `IMessengerAdapter`
- `Task<string?> SendAsync(SendRequest request, CancellationToken ct = default)` — универсальный метод отправки для всех адаптеров.
- `IAlbumBuilder CreateAlbumBuilder(PageContext ctx)` — создать билдер альбома (если поддерживается).
- `Task OnLeaveAsync(PageContext ctx, CancellationToken ct)` — вызывается при уходе со страницы.
### Навигация
- `NavigationService` — отвечает за определение текущей страницы и переходы.
- `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
- `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
### `SendRequest`
- `ChatId` — идентификатор чата.
- `Text`, `TextFormat` — текст и формат.
- `File`, `Caption`, `CaptionFormat` — файл и подпись.
- `Inline`, `Reply` — inline и reply клавиатуры.
- `MessageId` — id редактируемого сообщения.
- `AdapterOptions` — адаптер?специфичные опции (например `TelegramOptions`).
### Команды
- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
### Middleware
- `IPageMiddleware` — интерфейс middleware.
- `InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)`
### Абстракции адаптеров
- `IMessangerAdapterSetup` — настройка адаптера.
- `IMessengerAdapter` — экземпляр адаптера, реализующий `StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Command> commands, CancellationToken ct)`.
- `IMessengerAdapterFactory` — фабрика/реестр адаптеров (`MultiAdapterFactory` — реализация).
### Хранилище состояний
- `IStateStorage` — абстракция для сохранения состояния страниц между сессиями.
### `PageContext` расширения
- `SendAsync(SendRequest request, CancellationToken ct = default)` — отправить `SendRequest`.
- `SendTextAsync(...)`, `SendFileAsync(...)` — удобные оболочки, создающие `SendRequest`.
## BotPages.Telegram
- Реализация адаптера для Telegram на базе `Telegram.Bot`.
- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
- `TelegramAdapter` — реализация `IMessengerAdapter` для Telegram.
- `TelegramOptions` — настройки адаптера (например `NotifyOnSend`).
- `MessageBuilderExtensions.WithTelegramOptions` — расширение для установки `TelegramOptions` для конкретного сообщения.
# Генерация документации

44
docs/GETTING_STARTED.md
View File

@@ -1,28 +1,37 @@
# Быстрый старт — BotPages
# Быстрый старт с BotPages
Эта инструкция поможет запустить и протестировать проект локально.
Это руководство поможет быстро запустить demo?приложение с Telegram?адаптером.
Требования
- .NET 8 SDK
- Токен Telegram (если используете Telegram-адаптер)
- Токен Telegram?бота (для demo)
Сборка
```bash
dotnet build
```
Запуск демонстрации
1. Откройте проект `Demo`.
2. Внесите токен Telegram (если используется) в код инициализации адаптера или в переменные окружения проекта Demo.
3. Запустите:
Запуск demo
1. Установите переменную окружения `TELEGRAM_TOKEN`:
```bash
setx TELEGRAM_TOKEN "<token>" # Windows
export TELEGRAM_TOKEN="<token>" # Linux/macOS
```
2. Запустите demo:
```bash
dotnet run --project Demo
```
Пример конфигурации приложения
```csharp
var app = new BotPagesApp(stateStorage, logger)
.AddAdapter("telegram", new TelegramAdapterSetup("<token>"))
.AddTelegramAdapter(token)
.AddDefaultPage<WelcomePage>()
.MapCommand<WelcomePage>("/start")
.AddMiddleware(new LoggingMiddleware(logger));
@@ -30,18 +39,9 @@ var app = new BotPagesApp(stateStorage, logger)
await app.Build(CancellationToken.None);
```
Как написать страницу
- Наследуйте `StatefulPage` для страниц с пер-сессионным состоянием.
- Наследуйте `SingletonPage` для одноэкземплярных страниц.
- Переопределите `OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError` по необходимости.
- Для автоматического маппинга маршрутов используйте `AutoMapRoute()`.
Основные понятия
- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, адаптер?опции). Используйте `PageContext.SendAsync` для отправки.
- `Page` / `StatefulPage` / `SingletonPage` — модели страниц и их жизненный цикл.
- `IPageMiddleware` — middleware выполняется для каждого входящего обновления.
Тестирование команд
- Команды регистрируются в `BotPagesApp.MapCommand`.
- Шаблон команд поддерживает именованные и опциональные аргументы: `/cmd {a} {b?}`.
Подсказки
- Middleware выполняются в том порядке, в котором их добавляют в `BotPagesApp`.
- Команды имеют приоритет над обработкой страниц (если текст начинается с `/`).
Если требуется подробный справочник API — смотрите `docs/API_REFERENCE.md`.
Далее: см. `docs/API_REFERENCE.md` для описания публичных API.