Biblioteca que define las clases principales de orquestación, conexión, estado y parsing para la biblioteca Asterisk Manager Interface (AMI).
Get Started
$ dotnet add package Asterisk.Core.ManagerReadme
Asterisk.Core.Manager
Una librería resiliente, tipada y de alto rendimiento para la comunicación con el Asterisk Manager Interface (AMI) en entornos .NET.
Asterisk.Core.Manager proporciona una abstracción limpia sobre el protocolo AMI de bajo nivel, centrándose en la inyección de dependencias (Microsoft.Extensions.Logging) y la programación orientada a eventos para manejar la conectividad, las acciones y los mensajes asíncronos.
Características Principales
- Conexión Resiliente: Manejo robusto de la conectividad TCP con políticas de reintento y reconexión automática tras la pérdida de la red, asegurando la continuidad de la sesión AMI.
- Eventos Fuertemente Tipados: Despacho automático de mensajes asíncronos AMI (ej.
Hangup,Newchannel) a event handlers C# específicos, eliminando la necesidad de parsear mensajes crudos. - Acciones AMI: Soporte para el envío de acciones AMI con gestión de timeout y mapeo de respuestas mediante
ActionID. - Logging Estructurado: Integración total con la interfaz
Microsoft.Extensions.Loggingy uso intensivo deLoggerMessageAttributepara garantizar trazas de alto rendimiento, bajo overhead y estructuradas (JSON), facilitando la monitorización con herramientas como Serilog, Prometheus o ELK/Loki.
Arquitectura y Dependencias
Este paquete es la capa central y depende de los siguientes paquetes que definen las estructuras de datos básicas y el comportamiento del protocolo:
| Paquete | Propósito | Uso en Manager |
|---|---|---|
Asterisk.Core.Actions | Define todas las clases de acciones AMI que se envían al servidor (ej. LoginAction, LogoffAction). | Utilizado por ManagerAction para serializar las peticiones. |
Asterisk.Core.Events | Define todas las clases de eventos AMI que se reciben del servidor (ej. HangupEventArgs, NewchannelEventArgs). | Utilizado por ManagerEvent para el despacho tipado. |
Microsoft.Extensions.Logging | Proporciona la infraestructura de logging y el uso de ILogger y LoggerMessageAttribute. | Es el núcleo de la trazabilidad de alto rendimiento. |
Instalación
El paquete se distribuye a través de NuGet (asumido):
dotnet add package Asterisk.Core.Manager
Uso Rápido (Quick Start)
Para empezar, necesitarás inyectar un ILoggerFactory (típicamente a través del host de .NET Core) y utilizar el constructor de AsteriskManager.
1. Inicialización y Conexión
using Microsoft.Extensions.Logging;
using Asterisk.Core.Manager;
using Asterisk.Core.Events; // Para los EventArgs específicos
using System.Net;
// 1. Obtener la fábrica de loggers (ej. a través de inyección de dependencias)
ILoggerFactory loggerFactory = host.Services.GetRequiredService<ILoggerFactory>();
// 2. Inicializar el Manager
var manager = new AsteriskManager(address: ipAddress, port: 5038, loggerFactory);
// 3. Suscribirse a eventos de conexión y eventos AMI específicos
manager.ConnectionStarted += (s, e) =>
{
Console.WriteLine("Conexión TCP establecida. Iniciando autenticación...");
};
manager.HangupReceived += OnHangupEvent;
manager.NewchannelReceived += OnNewChannelEvent;
// 4. Iniciar la conexión
manager.Login("mi_usuario_ami", "mi_clave_secreta");
// manager.SendAction(new OriginateAction(...));
2. Manejo de Eventos Tipados
Los eventos AMI se reciben como objetos de datos tipados:
private static void OnHangupEvent(object? sender, HangupEventArgs e)
{
// Acceso a propiedades sin parsing de string
Console.WriteLine($"Canal colgado: {e.Channel}");
Console.WriteLine($"Motivo del colgado: {e.CauseText}");
}
private static void OnNewChannelEvent(object? sender, NewchannelEventArgs e)
{
Console.WriteLine($"Nuevo canal '{e.Channel}' creado por: {e.CallerIDNum}");
}
Configuración de Logging Estructurado
La librería utiliza ManagerTrace y ILogger para registrar todo el flujo de conexión, envío de acciones y procesamiento de eventos.
Para ver las trazas de bajo nivel, asegúrate de que tu configuración de appsettings.json o tu proveedor de logging (ej. Console, File, Serilog) incluya los niveles Information, Warning, y Error para los loggers principales:
{
"Logging": {
"LogLevel": {
"Default": "Warning",
"Asterisk.Core.Manager.Connection": "Information",
"Asterisk.Core.Manager.Action": "Debug",
"Asterisk.Core.Manager.Event": "Debug"
}
}
}
Los mensajes críticos de PING, fallo de envío de acciones y errores de parsing se registran con su EventId (ej. 513 para PingLoopError) y su nivel de severidad correcto (Critical o Error), facilitando la creación de alertas en sistemas de monitoreo.
Arquitectura de Clases
La librería se compone de las siguientes capas:
| Clase | Rol | Descripción |
|---|---|---|
AsteriskManager | Fachada (Motor Principal) | Clase de usuario principal. Orquesta la conexión, autenticación y despacho de eventos. Hereda de ManagerEvent. |
ManagerConnection | Capa de Conectividad | Gestiona el socket TCP, la reconexión y los bucles de lectura/escritura de bajo nivel. |
ManagerAction | Capa de Acciones | Se encarga de la serialización, envío y mapeo síncrono de respuestas AMI (ActionID). |
ManagerEvent | Capa de Despacho | Clase base abstracta que define los eventos abstractos (EventReceived, ResponseReceived) y contiene la lógica de despacho tipado de eventos AMI. |
ManagerState | Capa de Estado | Contiene el estado compartido de la sesión (conexión, streams, diccionarios de acciones pendientes, tokens de cancelación y las trazas (ManagerTrace)). |
Contribución
¡Las contribuciones son bienvenidas! Si deseas añadir nuevas clases de respuesta o mejorar la documentación, por favor, abre un issue o envía una pull request a nuestro repositorio.
Licencia
Distribuido bajo la licencia MIT.