Asterisk.Core.Manager 1.0.0

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.Logging y uso intensivo de LoggerMessageAttribute para 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:

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:

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.