Persiltech.Membership.Email 0.2.0

There is a newer version of this package available.
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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Persiltech.Membership.Email" Version="0.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Persiltech.Membership.Email" Version="0.2.0" />
                    
Directory.Packages.props
<PackageReference Include="Persiltech.Membership.Email" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Persiltech.Membership.Email --version 0.2.0
                    
#r "nuget: Persiltech.Membership.Email, 0.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Persiltech.Membership.Email@0.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Persiltech.Membership.Email&version=0.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Persiltech.Membership.Email&version=0.2.0
                    
Install as a Cake Tool

Persiltech.Membership.Email

NuGet License: MIT Sponsor

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. IEmailTemplateRenderer es 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.3.0 132 9/16/2026
0.2.0 126 9/13/2026
0.1.0 136 9/6/2026

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