Installing PolyBot: NuGet, Config, and DI Wiring

This page covers everything you need to get PolyBot running in a new or existing project: the NuGet install, project requirements, PolyBotOptions configuration, and the minimal service-registration calls.

Install the NuGet package

PolyBot is distributed as a single NuGet package. Install it with the .NET CLI:

dotnet add package PolyBot

Or add it to your .csproj directly:

<PackageReference Include="PolyBot" Version="1.0.0" />

PolyBot.SourceGenerators is bundled inside the PolyBot package as an analyzer. There is no separate PolyBot.SourceGenerators package to install. The source generator becomes active automatically as soon as you reference PolyBot.

Project requirements

Configure `PolyBotOptions`

PolyBotOptions is the single configuration class for PolyBot. It covers the bot token, API endpoint, polling behaviour, and webhook settings.

Option 1 — constructor injection (simplest)

Pass a PolyBotOptions instance directly to PolyBotClient:

PolyBotClient client = new PolyBotClient(new PolyBotOptions()
{
    BotToken = "YOUR_BOT_TOKEN",
    DropPendingUpdates = true,
});
client.Services.AddPolyBotRouter();
await client.RunPollingAsync();

Constructor values take precedence over any configuration section.

Option 2 — configuration section

PolyBotClient.Configuration is a ConfigurationManager. Load any standard Microsoft.Extensions.Configuration source and put your values under the "PolyBot" key:

PolyBotClient client = new PolyBotClient();
client.Configuration.AddJsonFile("appsettings.json");
client.Services.AddPolyBotRouter();
await client.RunPollingAsync();

{
  "PolyBot": {
    "BotToken": "YOUR_BOT_TOKEN",
    "DropPendingUpdates": true,
    "AllowedUpdates": "Message, CallbackQuery"
  }
}

Option 3 — register manually (Generic Host / webhook)

When you manage the IServiceCollection yourself (e.g. with Generic Host or ASP.NET Core), register a PolyBotOptions singleton before calling AddPolyBotDefaults():

services.AddSingleton(new PolyBotOptions() { BotToken = token });
services.AddPolyBotDefaults();
services.AddPolyBotRouter();

`PolyBotOptions` reference

Property	Type	Default	Description
`BotToken`	`string?`	`null`	Required for polling. Not required in test mode.
`BotUsername`	`string?`	`null`	Back-filled from `GetMe` at startup; used for `@botsuffix` command verification.
`BaseUrl`	`string?`	`null`	Custom Bot API server URL.
`UseTestEnvironment`	`bool`	`false`	Route requests to Telegram’s test environment.
`PollingLimit`	`int?`	`null`	Maximum updates per `GetUpdates` batch (Telegram allows 1–100).
`PollingOffset`	`int?`	`null`	Initial update offset; leave unset to consume pending updates.
`AllowedUpdates`	`UpdateType[]?`	`null`	Update types to receive; `null` receives all types.
`DropPendingUpdates`	`bool`	`false`	Drop accumulated updates when polling starts or the webhook is set.
`WebhookUrl`	`string?`	`null`	Full HTTPS URL Telegram delivers updates to.
`WebhookSecretToken`	`string?`	`null`	Verified from the `X-Telegram-Bot-Api-Secret-Token` header.
`WebhookMaxConnections`	`int`	`40`	Max simultaneous HTTPS connections to the webhook (1–100).
`DeleteWebhookOnStop`	`bool`	`true`	Call `DeleteWebhook` on graceful shutdown.

Service wiring

Minimal wiring with `PolyBotClient`

PolyBotClient calls AddPolyBotDefaults() internally, so the minimum setup is:

PolyBotClient client = new PolyBotClient(new PolyBotOptions() { BotToken = token });
client.Services.AddPolyBotRouter(); // generated — appears after first build
await client.RunPollingAsync();

Minimal wiring with a plain `IServiceCollection`

