devsoftxela-libraryDsx 1.2.95

devsoftxelalibrary

Descripción

Librería completa para el desarrollo de sistemas en DevSoftXela. Incluye extensiones para generación de documentos PDF con iText7, validación de documentos guatemaltecos (CUI), manipulación de strings y utilerías comunes.

Requisitos

• .NET 10
• C# 14.0
• iText7 (versión 8.x o superior)
• Humanizer (para conversión de números a letras)

Instalación

Actualizaciones

Última versión (v1.3.0)

• ✅ Nuevo: Soporte completo para análisis y validación del Código Único de Identificación (CUI) de Guatemala
• ✅ Nuevo: Extensión AnalizarCui() para strings con validación automática
• ✅ Mejora: Catálogos centralizados de departamentos y municipios de Guatemala
• ✅ Se agregó soporte para celdas previas al encabezado en dsxGenerateTable mediante el parámetro opcional preHeaderCell
• ✅ Optimización de caché de imágenes para mejorar el rendimiento en documentos PDF con múltiples imágenes

V1.2.41

• Se actualizó el servicio SaveAsync para validar DataAnnotations en las entidades

V1.2.26

• Se cambió la clase DTE para uso de fechas: FechaHoraEmision y FechaHoraCertificacion con DateTimeOffset

Versiones anteriores

• Se integró la funcionalidad para manejo de nombres completos
• Se corrigió problema al no haber definida una ruta para la exportación automática de interfaces de TypeScript a Angular

Extensiones de String

La librería incluye extensiones útiles para el manejo de cadenas (strings) en C#, ubicadas en el namespace dsxlibrary.core.Extensions.

ToTitleCaseEs

Convierte una cadena a formato de título en español, capitalizando la primera letra de cada palabra y asegurando que las letras restantes sean minúsculas.

Características:

• Manejo inteligente de artículos y preposiciones en español
• Soporte para caracteres especiales y acentuados
• No altera cadenas que ya están en formato de título

Sintaxis:

Ejemplos:

AnalizarCui

Analiza y valida un Código Único de Identificación (CUI) de Guatemala, extrayendo información detallada sobre el departamento y municipio de emisión.

Características:

• ✅ Validación de formato (13 dígitos numéricos)
• ✅ Validación del dígito verificador usando el algoritmo oficial del RENAP
• ✅ Extracción automática del código de departamento y municipio
• ✅ Resolución de nombres de departamento y municipio usando catálogos centralizados
• ✅ Formateo del CUI en partes legibles
• ✅ Conversión del CUI a texto en español

Sintaxis:

Propiedades de CuiResultado:

Ejemplos:

Ejemplo 1: CUI válido

using dsxlibrary.core.Extensions;

string cuiValido = "1622322330901";
var resultadoValido = cuiValido.AnalizarCui();

Console.WriteLine($"CUI Válido: {resultadoValido.EsValido}");
Console.WriteLine($"Departamento: {resultadoValido.NombreDepartamento}");
Console.WriteLine($"Municipio: {resultadoValido.NombreMunicipio}");
Console.WriteLine($"CUI en letras: {resultadoValido.CuiEnLetras}");

Ejemplo 2: CUI inválido

using dsxlibrary.core.Extensions;

string cuiInvalido = "162232233090X";
var resultadoInvalido = cuiInvalido.AnalizarCui();

Console.WriteLine($"CUI Válido: {resultadoInvalido.EsValido}");
Console.WriteLine($"Error: {resultadoInvalido.Error}");

Notas importantes:

• El CUI debe tener exactamente 13 dígitos numéricos
• Los espacios en blanco al inicio y final se eliminan automáticamente
• Si el departamento o municipio no se encuentra en los catálogos, los nombres serán null
• La conversión a letras utiliza la cultura española de Guatemala (es-GT)

Extensiones para iText7

