TelegramUpdater 1.4.0-preview.5.3

.NET 6.0
This is a prerelease version of TelegramUpdater.
dotnet add package TelegramUpdater --version 1.4.0-preview.5.3
NuGet\Install-Package TelegramUpdater -Version 1.4.0-preview.5.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TelegramUpdater" Version="1.4.0-preview.5.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add TelegramUpdater --version 1.4.0-preview.5.3
#r "nuget: TelegramUpdater, 1.4.0-preview.5.3"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install TelegramUpdater as a Cake Addin
#addin nuget:?package=TelegramUpdater&version=1.4.0-preview.5.3&prerelease

// Install TelegramUpdater as a Cake Tool
#tool nuget:?package=TelegramUpdater&version=1.4.0-preview.5.3&prerelease

TelegramUpdater (Preview)

This project aims creating telegram bots in a simplest and more straight way with DRY. ( TelegramUpdater aims .NET 6 and above. )

The package ( should ) handles following:

  1. Getting updates from telegram ( Customizable )
  2. Ensures updates are processed in parallel.
  3. Ensures updates are processed sequential pre each user.
  4. Ensures a limited count of updates are processed in parallel. ( This count is specified as MaxDegreeOfParallelism, this ensures that parallel running tasks should not be more than MaxDegreeOfParallelism. )
  5. Queuing updates per each user and allows you to semi manage them.
  6. Handle updates based on created handlers and filters.
  7. Handle exceptions occurred while handling updates.
  8. Applies DI ( Dependency Injection ) inside scoped update Handlers where an IServiceProvider is available.
  9. Enable waiting for other updates while handling an update.
  10. Handle overlapping handlers.
  11. Some extension methods and properties ( especially in scoped handlers ) to make faster to develop.
  12. Handle some low level staff like handling commands, deep-links and etc.
  13. (Recently) Helps you keep state of a user in a simplest way.

Getting Started

Let's get started with this package and learn how to implement some of above features.

Installation

The package is available inside Nuget.

TelegramUpdater uses Telegram.Bot: .NET Client for Telegram Bot API package as an C# wrapper over Telegram bot api.

Setup

Assume you have an empty console application. Put following inside Program.cs.

using TelegramUpdater;

// Initialize a new instance of Updater using your bot token
var updater = new Updater("<BOT_TOKEN>");

updater.AutoCollectScopedHandlers();
updater.AddDefaultExceptionHandler();

await updater.StartAsync();

Let's explain above code.

  1. Initialize Updater

    To do this you need a Telegram bot token. You can create a bot and get it's token from @BotFather.

    Then replace you own token with <BOT_TOKEN>.

  2. Add you update handlers

    While you can add the update handlers manually using following methods:

    • updater.AddSingletonUpdateHandler()
    • updater.AddScopedUpdaterHandler()

    But it's better to let's updater fetch them automatically for some reasons:

    1. You won't miss a handler in case you forgot to add it.
    2. You will have all your handler in one place and their right place. ...

    NOTE:

    • By default, updater will look for handler inside UpdaterHandlers namespace followed by updater name.

      Eg: UpdateHandler/Messages for message handlers.

    • This method looks only for ScopedUpdateHandler.

  3. Add exception handler

    Method updater.AddDefaultExceptionHandler() will add a default ExceptionHandler that handles all exceptions occurred while handling updates.

  4. Start the updater using a default UpdateWriter.

    UpdateWriter is a class that manages receiving updates from Telegram and writing them to the updater.

    You can create your own writer by inheriting from UpdateWriterAbs, then use await updater.StartAsync<MyUpdateWriter>()

Now, if you run the app, you will see some logs and nothing else. Since you should add some update handlers yet.

Create update handlers

Let's create a command handler for /start.

  1. Since we are using AutoCollectScopedHandlers, you should create a folder named UpdateHandler ( you can change this naming ) and another folder named Messages inside it.

  2. Inside UpdateHandler/Messages create a file name StartCommand.cs.

    Inside StartCommand.cs should be like this:

    namespace MyApp.UpdateHandlers.Messages;
    
    internal class StartCommand
    {
    
    }
    
  3. Convert your class to an Scoped message handler

    Your class should inherit from MessageHandler ( from TelegramUpdater.UpdateHandlers.Scoped.ReadyToUse namespace )

    using Telegram.Bot.Types;
    using TelegramUpdater.UpdateContainer;
    using TelegramUpdater.UpdateHandlers.Scoped.ReadyToUse;
    
    namespace YouKnowIKnowYou.UpdateHandlers.Messages;
    
    internal class StartCommand : MessageHandler
    {
        protected override Task HandleAsync(IContainer<Message> cntr)
        {
            throw new NotImplementedException();
        }
    }
    
  4. Our implementation to handle the update goes inside HandleAsync method.

    For now let's just send a message to the user.

    protected override async Task HandleAsync(IContainer<Message> _)
    {
        await ResponseAsync("Started from TelegramUpdater");
    }
    
  5. Add a filter to look for /start commands only.

    For scoped update handlers, we use FilterAttributes to apply filters.

    using Telegram.Bot.Types;
    using TelegramUpdater.FilterAttributes.Attributes;
    using TelegramUpdater.UpdateContainer;
    using TelegramUpdater.UpdateHandlers.Scoped.ReadyToUse;
    
    namespace YouKnowIKnowYou.UpdateHandlers.Messages;
    
    [Command(command: "start"), Private]
    internal class StartCommand : MessageHandler
    {
        protected override async Task HandleAsync(IContainer<Message> _)
        {
            await ResponseAsync("Started from TelegramUpdater");
        }
    }
    

    This is how a real scoped update handler look like.

Now if you run the app and send /start to the bot, you'll have a response.

Product Versions
.NET net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on TelegramUpdater:

Package Downloads
TelegramUpdater.Hosting

Hosting extension package for TelegramUpdater

TelegramUpdater.FillMyForm

This is an extension package for TelegramUpdater to help you fill a form in a blink of an eye.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.4.0-preview.5.3 84 4/28/2022
1.4.0-preview.5.2 73 4/10/2022
1.4.0-preview.4.9 65 4/4/2022
1.4.0-preview.4.4 70 4/3/2022
1.4.0-preview.4.1 67 4/1/2022
1.4.0-preview.3.3 76 3/14/2022
1.4.0-preview.2.3 64 3/10/2022
1.4.0-preview.2.2 66 3/8/2022
1.4.0-preview.1.4 86 3/7/2022

Updated to Telegram.Bot 18.0.0-alpha2, use polling by default.