Gesgocom.PlantillasCorreo 1.0.0

Gesgocom.PlantillasCorreo

Sustitución de variables en plantillas de correo por tipo y contexto, con un analizador de una sola pasada.

  • Marcadores: {{clave}} y {{{clave}}}, con clave = [A-Za-z0-9_]+. Lo que no encaja se copia literal.
  • Los valores insertados no se vuelven a analizar: no hay sustituciones encadenadas.
  • SustituirHtml: cuerpo HTML. {{clave}} se escapa; solo vale en contenido de elemento o dentro de un valor de atributo entre comillas.
  • SustituirTexto: cuerpo en texto plano. No escapa; {{{clave}}} solo con conversor (SaneadorContenido.ATexto).
  • SustituirAsunto: asunto. Sin {{{clave}}} y siempre en una sola línea.
  • Todo marcador rechazado se deja vacío y se registra en Incidencias; nunca se lanza excepción por el contenido.

Modelo de seguridad

  • Una sola pasada: la plantilla se recorre una vez de izquierda a derecha, en tiempo lineal. Lo insertado nunca se vuelve a analizar, así que un valor que contenga {{otra}} no se expande.
  • El catálogo manda: el tipo de cada variable lo decide el catálogo del servidor, no la plantilla. Una clave que no está en el catálogo se deja vacía y se registra.
  • Contexto HTML con estados explícitos: el procesador sigue el tokenizador HTML (contenido, apertura de etiqueta, nombre de etiqueta, entre atributos, nombre de atributo, valor con y sin comillas, comentarios y declaraciones, texto crudo) alimentado solo con el texto literal de la plantilla. Los valores insertados no cambian el estado: se escapan (& < > " ') o, en el caso de {{{ }}}, llegan ya saneados.
  • Dónde se admite un marcador: en contenido de elemento y en valores de atributo entre comillas. Se rechaza en el nombre de etiqueta (<scr{{x}}>), en nombres de atributo o entre atributos (<img {{x}}="…">), en valores sin comillas (title={{x}}), en atributos de evento (on*), srcdoc y srcset.
  • Comentarios y declaraciones: <!-- … --> (con los cierres del navegador: -->, --!>, <!-->, <!--->), <!…>, <!DOCTYPE …>, <?…> y </1…>: todo marcador se rechaza. Excepción: los comentarios condicionales de Outlook (<!--[if mso | IE]>…<![endif]--> y la forma <!--[if !mso]><!-->…<!--<![endif]--> que genera MJML) se analizan como HTML normal con las mismas reglas, porque Outlook los pinta.
  • Texto crudo: dentro de script, style, textarea, title, xmp, iframe, noembed y noframes no se admiten marcadores. El elemento solo se cierra con </nombre seguido de espacio HTML, / o > (no </script-x>).
  • Bloqueo: tras <![CDATA[, <svg>, <math>, <plaintext>, <select>, <frameset> o <!-- dentro de un script, el contexto deja de ser determinable con seguridad (contenido extranjero, escapado de script, modos que ignoran etiquetas) y se rechazan todos los marcadores siguientes del documento.
  • URL: si un valor de href/xlink:href contiene algún marcador, al cerrarse la comilla se valida el valor final entero: debe empezar por https://, mailto: o tel: (ignorando espacios iniciales, tabuladores y saltos, como el navegador). En src, background, poster, action, formaction, lowsrc, dynsrc, data y codebase, solo https://. Si no vale, el atributo se queda vacío (href="") y se registra. Las URL relativas o //host se rechazan, y un esquema escrito con entidades también.
  • style: un marcador solo vale como valor completo de una declaración (propiedad: {{x}}; o al final del atributo) y el valor debe ser un color hexadecimal o una palabra/medida simple ([A-Za-z0-9.%-]+). Nada de url(), funciones, escapes ni fragmentos de identificador.
  • Triple llave: {{{clave}}} solo inserta HTML si la variable es ContenidoEnriquecido, el marcador está en contenido de elemento y se ha pasado un saneador. En cualquier otro caso queda vacío y se registra.
  • Asunto: SustituirAsunto no admite {{{ }}} y cambia por un espacio CR, LF, U+0085, U+2028 y U+2029 de cada valor y del resultado final, para que no se puedan partir cabeceras.
  • Saneador (lista blanca): SaneadorContenido.Sanear solo conserva las etiquetas de los FormatoPermitido elegidos (p, br, strong, b, em, i, ul, ol, li, a). Elimina atributos, clases y propiedades CSS ajenos; los href solo pueden ser https: o mailto:; descarta con su contenido script, style, noscript, template, iframe, object, embed, title y textarea. Añade estilos en línea mínimos y el color de enlace (hexadecimal; si no es válido, el de por defecto).
  • Límites del contenido enriquecido: Sanear y ATexto devuelven cadena vacía si el HTML supera SaneadorContenido.TamanoMaximo (512 K caracteres) o 10 000 < (el analizador de AngleSharp es cuadrático con la profundidad); el procesador deja entonces el marcador vacío con una incidencia. ATexto recorre el árbol sin recursión y, más allá de 256 niveles, conserva el texto sin estructura.
  • Texto plano: SustituirTexto no escapa HTML. Para insertar contenido enriquecido en texto se le pasa SaneadorContenido.ATexto, que no devuelve HTML.

Ejemplo completo

using Gesgocom.PlantillasCorreo;

var catalogo = new Dictionary<string, VariableCatalogo>
{
    ["nombre"]  = new("nombre", "Nombre", TipoVariable.Texto, "Ana"),
    ["enlace"]  = new("enlace", "Enlace de acceso", TipoVariable.Enlace, "https://ejemplo.es"),
    ["mensaje"] = new("mensaje", "Mensaje", TipoVariable.ContenidoEnriquecido, "<p>Hola</p>"),
};
var valores = new Dictionary<string, string>
{
    ["nombre"]  = "Ana <b>",
    ["enlace"]  = "https://ejemplo.es/acceso?x=1&y=2",
    ["mensaje"] = "<p>Hola <strong>Ana</strong> <script>alert(1)</script></p>",
};

var html = ProcesadorMarcadores.SustituirHtml(
    "<p>Hola {{nombre}}</p><a href=\"{{enlace}}\">Entrar</a>{{{mensaje}}}",
    catalogo, valores, SaneadorContenido.Saneador(FormatoPermitido.Todos));

var asunto = ProcesadorMarcadores.SustituirAsunto("Bienvenida, {{nombre}}", catalogo, valores);
var texto = ProcesadorMarcadores.SustituirTexto("Hola {{nombre}}\n\n{{{mensaje}}}", catalogo, valores, SaneadorContenido.ATexto);

foreach (var i in html.Incidencias.Concat(asunto.Incidencias).Concat(texto.Incidencias))
    logger.LogWarning("Plantilla: {Incidencia}", i);

// html.Texto, asunto.Texto y texto.Texto son lo que se envía.

Desarrollo

make test          # pruebas en Release
NUGET_API_KEY=… make pack-current  # pruebas, compilación y publicación de la versión actual

NUGET_API_KEY solo se lee del entorno; sin ella los pack* fallan antes de compilar.

No packages depend on Gesgocom.PlantillasCorreo.

Primera versión: sustitución de marcadores {{clave}} y {{{clave}}} en una sola pasada y en tiempo lineal, con estados explícitos del contexto HTML (marcadores solo en contenido y en valores entre comillas), validación del valor final de los atributos URL, style restringido a valores completos, SustituirAsunto en una sola línea, y saneado por lista blanca del contenido enriquecido con conversión a texto plano y límites de tamaño.

.NET 10.0

Version Downloads Last updated
1.1.0 4 11/15/2026
1.0.0 4 11/15/2026