Persiltech.Membership.Email
0.3.0
dotnet add package Persiltech.Membership.Email --version 0.3.0
NuGet\Install-Package Persiltech.Membership.Email -Version 0.3.0
<PackageReference Include="Persiltech.Membership.Email" Version="0.3.0" />
<PackageVersion Include="Persiltech.Membership.Email" Version="0.3.0" />
<PackageReference Include="Persiltech.Membership.Email" />
paket add Persiltech.Membership.Email --version 0.3.0
#r "nuget: Persiltech.Membership.Email, 0.3.0"
#:package Persiltech.Membership.Email@0.3.0
#addin nuget:?package=Persiltech.Membership.Email&version=0.3.0
#tool nuget:?package=Persiltech.Membership.Email&version=0.3.0
Persiltech.Membership.Email
Adaptador de correo de Persiltech.Membership: compone los avisos de confirmación de correo, reinicio de contraseña y cambio de correo a partir de plantillas HTML, y los entrega por Persiltech.Email.
Persiltech.Membership deja IMembershipEmailSender sin implementar a propósito, porque
redactar el mensaje exige conocer la marca, el diseño y las rutas de la aplicación. Este
paquete pone esas tres cosas en Options y en plantillas sustituibles, de modo que dos
aplicaciones distintas comparten el mismo binario.
Instalación
dotnet add package Persiltech.Membership.Email
Uso
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSmtpEmailSender(options => builder.Configuration.GetSection("Smtp").Bind(options));
builder.Services.AddMembershipEmail(options => builder.Configuration.GetSection("MembershipEmail").Bind(options));
AddMembershipEmail no registra el transporte: IEmailSender lo aporta el consumidor,
normalmente con AddSmtpEmailSender de Persiltech.Email, porque elegir servidor y
credenciales es suyo. El orden entre ambas llamadas da igual; lo que no puede es faltar una.
Con la configuración correspondiente:
{
"MembershipEmail": {
"BrandName": "Persiltech",
"ClientBaseUrl": "https://app.example.com",
"LogoUrl": "https://cdn.example.com/logo.png",
"PrimaryColor": "#0d6efd",
"SupportEmail": "soporte@example.com"
}
}
Las opciones se validan al arrancar la aplicación, no en el primer aviso: el registro
usa un IValidateOptions<MembershipEmailOptions> y encadena ValidateOnStart(). Los fallos
salen todos juntos, no de uno en uno.
Dos de las reglas evitan fallos silenciosos que de otro modo nadie ve: TemplatesDirectory
tiene que existir —apuntando a un directorio que no está, se servirían las plantillas
embebidas y el rebrandeo no se aplicaría sin avisar— y LogoUrl tiene que ser absoluta,
porque los clientes de correo no resuelven rutas relativas. El validador se registra con
TryAddSingleton: uno propio registrado antes gana.
El contrato
public sealed class MembershipEmailOptions
{
public string BrandName { get; set; } = string.Empty; // obligatorio
public string ClientBaseUrl { get; set; } = string.Empty; // obligatoria, http o https absoluta
public string EmailConfirmationPath { get; set; } = "/confirm-email";
public string PasswordResetPath { get; set; } = "/reset-password";
public string EmailChangePath { get; set; } = "/confirm-email-change";
public string? LogoUrl { get; set; } // si se indica, absoluta
public string PrimaryColor { get; set; } = "#0d6efd"; // #rgb o #rrggbb
public string OnPrimaryColor { get; set; } = "#ffffff"; // el texto que va encima
public string Language { get; set; } = "es"; // etiqueta BCP 47
public string? SupportEmail { get; set; }
public string? TemplatesDirectory { get; set; } // si se indica, tiene que existir
}
OnPrimaryColor es el color del rótulo del encabezado y del texto del botón. Existe porque el
blanco no siempre vale: sobre una marca clara —un amarillo, un verde lima— el botón deja de
leerse, y el paquete no puede elegirlo sin conocer la marca.
Language va al atributo lang del documento. No traduce nada —el texto vive en las
plantillas— pero sin él una aplicación que las traduzca seguiría anunciando español, y un lector
de pantalla lo pronunciaría así.
ClientBaseUrl es la raíz de la aplicación cliente —la que abre el usuario—, no la de la
API, y de ella cuelgan las tres rutas.
Los enlaces
Cada aviso lleva un enlace de vuelta con los datos que la pantalla tiene que devolver a la
API. Los nombres de los parámetros salen de los contratos de Persiltech.Membership, que
identifican la cuenta por el correo:
| Aviso | Enlace |
|---|---|
| Confirmación de correo | {ClientBaseUrl}{EmailConfirmationPath}?email=…&token=… |
| Reinicio de contraseña | {ClientBaseUrl}{PasswordResetPath}?email=…&token=… |
| Cambio de correo | {ClientBaseUrl}{EmailChangePath}?newEmail=…&token=… |
Ambos valores viajan codificados con Uri.EscapeDataString: los testigos de ASP.NET Core
Identity traen + y /, y sin codificar se pierden por el camino.
Las plantillas
Cada aviso son tres archivos embebidos en el ensamblado, bajo Templates/:
| Aviso | Nombre | Archivos |
|---|---|---|
| Confirmación de correo | EmailConfirmation |
.subject.txt, .html, .txt |
| Reinicio de contraseña | PasswordReset |
.subject.txt, .html, .txt |
| Cambio de correo | EmailChange |
.subject.txt, .html, .txt |
| Bloqueo de la cuenta | AccountLocked |
.subject.txt, .html, .txt |
El .html de cada aviso es solo el interior: el encabezado, el ancho de 600 píxeles y el pie
viven una vez en Layout.html, que envuelve a los cuatro. El .txt es la parte alternativa en
texto plano, que un correo transaccional no debería omitir.
AccountLocked es el único sin enlace de vuelta. No lleva testigo —con uno, fallar la
contraseña de alguien bastaría para mandarle un enlace de reinicio que no ha pedido—, así que
no hay pantalla a la que dirigir a nadie y el marcador {{ActionUrl}} no aparece en su
plantilla. A cambio dispone de {{LockoutMinutes}}, los minutos que dura el bloqueo. Se manda
la duración y no la hora a la que termina para no tener que acertar con la zona horaria de
quien lo lee.
Cambiar el diseño
TemplatesDirectory apunta a una carpeta cuyos archivos ganan a los embebidos, por nombre.
Basta con dejar ahí el que se quiera cambiar —Layout.html para rebrandear entero, o el
.html de un aviso suelto—; el resto siguen saliendo del paquete. Las plantillas se leen una
vez y se cachean, así que un cambio en disco exige reiniciar la aplicación.
Para la mayoría de los casos no hace falta llegar ahí: el logotipo, los dos colores, el idioma y el correo de contacto son configuración. Sustituir plantillas es para cambiar el texto —traducirlo, por ejemplo— o la maqueta.
Qué hay detrás del diseño
Un correo no es una página web: se abre en decenas de clientes que interpretan el HTML de forma distinta, y varios llevan veinte años sin cambiar. Estas plantillas dan por sentado eso, y conviene saberlo antes de tocarlas:
- El botón va por duplicado. Outlook de escritorio usa el motor de Word, que no entiende
border-radiusni el relleno de uninline-block: sin la variante VML de dentro del condicional<!--[if mso]>, el botón le sale como texto suelto. El resto de clientes ven el enlace normal. - Modo oscuro. Se declaran ambos esquemas y la maqueta trae su paleta oscura. Sin eso, Apple Mail y Outlook.com invierten el fondo por su cuenta y dejan el texto oscuro sobre fondo oscuro.
- Todo el estilo va en línea. Gmail descarta el
<style>en varios contextos; el bloque solo lleva lo que mejora la experiencia y cuya ausencia no rompe nada —las medias consultas—. - En móvil el botón ocupa el ancho y mide 48 px de alto, por encima del mínimo táctil recomendado, y el cuerpo va a 16 px.
- Cada aviso trae su versión en texto plano. No es un adorno: hay clientes y filtros que la prefieren, y un transaccional sin ella puntúa peor en entrega.
- Ninguna imagen es imprescindible. Muchos clientes las bloquean por defecto, así que el
mensaje se entiende entero sin cargar ninguna; el logotipo es opcional y lleva
alt.
Si sustituyes Layout.html o el .html de un aviso, estas propiedades se pierden salvo que
las mantengas. Lo más fácil es partir del archivo del paquete y editarlo.
Marcadores
La sintaxis es {{Nombre}}. Un marcador que no corresponda a ningún valor lanza
InvalidOperationException nombrándolo: una plantilla con un nombre mal tecleado tiene que
fallar en el primer envío de prueba, no llegar en blanco al buzón de un cliente.
| Marcador | Origen |
|---|---|
FirstName, LastName, FullName |
El aviso. |
Email |
Destinatario del aviso. |
ActionUrl |
Enlace de vuelta, ya construido. |
LockoutMinutes |
Solo en AccountLocked: minutos que dura el bloqueo. |
BrandName, PrimaryColor, OnPrimaryColor, Language, SupportEmail |
Las opciones. |
BrandHeader |
El logotipo como <img> si hay LogoUrl; si no, la marca en texto. |
SupportLine |
El contacto del pie ya maquetado, o nada si no hay SupportEmail. |
SupportLineText |
Lo mismo para la versión en texto plano. |
Year |
Año en curso, para el pie. |
Preheader |
El asunto ya sustituido. |
Body |
Solo en Layout.html: el interior del aviso. |
SupportLine y SupportLineText existen porque SupportEmail es opcional y el compositor no
tiene condicionales: escribiendo el separador y el mailto: directamente en la plantilla, un
despliegue sin correo de contacto acababa con un · colgando y un enlace vacío.
En el .html los valores se insertan codificados —solo lo sensible en HTML: los acentos
viajan tal cual—; en el .txt y en el asunto, crudos. Body y BrandHeader son las dos
excepciones: son marcado que genera el propio paquete.
Otro motor de plantillas
IEmailTemplateRenderer es público y se registra con TryAddSingleton, así que una
implementación propia —con Scriban, Fluid o lo que sea— registrada antes de
AddMembershipEmail gana:
public interface IEmailTemplateRenderer
{
RenderedEmail Render(string templateName, IReadOnlyDictionary<string, string?> values);
}
public sealed record RenderedEmail(string Subject, string HtmlBody, string TextBody);
Decisiones de diseño
- Plantillas en archivos, no en cadenas de C#. El HTML de correo es tabular y con estilos en línea: en archivos se previsualiza en un navegador, lo puede tocar un diseñador y el encabezado y el pie se escriben una sola vez.
- Ni Razor ni un motor de terceros de partida. Razor exige ASP.NET Core y compilación en
tiempo de ejecución para tres correos transaccionales.
IEmailTemplateRendereres la costura por la que entra un motor con condicionales el día que haga falta. - La marca y las rutas son configuración. Es lo que separa a este paquete de un adaptador escrito dentro de una aplicación.
- Un marcador desconocido lanza. Es determinista, así que salta en la primera prueba de quien escribe la plantilla.
- El paquete no elige el transporte. Depende de
IEmailSender, no de SMTP.
Compatibilidad
net10.0. Requiere Persiltech.Membership y Persiltech.Email.
Estado
Versión 0.x: la superficie pública puede cambiar entre versiones menores.
Historial de versiones
El código fuente vive en el monorepo; esta tabla resume qué cambió en cada versión publicada.
| Versión | Cambios |
|---|---|
| 0.3.0 | Nueva plantilla AccountLocked, para el aviso de bloqueo de cuenta que estrena Persiltech.Membership 0.9.0. Es la única sin enlace de vuelta: no lleva testigo, así que no hay pantalla a la que dirigir a nadie. Dispone de {{LockoutMinutes}} y dice cuánto dura el bloqueo en lugar de a qué hora termina, para no depender de la zona horaria de quien lo lee.<br><br>Rediseño de las cuatro plantillas. El botón gana su variante VML para Outlook de escritorio, donde salía como texto suelto. Los mensajes dejan de quedar ilegibles en modo oscuro. En móvil el botón ocupa el ancho y mide 48 px de alto, y el cuerpo sube a 16 px. Se corrige el pie cuando no hay SupportEmail: escribía un separador colgando y un mailto: vacío. Dos opciones nuevas, OnPrimaryColor —el blanco no se lee sobre una marca clara— y Language —el idioma estaba fijado a español dentro de la maqueta—, y cuatro marcadores nuevos para quien sustituya plantillas. |
| 0.2.0 | ClientBaseUrls: una dirección de vuelta por portal, elegida con la cabecera clientId que envía el frontal. Con una sola dirección, quien pedía su contraseña desde el portal de clientes recibía un enlace hacia el administrativo. La clave solo elige entre lo configurado; una desconocida cae en ClientBaseUrl. |
| 0.1.0 | Primera versión: implementa IMembershipEmailSender con plantillas HTML embebidas y sustituibles, la marca y las rutas del cliente como configuración, y la entrega por IEmailSender. |
Soporte
Para dudas, fallos o peticiones abre una incidencia. También puedes consultar la página del paquete.
Apoyar el desarrollo
Si el paquete te ahorra trabajo, puedes apoyar su mantenimiento en GitHub Sponsors.
| 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
- Persiltech.Email (>= 0.1.1)
- Persiltech.Membership (>= 0.9.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
v0.3.0
- Nueva plantilla AccountLocked, para el aviso de bloqueo de cuenta que estrena Persiltech.Membership 0.9.0
- Es el unico aviso sin enlace de vuelta: no lleva testigo, asi que no hay pantalla a la que mandar a nadie
- Dice cuantos minutos dura el bloqueo, en lugar de a que hora termina, para no depender de la zona horaria de quien lee
- Como los demas, se puede sustituir por archivo con MembershipEmailOptions.TemplatesDirectory
- Rediseno de las cuatro plantillas. El boton gana su version VML para Outlook de escritorio, que usa el motor de Word y lo dejaba como texto suelto
- Modo oscuro: los mensajes ya no quedan con texto oscuro sobre fondo oscuro en Apple Mail ni en Outlook.com
- En movil el boton ocupa el ancho y mide 48 px de alto, por encima del minimo tactil; el cuerpo sube a 16 px
- Se corrige el pie cuando SupportEmail no esta configurado: antes escribia un separador colgando y un enlace mailto: vacio
- Nueva opcion OnPrimaryColor: el blanco sobre una marca clara no se lee, y el paquete no puede elegirlo sin conocerla
- Nueva opcion Language: el idioma del documento estaba fijado a espanol dentro de la maqueta
- Nuevos marcadores para quien sustituya las plantillas: OnPrimaryColor, Language, SupportLine y SupportLineText
v0.1.0
- Primera versión: implementa IMembershipEmailSender de Persiltech.Membership con plantillas HTML
- La marca, los colores y las rutas del cliente son configuración, no código
- Las plantillas embebidas se sustituyen por archivo con MembershipEmailOptions.TemplatesDirectory
- Las opciones se validan al arrancar con IValidateOptions, acumulando todos los fallos