Verbara.Sdk.Hosting
2.10.0
See the version list below for details.
dotnet add package Verbara.Sdk.Hosting --version 2.10.0
NuGet\Install-Package Verbara.Sdk.Hosting -Version 2.10.0
<PackageReference Include="Verbara.Sdk.Hosting" Version="2.10.0" />
<PackageVersion Include="Verbara.Sdk.Hosting" Version="2.10.0" />
<PackageReference Include="Verbara.Sdk.Hosting" />
paket add Verbara.Sdk.Hosting --version 2.10.0
#r "nuget: Verbara.Sdk.Hosting, 2.10.0"
#:package Verbara.Sdk.Hosting@2.10.0
#addin nuget:?package=Verbara.Sdk.Hosting&version=2.10.0
#tool nuget:?package=Verbara.Sdk.Hosting&version=2.10.0
Verbara.Sdk.Hosting
The recommended entry point to the Verbara.Sdk family — single dotnet add brings in AMI, AGI, ARI, Live, Activities, Sessions, and Config plus a Microsoft.Extensions.DependencyInjection extension that wires everything into your IHost with one call. Native AOT, zero reflection, MIT licensed.
What it does
AddVerbara(IConfiguration | Action<VerbaraOptions>)— registersIAmiConnection,IAriClient,IAgiServer, the Live API (VerbaraServer),IActivityRegistry,ISessionEngine, and the supporting hosted services. Source-generator-validated.AddVerbaraAri(Action<AriClientOptions>)— registersIAriClientand nothing else, for a host that needs only ARI (below).VerbaraOptions— strongly-typed configuration model with[OptionsValidator]source-generated validation (no runtime reflection). Bind directly fromappsettings.jsonor configure inline.- Hosted lifecycle —
IHostedServiceimplementations connect AMI onStartAsync, drain onStopAsync. AGI server, ARI WebSocket, andVerbaraServer(Live aggregate) follow the same pattern. - Health checks —
AmiHealthCheck(ami, the same state table aslive),LiveHealthCheck(live) andAgiHealthCheck(agi) auto-registered,AriHealthCheck(ari, the same state table asami, ARI'sFaultedasUnhealthy) with anArisection;AddVerbaraMultiServeraddsVerbaraServerPoolHealthCheck(verbara-pool); all with no tags unless you name them (VerbaraHealthCheckOptions.Tags). Expose them at a diagnostics endpoint such as/health; point Kubernetes probes at endpoints filtered by tag, and never put an SDK check on the tag your readiness probe reads (Health endpoint). - Multi-server support — register multiple
VerbaraServerinstances viaVerbaraServerPoolfor federated deployments.
This is a meta-package: it does not contain its own runtime types. It transitively pulls in Verbara.Sdk, Verbara.Sdk.Ami, Verbara.Sdk.Agi, Verbara.Sdk.Ari, Verbara.Sdk.Live, Verbara.Sdk.Activities, Verbara.Sdk.Sessions, and Verbara.Sdk.Config. Add Voice AI / Push / OpenTelemetry packages on top as needed.
Install
dotnet add package Verbara.Sdk.Hosting
Quick start — bind from config
using Verbara.Sdk.Hosting;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddVerbara(builder.Configuration);
var host = builder.Build();
await host.RunAsync();
{
"Asterisk": {
"Ami": { "Hostname": "pbx.example.com", "Username": "admin", "Password": "secret" },
"Ari": { "BaseUrl": "http://pbx.example.com:8088", "Username": "admin", "Password": "secret", "Application": "my-app" },
"AgiPort": 4573,
"HealthCheckTags": ["voice"]
}
}
Asterisk:Ami and Asterisk:Ari take every option of AmiConnectionOptions and AriClientOptions, by name ("MaxReconnectAttempts": 10, "ReconnectInitialDelay": "00:00:01"); values are read with the invariant culture, and one that cannot be read as the option's type makes AddVerbara throw an InvalidOperationException naming its key. A value of the right type that the options do not accept (with AutoReconnect on, a reconnect delay or multiplier the backoff cannot use, for example; see the high-load tuning guide) fails the host's start with an OptionsValidationException naming the option. The Ari section is optional: without it no ARI client is registered. AgiPort is the FastAGI server's port. HealthCheckTags names the tags every SDK health check carries (Health endpoint); without it they carry none.
Quick start — inline configure
builder.Services.AddVerbara(options =>
{
options.Ami.Hostname = "192.168.1.100";
options.Ami.Username = "admin";
options.Ami.Password = "secret";
// Optional: tune reconnect / heartbeat
options.Ami.ReconnectInitialDelay = TimeSpan.FromSeconds(1);
options.Ami.HeartbeatInterval = TimeSpan.FromSeconds(30);
});
builder.Services.Configure<VerbaraHealthCheckOptions>(o => o.Tags.Add("voice"));
After host.RunAsync(), resolve services in your code:
var ami = host.Services.GetRequiredService<IAmiConnection>();
var server = host.Services.GetRequiredService<VerbaraServer>(); // Live API aggregate
var ari = host.Services.GetRequiredService<IAriClient>();
ARI-only hosts
AddVerbara always registers the AMI connection, and its hosted service dials AMI when the host starts: a failed dial
stops the host. A host that needs only ARI registers it with AddVerbaraAri instead:
builder.Services.AddVerbaraAri(options =>
{
options.BaseUrl = "http://pbx.example.com:8088";
options.Username = "admin";
options.Password = "secret";
options.Application = "my-app";
options.EventsEnabled = false;
});
It registers what AddVerbara registers for ARI, and no more: the client, its options (every value set in the callback
is delivered, and validated when the host starts), the ari health check, the hosted service that connects the client,
and the audio servers when ConfigureAudioServer is set. No AMI connection, AGI server or Live server is registered, and
no ami, agi or live check. With EventsEnabled = false the client opens no events WebSocket, so the host starts and
stops with no Asterisk reachable; with events on, the client dials at start and a failed dial stops the host.
- The
aricheck asks Asterisk on each run, so on a host with no reachable Asterisk it readsUnhealthy. Keep it, like every SDK check, off the endpoint your readiness probe reads (see Health endpoint). - The ARI client is registered once. Calling
AddVerbaraAritwice, or on a collection whereAddVerbaraset itsArioptions, throws anInvalidOperationExceptionnaming both methods.AddVerbarawith noArioptions andAddVerbaraArion the same collection is fine. - The session engine (
AddVerbaraSessions*) andAddVerbaraMultiServerread the Live server, which needs AMI: they needAddVerbara, notAddVerbaraAri.
Session options from configuration
Each sessions registration accepts the host configuration: AddVerbaraSessions, AddVerbaraSessionsBuilder,
AddVerbaraSessionsMultiServer, and AddVerbaraSessionsMultiServerBuilder. Each reads every settable
SessionOptions property from the Sessions section; the builder variants still return the builder for
UseRedis(...) or UsePostgres(...).
builder.Services.AddVerbaraSessions(builder.Configuration, options =>
{
// Runs after binding; override the configured retention for this host.
options.CompletedRetention = TimeSpan.FromMinutes(1);
});
{
"Sessions": {
"ReconciliationInterval": "00:00:10",
"DialingTimeout": "00:01:00",
"CompletedRetention": "00:05:00",
"InboundContextPatterns": ["from-carrier"],
"OutboundContextPatterns": ["to-carrier"]
}
}
For a pool, pass the configuration to AddVerbaraSessionsMultiServer(builder.Configuration) after
AddVerbaraMultiServer(). A configured context list replaces its default list, including when the provider exposes
an empty list key. An absent list keeps its own default, and an absent Sessions section keeps all defaults.
Values use invariant culture; a malformed value throws an InvalidOperationException naming its configuration key
when options are resolved. The existing options validator runs on startup, just as with inline configuration.
"ReconciliationInterval": "-00:00:00.001" switches the sweep off without starting a timer. The overloads use
source-generated binding and support Native AOT. Existing calls with a configure delegate or a literal null keep
using the existing overloads.
Health endpoint
The package auto-registers IHealthCheck for AMI/ARI/AGI (AddVerbaraAri: for ARI only). Wire to ASP.NET Core:
builder.Services.AddHealthChecks();
// ...
app.MapHealthChecks("/health"); // diagnostics: every check, the SDK's included — no probe reads this endpoint
The ami check reads the AMI connection's state: Connected is Healthy, Reconnecting, Connecting or not yet connected is Degraded (the connection may come back, or nobody has connected it yet), and Disconnecting or Disconnected is Unhealthy; its data carries the state as amiState. It uses the same table as live, so the two never disagree on a state (migration guide). The ari check reads the ARI client's state with the same table, ARI's Faulted as Unhealthy; its data carries the state as ariState (migration guide).
A client with EventsEnabled = false reads RestOnly, and its ari check sends one GET /ari/asterisk/ping per run
instead: an answer reads Healthy, anything else Unhealthy. To keep it out of a host endpoint that is not a probe,
filter that endpoint by name (a readiness probe reads none of the SDK's checks: see below):
app.MapHealthChecks("/health/pbx", new HealthCheckOptions { Predicate = check => check.Name != "ari" });
The live check reads the AMI connection before the state it holds: Connected reports on the state as before, Reconnecting, Connecting or not yet connected is Degraded (the state is not being updated, but the connection may come back), and Disconnecting or Disconnected is Unhealthy; its data carries the connection's state as amiState.
Every SDK check (ami, live, agi, ari, sessions, verbara-pool) is registered with no tags unless you name them
in VerbaraHealthCheckOptions.Tags — builder.Services.Configure<VerbaraHealthCheckOptions>(o => o.Tags.Add("voice")),
before or after the SDK's registrations — or, with AddVerbara(IConfiguration), in the array Asterisk:HealthCheckTags.
Never name the tag your readiness probe reads: an Asterisk outage would take the pod out of service. To tag one check, or
keep one off the host-wide tag, see the PostConfigure recipe under Multi-server.
Multi-server (federation)
Register multi-server support at DI time, then resolve the pool after Build() and add servers at runtime:
builder.Services.AddVerbaraMultiServer();
var host = builder.Build();
var pool = host.Services.GetRequiredService<VerbaraServerPool>();
await pool.AddServerAsync("pbx-east", new AmiConnectionOptions
{
Hostname = "pbx-east",
Port = 5038,
Username = "admin",
Password = "secret"
});
await pool.AddServerAsync("pbx-west", new AmiConnectionOptions
{
Hostname = "pbx-west",
Port = 5038,
Username = "admin",
Password = "secret"
});
AddVerbaraMultiServer also registers a health check named verbara-pool, with no tags unless you name them (VerbaraHealthCheckOptions.Tags), once however often it is called. It reads every server's AMI connection when it runs: Healthy when every server is connected or the pool holds none, Unhealthy when every server's connection has ended (Disconnecting or Disconnected), and Degraded otherwise; its data maps each server id to its connection's state. A pool whose servers are all connected reads Degraded while any server's last Status was refused (VerbaraServer.LastStatusRefusal), and its data then adds one status-refused entry naming each such server and Asterisk's message; every refusal also counts on live.status.refused. An unfiltered /health endpoint includes it, so point a liveness probe at an endpoint filtered by tag (migration guide).
To tag one SDK check, or to keep one off the host-wide tags, edit its registration in a PostConfigure:
// Before or after AddVerbaraMultiServer(): PostConfigure runs after every Configure, so the SDK's registration is there.
builder.Services.PostConfigure<HealthCheckServiceOptions>(o =>
{
foreach (var r in o.Registrations)
if (r.Name == "verbara-pool") r.Tags.Add("voice"); // your tag, your endpoint
});
r.Tags.Remove("voice") in the same PostConfigure keeps that check off a tag VerbaraHealthCheckOptions.Tags names. Write
it as PostConfigure, not Configure: a Configure<HealthCheckServiceOptions> registered before an SDK registration
(AddVerbara, AddVerbaraMultiServer() or a sessions registration) sees none of that registration's checks, because each
of them is added from a Configure too. Never put an SDK check on the tag your readiness probe reads.
For call sessions, AddVerbaraSessionsMultiServer registers the session engine and a reconciliation sweep for every server of the pool. It attaches no server: attach each one under its id in the pool, admit the calls it already carries, and detach it when it leaves. Never attach from inside a subscriber of the session engine's Events: that throws InvalidOperationException.
builder.Services.AddVerbaraMultiServer();
builder.Services.AddVerbaraSessionsMultiServer();
// ...
var server = await pool.AddServerAsync("pbx-east", options);
var sessions = host.Services.GetRequiredService<ICallSessionManager>();
sessions.AttachToServer(server, "pbx-east");
await sessions.AdmitExistingCalls("pbx-east");
AdmitExistingCalls opens a session for each call the server's channel table holds that no session holds, so calls already up when the server is attached are followed too. The session engine indexes calls per server id: find a call with GetByChannelId(serverId, uniqueId), GetByLinkedId(serverId, linkedId) or GetByBridgeId(serverId, bridgeId). The lookups that name no server return null when two servers hold the id.
On each SessionOptions.ReconciliationInterval tick (30 s by default) the sweep verifies, for each server, the held calls attached under its id against one Status of that server, and ends a call whose hangup was lost as a reload ends it; one server's failure never stops the others. o => o.ReconciliationInterval = Timeout.InfiniteTimeSpan in the configure delegate switches it off. Give every Asterisk of the pool its own systemname, so no two servers issue the same channel ids: calls of two servers are kept apart without it, but a lookup that names no server, or a consumer keyed by linkedid alone, cannot tell them apart. See the migration guide and, for what 2.10.0 changes, the 2.10.0 migration guide.
See Examples/MultiServerExample/ for a full federation walkthrough.
Native AOT
AddVerbara and AddVerbaraAri are fully AOT-safe: options validation comes from a source generator, no Type.GetType lookups, no Activator.CreateInstance. 0 trim warnings.
License
MIT. Part of the Verbara.Sdk project.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Configuration (>= 10.0.0)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Options (>= 10.0.0)
- System.Reactive (>= 7.0.0)
- Verbara.Sdk (>= 2.10.0)
- Verbara.Sdk.Activities (>= 2.10.0)
- Verbara.Sdk.Agi (>= 2.10.0)
- Verbara.Sdk.Ami (>= 2.10.0)
- Verbara.Sdk.Ari (>= 2.10.0)
- Verbara.Sdk.Config (>= 2.10.0)
- Verbara.Sdk.Live (>= 2.10.0)
- Verbara.Sdk.Sessions (>= 2.10.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Verbara.Sdk.Hosting:
| Package | Downloads |
|---|---|
|
Verbara.Sdk.OpenTelemetry
Verbara.Sdk.OpenTelemetry - batteries-included OpenTelemetry wiring for Verbara.Sdk. One-line AddVerbaraOpenTelemetry(...) enrolls every ActivitySource and Meter from VerbaraTelemetry and provides convenience helpers for Console, OTLP, and Prometheus exporters. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.10.1 | 1,397 | 11/17/2026 |
| 2.10.0 | 291 | 11/16/2026 |
| 2.9.0 | 2,810 | 10/29/2026 |
| 2.8.0 | 2,913 | 10/9/2026 |
| 2.7.0 | 752 | 10/3/2026 |
| 2.6.1 | 480 | 9/30/2026 |
| 2.6.0 | 714 | 9/24/2026 |
| 2.5.3 | 632 | 9/13/2026 |
| 2.5.2 | 281 | 9/13/2026 |
| 2.5.1 | 291 | 9/12/2026 |
| 2.5.0 | 363 | 8/25/2026 |
| 2.4.0 | 1,943 | 7/27/2026 |
| 2.3.2 | 653 | 7/20/2026 |
| 2.3.1 | 306 | 7/14/2026 |
| 2.3.0 | 369 | 7/6/2026 |
| 2.2.1 | 888 | 5/23/2026 |
| 2.2.0 | 161 | 5/20/2026 |
| 2.1.2 | 168 | 5/8/2026 |
| 2.1.1 | 133 | 5/7/2026 |
| 2.1.0 | 3,390 | 5/7/2026 |