La librería incluye una suite completa de extensiones para facilitar la generación de documentos PDF con iText7, ubicadas en el namespace dsxlibrary.core.Extensions.

Métodos Disponibles

dsxParrafoPerzonalizado

Crea párrafos personalizados con estilos configurables.

Parámetros:

• text (string): Texto del párrafo
• fontId (int, opcional): ID de fuente (0: Normal, 1: Negrita, 2: Itálica) - Por defecto: 0
• fontSize (int, opcional): Tamaño de fuente en puntos - Por defecto: 12
• marginTop (float, opcional): Margen superior en puntos - Por defecto: 2
• marginBottom (float, opcional): Margen inferior en puntos - Por defecto: 5

Ejemplo:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("ejemplo.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

document.Add(new Paragraph("Título del documento").SetFontSize(20).SetBold());
document.Add(new Paragraph("Este es un párrafo de ejemplo que utiliza iText7 para ser generado en un documento PDF."))
        .dsxParrafoPerzonalizado(1, 12, 2, 5);

document.Close();

dsxCreateCell

Crea celdas de tabla con estilos personalizables avanzados.

Parámetros:

• text (string): Texto de la celda
• fontId (int, opcional): ID de fuente - Por defecto: 0
• alignId (int, opcional): Alineación (0: Izquierda, 1: Centro, 2: Derecha, 3: Justificado) - Por defecto: 0
• fontSize (float, opcional: Tamaño de fuente - Por defecto: 8f
• textColor (Color?, opcional): Color del texto - Por defecto: null (negro)
• backgroundColor (Color?, opcional): Color de fondo - Por defecto: null (transparente)
• borderId (int, opcional): Estilo de borde (0: Sólido, 1: Sin borde, 2: Punteado, 3: Rayado, 4: Doble) - Por defecto: 0
• verticalAlignment (VerticalAlignment, opcional): Alineación vertical - Por defecto: MIDDLE
• colspan (int, opcional): Columnas a abarcar - Por defecto: 1
• rowspan (int, opcional): Filas a abarcar - Por defecto: 1
• padding (float, opcional): Padding interno de la celda - Por defecto: 0f

Ejemplo:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("tabla_ejemplo.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

Table tabla = new Table(UnitValue.CreatePercentArray(new float[] { 1, 2, 1 }))
        .UseAllAvailableWidth()
        .SetFontSize(8);

tabla.AddHeaderCell("Encabezado 1".dsxCreateCell(1, 2, 0, 12, null, null, 1, 1, 2, 5));
tabla.AddHeaderCell("Encabezado 2".dsxCreateCell(1, 2, 0, 12, null, null, 1, 1, 2, 5));
tabla.AddHeaderCell("Encabezado 3".dsxCreateCell(1, 2, 0, 12, null, null, 1, 1, 2, 5));

tabla.AddCell("Celda 1.1".dsxCreateCell(0, 0, 0, 10, null, null, 1, 1, 5, 2));
tabla.AddCell("Celda 1.2".dsxCreateCell(0, 0, 0, 10, null, null, 1, 1, 5, 2));
tabla.AddCell("Celda 2.1".dsxCreateCell(0, 0, 0, 10, null, null, 1, 1, 5, 2));
tabla.AddCell("Celda 2.2".dsxCreateCell(0, 0, 0, 10, null, null, 1, 1, 5, 2));

document.Add(tabla);

document.Close();

dsxGenerateTable

Genera tablas completas con encabezados, datos y estilos configurables. Soporta celdas previas al encabezado para títulos o subtítulos.

Parámetros:

• headers (List<string>?): Lista de encabezados de columnas (nullable)
• data (List<TableCellData>): Lista de objetos TableCellData con los datos
• columnWidths (float[]): Anchos de columna en porcentaje
• tableWidthPercentage (float): Ancho de la tabla en porcentaje
• preHeaderCell (TableCellData?, opcional): Celda opcional antes del encabezado - Por defecto: null
• headerPadding (float, opcional): Padding de los encabezados en puntos - Por defecto: 0f
• cellPadding (float, opcional): Padding de las celdas en puntos - Por defecto: 0f

Ejemplo - Tabla con encabezados:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("tabla_con_encabezado.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

List<string> headers = new List<string> { "Nombre", "Edad", "Ciudad" };
List<TableCellData> data = new List<TableCellData>
{
    new TableCellData { Cells = new List<string> { "Juan Perez", "25", "Guatemala" } },
    new TableCellData { Cells = new List<string> { "Maria Lopez", "30", "Quetzaltenango" } },
    new TableCellData { Cells = new List<string> { "Carlos Ruiz", "28", "Escuintla" } }
};
float[] columnWidths = new float[] { 2, 1, 2 };
float tableWidthPercentage = 100;

document.Add(new Paragraph("Reporte de Usuarios").SetFontSize(20).SetBold());
document.Add(headers.dsxGenerateTable(data, columnWidths, tableWidthPercentage));

document.Close();

Ejemplo - Tabla sin encabezados:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("tabla_sin_encabezado.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

List<TableCellData> data = new List<TableCellData>
{
    new TableCellData { Cells = new List<string> { "Juan Perez", "25", "Guatemala" } },
    new TableCellData { Cells = new List<string> { "Maria Lopez", "30", "Quetzaltenango" } },
    new TableCellData { Cells = new List<string> { "Carlos Ruiz", "28", "Escuintla" } }
};
float[] columnWidths = new float[] { 2, 1, 2 };
float tableWidthPercentage = 100;

document.Add(new Paragraph("Reporte de Usuarios sin Encabezado").SetFontSize(20).SetBold());
document.Add(data.dsxGenerateTable(columnWidths, tableWidthPercentage));

document.Close();

dsxAddImageWithAutoScale

Inserta imágenes en el PDF con posicionamiento y tamaño personalizados. Las imágenes se almacenan en caché para optimizar el rendimiento.

Parámetros:

• imagePath (string): Ruta del archivo de imagen
• width (float): Ancho de la imagen
• height (float): Altura de la imagen
• x (float): Coordenada X de posición
• y (float): Coordenada Y de posición
• autoScale (bool, opcional): Ajuste automático de escala - Por defecto: true

Ejemplo:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("archivo_con_imagen.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

document.Add(new Paragraph("Ejemplo de Inserción de Imagen").SetFontSize(20).SetBold());
document.Add(new AreaBreak(AreaBreakType.NEXT_PAGE));

string rutaImagen = "C:\\ruta\\a\\tu-imagen.jpg";
document.Add(new Image(rutaImagen).dsxAddImageWithAutoScale(200, 100, 50, 700));

document.Close();

dsxAddBackgroundImage

Agrega una imagen de fondo a una página del PDF con escalado automático al tamaño de la página.

Parámetros:

• canvas (PdfCanvas): Canvas de la página
• imagePath (string): Ruta de la imagen de fondo
• pdfDocument (PdfDocument): Documento PDF

Ejemplo:

using dsxlibrary.core.Extensions;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

PdfWriter writer = new PdfWriter("archivo_con_imagen_fondo.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);

document.Add(new Paragraph("Ejemplo de Imagen de Fondo").SetFontSize(20).SetBold());
document.Add(new AreaBreak(AreaBreakType.NEXT_PAGE));

string rutaImagenFondo = "C:\\ruta\\a\\tu-imagen-fondo.jpg";
PdfCanvas canvas = new PdfCanvas(pdf.AddNewPage());
canvas.dsxAddBackgroundImage(rutaImagenFondo, pdf);

document.Add(new Paragraph("Contenido sobre imagen de fondo.")
            .SetFixedPosition(50, 750, 500)
            .SetFontSize(12)
            .SetFontColor(DeviceColor.BLACK));

document.Close();

Modelo TableCellData

La clase TableCellData permite definir propiedades detalladas para cada celda de la tabla.

Propiedades: | Propiedad | Tipo | Descripción | |-----------|------|-------------| | Text | string | Texto de la celda | | FontId | int | ID de fuente (0: Normal, 1: Negrita, 2: Itálica) | | Alignment | TextAlignment | Alineación horizontal | | FontSize | float | Tamaño de fuente | | TextColor | Color? | Color del texto | | BackgroundColor | Color? | Color de fondo | | BorderId | int | Estilo de borde (0: Sólido, 1: Sin borde, 2: Punteado, 3: Rayado, 4: Doble) | | VerticalAlignment | VerticalAlignment | Alineación vertical | | ColSpan | int | Columnas a abarcar | | RowSpan | int | Filas a abarcar |

Helpers para iText7

HeaderEventHandler

Helper para agregar encabezados personalizados a documentos PDF.

Características:

• Encabezado por defecto: "Report Service - timestamp: dd/MMM/yyyy HH:mm"
• Texto personalizable manteniendo el timestamp
• Color gris y centrado en la parte superior

Ejemplo:

using iText.Kernel.Events;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

public class HeaderEventHandler : IEventHandler
{
    public void HandleEvent(EventData eventData)
    {
        var document = eventData.GetDocument();
        var pdfDocument = document.GetPdfDocument();

        // Agregar encabezado
        var header = new Paragraph("Reporte generado por DevSoftXela")
                        .SetFontSize(10)
                        .SetHeight(20)
                        .SetTextAlignment(TextAlignment.CENTER)
                        .SetMargin(0);

        // Timestamp
        var timestamp = DateTime.Now.ToString("dd/MMM/yyyy HH:mm");
        header.Add($"\n{timestamp}").SetFontColor(ColorConstants.GRAY);

        // Posicionar en el header
        var canvas = new PdfCanvas(pdfDocument.GetPage(eventData.GetPageNumber()));
        canvas.SaveState()
              .SetLineWidth(1)
              .MoveTo(36, 806)
              .LineTo(559, 806)
              .Stroke();
        canvas.RestoreState();

        document.Add(header);
    }
}

FooterEventHandler

Helper para agregar pie de página con numeración a documentos PDF.

Características:

• Etiqueta por defecto: "Página X de Y"
• Etiqueta personalizable (ej: "Page", "Pág.", "BOLETA", etc.)
• Color gris y centrado en la parte inferior
• Utiliza placeholder para mostrar correctamente el total de páginas

Ejemplo:

using iText.Kernel.Events;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;

public class FooterEventHandler : IEventHandler
{
    public void HandleEvent(EventData eventData)
    {
        var document = eventData.GetDocument();
        var pdfDocument = document.GetPdfDocument();

        // Obtener el número total de páginas
        int totalPages = pdfDocument.GetNumberOfPages();

        // Crear pie de página
        var footer = new Paragraph($"Página {eventData.GetPageNumber()} de {totalPages}")
                        .SetFontSize(10)
                        .SetTextAlignment(TextAlignment.CENTER)
                        .SetMargin(0)
                        .SetFontColor(ColorConstants.GRAY);

        // Posicionar en el pie de página
        var canvas = new PdfCanvas(pdfDocument.GetPage(eventData.GetPageNumber()));
        canvas.SaveState()
              .SetLineWidth(1)
              .MoveTo(36, 50)
              .LineTo(559, 50)
              .Stroke();
        canvas.RestoreState();

        document.Add(footer);
    }
}

Validación

CuiValidator

Clase estática para validación del Código Único de Identificación (CUI) de Guatemala.

Métodos:

Repositorio

GitHub - devsoftxela-libraryCSharp

Licencia

Este proyecto está bajo licencia privada de DevSoftXela.

Soporte

Para reportar problemas o solicitar nuevas características, por favor crear un issue en el repositorio de GitHub.

Última actualización: Enero 2026