When you supply your own service collection (Generic Host, ASP.NET Core, or unit tests), call both methods:

// 1. Register options (required before AddPolyBotDefaults)
services.AddSingleton(new PolyBotOptions() { BotToken = token });

// 2. Register PolyBot core services (state machine, update awaiter, etc.)
services.AddPolyBotDefaults();

// 3. Register the generated router as IUpdateHandler
services.AddPolyBotRouter();

AddPolyBotDefaults() registers the following with try-add semantics (your registrations win if added first):

Service	Default implementation
`IStateStorage`	`MemoryStateStorage`
`IStateMachine`	`StateMachine`
`IUpdateContextAccessor`	`UpdateContextAccessor`
`IUpdateAwaiter`	`UpdateAwaiter`

To use a custom state storage backend (required for multi-instance bots), register your IStateStorage before calling AddPolyBotDefaults() or AddPolyBotRouter(). The try-add semantics mean the first registration wins.

Generic Host integration

When Microsoft.Extensions.Hosting.Abstractions is referenced, the generator emits a PolyBotPollingHostedService. Register it with:

services.AddPolyBotHostedPolling(receiver =>
{
    receiver.DropPendingUpdates = true;
});

ASP.NET Core webhook integration

When any Microsoft.AspNetCore.* package is referenced, the generator emits webhook infrastructure:

// In Program.cs / Startup.cs
builder.Services.AddPolyBotWebhook();

// ...

app.MapPolyBotWebhook("/bot");

AddPolyBotWebhook() registers a hosted service that calls SetWebhook on startup and DeleteWebhook on shutdown (when DeleteWebhookOnStop is true). The mapped endpoint validates the X-Telegram-Bot-Api-Secret-Token header, deserializes the update, routes it through BotRouter, and returns 200 OK.

Namespace collision warning

Do not declare a type named PolyBotExtensions in the PolyBot namespace anywhere in your project. The source generator emits a static class PolyBotExtensions in namespace PolyBot containing AddPolyBotRouter(). A hand-written class with the same name in the same namespace will cause a compile error.

Verify the installation

After adding the package and building once, confirm the generator ran correctly:

dotnet build

A successful build with at least one [XxxHandler]-decorated method produces no CUR0xx errors. You can also inspect the generated files under obj/ in your project directory if you want to see the emitted router code.

AddPolyBotRouter() is emitted by the source generator and will not exist until after the first successful build. New projects may show an IDE “method not found” squiggle until you run dotnet build once.

Get Started

Core Concepts

Features

Hosting & Deployment

Testing

Installing PolyBot: NuGet, Config, and DI Wiring

Install the NuGet package

Project requirements

Configure `PolyBotOptions`

Option 1 — constructor injection (simplest)

Option 2 — configuration section

Option 3 — register manually (Generic Host / webhook)

`PolyBotOptions` reference

Service wiring

Minimal wiring with `PolyBotClient`

Minimal wiring with a plain `IServiceCollection`

Generic Host integration

ASP.NET Core webhook integration

Namespace collision warning

Verify the installation

​Install the NuGet package

​Project requirements

​Configure PolyBotOptions

​Option 1 — constructor injection (simplest)

​Option 2 — configuration section

​Option 3 — register manually (Generic Host / webhook)

​PolyBotOptions reference

​Service wiring

​Minimal wiring with PolyBotClient

​Minimal wiring with a plain IServiceCollection

​Generic Host integration

​ASP.NET Core webhook integration

​Namespace collision warning

​Verify the installation

Install the NuGet package

Project requirements

Configure `PolyBotOptions`

Option 1 — constructor injection (simplest)

Option 2 — configuration section

Option 3 — register manually (Generic Host / webhook)

`PolyBotOptions` reference

Service wiring

Minimal wiring with `PolyBotClient`

Minimal wiring with a plain `IServiceCollection`

Generic Host integration

ASP.NET Core webhook integration

Namespace collision warning

Verify the installation