Persiltech.Membership.Email
0.2.0
See the version list below for details.
dotnet add package Persiltech.Membership.Email --version 0.2.0
NuGet\Install-Package Persiltech.Membership.Email -Version 0.2.0
<PackageReference Include="Persiltech.Membership.Email" Version="0.2.0" />
<PackageVersion Include="Persiltech.Membership.Email" Version="0.2.0" />
<PackageReference Include="Persiltech.Membership.Email" />
paket add Persiltech.Membership.Email --version 0.2.0
#r "nuget: Persiltech.Membership.Email, 0.2.0"
#:package Persiltech.Membership.Email@0.2.0
#addin nuget:?package=Persiltech.Membership.Email&version=0.2.0
#tool nuget:?package=Persiltech.Membership.Email&version=0.2.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? SupportEmail { get; set; }
public string? TemplatesDirectory { get; set; } // si se indica, tiene que existir
}
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 |
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 tres. El .txt es la parte alternativa en
texto plano, que un correo transaccional no debería omitir.
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.
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. |
BrandName, PrimaryColor, SupportEmail |
Las opciones. |
BrandHeader |
El logotipo como <img> si hay LogoUrl; si no, la marca en texto. |
Year |
Año en curso, para el pie. |
Preheader |
El asunto ya sustituido. |
Body |
Solo en Layout.html: el interior del aviso. |
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.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.8.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.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