TailoredApps.Shared.Email¶
Opis¶
Biblioteka dostarcza kompletną abstrakcję do wysyłania wiadomości e-mail w aplikacjach .NET. Opiera się na interfejsie IEmailProvider, który możesz wymieniać w zależności od środowiska — w produkcji używasz SmtpEmailProvider (wysyłka przez SMTP), w lokalnym środowisku deweloperskim EmailServiceToConsolleWritter (wypisuje do konsoli bez wysyłki).
Biblioteka zawiera też system budowania treści emaili oparty na szablonach (IMailMessageBuilder), który obsługuje proste podstawianie tokenów (DefaultMessageBuilder) lub szablony ładowane z pliku z placeholderami {{token}} (TokenReplacingMailMessageBuilder).
Wbudowane zabezpieczenie przed przypadkowym spamem w środowiskach nieprodukcyjnych: kiedy IsProd = false, wszystkie emaile trafiają na adres CatchAll zamiast do prawdziwych odbiorców.
Instalacja¶
Rejestracja w DI¶
// Program.cs
using TailoredApps.Shared.Email;
// Rejestracja SMTP provider
builder.Services.RegisterSmtpProvider();
// Opcjonalnie: rejestracja buildera szablonów
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.Configure<TokenReplacingMailMessageBuilderOptions>(options =>
{
options.Location = Path.Combine(builder.Environment.ContentRootPath, "EmailTemplates");
options.FileExtension = "html";
});
Konfiguracja appsettings.json¶
{
"Mail": {
"Providers": {
"Smtp": {
"Host": "smtp.example.com",
"Port": 587,
"UserName": "noreply@example.com",
"Password": "secret",
"From": "noreply@example.com",
"EnableSsl": true,
"IsProd": true,
"CatchAll": "dev@example.com"
}
}
}
}
Przykład użycia¶
public class NotificationService
{
private readonly IEmailProvider _emailProvider;
private readonly IMailMessageBuilder _messageBuilder;
public NotificationService(
IEmailProvider emailProvider,
IMailMessageBuilder messageBuilder)
{
_emailProvider = emailProvider;
_messageBuilder = messageBuilder;
}
public async Task SendWelcomeEmailAsync(string recipientEmail, string userName)
{
var body = _messageBuilder.Build(
templateKey: "welcome.html",
variables: new Dictionary<string, string>
{
{ "UserName", userName },
{ "AppUrl", "https://myapp.example.com" }
},
templates: null // załaduje z pliku, jeśli skonfigurowano Location
);
var messageId = await _emailProvider.SendMail(
recipnet: recipientEmail,
topic: "Witaj w MyApp!",
messageBody: body,
attachments: null
);
Console.WriteLine($"Email sent, MessageId: {messageId}");
}
public async Task SendInvoiceAsync(
string recipientEmail,
string subject,
string htmlBody,
byte[] pdfBytes)
{
await _emailProvider.SendMail(
recipnet: recipientEmail,
topic: subject,
messageBody: htmlBody,
attachments: new Dictionary<string, byte[]>
{
{ "faktura.pdf", pdfBytes }
}
);
}
}
Szablon e-mail (welcome.html)¶
<!DOCTYPE html>
<html>
<body>
<h1>Witaj, {{UserName}}!</h1>
<p>Twoje konto zostało założone. <a href="{{AppUrl}}">Kliknij tutaj</a> by się zalogować.</p>
</body>
</html>
API Reference¶
| Typ | Rodzaj | Opis |
|---|---|---|
IEmailProvider |
Interfejs | Główny kontrakt: SendMail, GetMail |
SmtpEmailProvider |
Klasa | Wysyłka przez SMTP; opcje z SmtpEmailServiceOptions. GetMail nie jest zaimplementowane (NotImplementedException) |
EmailServiceToConsolleWritter |
Klasa | Wypisuje dane emaila do konsoli (dev/test); GetMail zwraca pustą listę. Nazwa klasy ma taką pisownię w API |
SmtpEmailServiceOptions |
Klasa | Konfiguracja SMTP: Host, Port, UserName, Password, From, EnableSsl, IsProd, CatchAll |
IMailMessageBuilder |
Interfejs | Kontrakt: Build(templateKey, variables, templates) |
DefaultMessageBuilder |
Klasa | Podstawia tokeny w słowniku szablonów |
TokenReplacingMailMessageBuilder |
Klasa | Ładuje szablony z systemu plików; placeholdery {{token}} |
TokenReplacingMailMessageBuilderOptions |
Klasa | Location (ścieżka do katalogu szablonów), FileExtension |
SmtpEmailProviderExtensions.RegisterSmtpProvider |
Metoda ext. | Rejestruje SmtpEmailProvider w DI |
SmtpEmailProviderExtensions.RegisterConsoleProvider |
Metoda ext. | Rejestruje EmailServiceToConsolleWritter w DI |
🔒 Bezpieczeństwo¶
- Zmienne szablonu są kodowane jako HTML. Treść wiadomości jest wysyłana jako HTML, a wartości
{{token}}często pochodzą od użytkownika (np. nazwa wyświetlana).TokenReplacingMailMessageBuilderiDefaultMessageBuilderkodują wartości (WebUtility.HtmlEncode), więc<a href="https://evil">nie stanie się linkiem phishingowym w mailu z zaufanego nadawcy. Wartości, które celowo zawierają HTML, wstawiaj przez potrójne nawiasy{{{token}}}; globalnie wyłącza toTokenReplacingMailMessageBuilderOptions.HtmlEncodeVariables = falselubnew DefaultMessageBuilder(htmlEncodeVariables: false). - Podmiana w jednym przebiegu. Wartość zawierająca
{{InnyToken}}nie jest ponownie rozwijana. - Jeden adresat.
SmtpEmailProvider.SendMailprzyjmuje dokładnie jeden adres; lista rozdzielona przecinkami lub średnikami kończy sięFormatException(wcześniejMailAddressCollection.Adddopisywał dodatkowych odbiorców). - TLS domyślnie włączone.
Mail:Providers:Smtp:EnableSslma teraz wartość domyślnątrue. CatchAllwymagany poza produkcją. GdyIsProd = false, brakCatchAllpowodujeInvalidOperationExceptionzamiast wysyłki „donikąd”.
🤖 AI Agent Prompt¶
## TailoredApps.Shared.Email — Instrukcja dla agenta AI
Używasz biblioteki TailoredApps.Shared.Email w projekcie .NET.
### Rejestracja
```csharp
// Produkcja (SMTP):
builder.Services.RegisterSmtpProvider();
// Development (konsola):
builder.Services.RegisterConsoleProvider();
// Builder szablonów (opcjonalnie):
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.Configure<TokenReplacingMailMessageBuilderOptions>(o => {
o.Location = "EmailTemplates/";
o.FileExtension = "html";
});
```
### appsettings.json
```json
"Mail": { "Providers": { "Smtp": {
"Host": "smtp.host.com", "Port": 587, "UserName": "user",
"Password": "pass", "From": "no-reply@app.com",
"EnableSsl": true, "IsProd": true, "CatchAll": "dev@app.com"
}}}
```
### Użycie
```csharp
// Wstrzyknij IEmailProvider + IMailMessageBuilder
var body = _builder.Build("template.html", variables, null);
await _emailProvider.SendMail(email, subject, body, attachments);
```
### Zasady
- Gdy IsProd=false, wszystkie emaile trafiają na CatchAll — nigdy do prawdziwych odbiorców
- Do testów wstrzyknij IEmailProvider jako mock lub użyj RegisterConsoleProvider
- Placeholdery w szablonach TokenReplacing: {{NazwaTokena}}
- Klucz szablonu (`templateKey`) musi być równy nazwie pliku szablonu wraz z rozszerzeniem, np. `template.html`; nieznany klucz → `KeyNotFoundException`
- Sekcja konfiguracji "Mail:Providers:Smtp" jest wymagana — jej brak powoduje `InvalidOperationException`
- Załączniki: słownik fileName → byte[]
- Wartości {{token}} są HTML-encodowane; HTML wstawiaj świadomie przez {{{token}}}
- SendMail przyjmuje jeden adres — listy odbiorców obsługuj pętlą po stronie aplikacji
- EnableSsl jest domyślnie true; CatchAll jest wymagany gdy IsProd = false