Email xác nhận đơn hàng bắt đầu bằng một chuỗi $"Xin chào {order.CustomerName}". Ba tháng sau, nó có thêm điều kiện VIP, vòng lặp danh sách sản phẩm, định dạng tiền theo locale, và một nhánh cho khách doanh nghiệp. Đó là lúc bạn cần template engine Fluid hoặc Scriban — nhưng chỉ khi template thật sự là dữ liệu. Bài này chỉ ra ranh giới đó, cú pháp thật của hai thư viện, và cách chạy template không tin cậy mà không mở toang ứng dụng.
Mục lục
Cập nhật 2026
- .NET 10 LTS là nền cho mọi ví dụ; Razor vẫn là mặc định cho HTML biên dịch cùng app (Razor Pages, MVC, Blazor). Template engine là lựa chọn cho nội dung sinh lúc chạy.
System.Net.Mail.SmtpClientkhông còn được Microsoft khuyến nghị cho code mới. Dùng MailKit cho SMTP; phần render template không phụ thuộc thư viện mail.- Fluid giữ tương thích Liquid (Shopify) và là lựa chọn khi template do người dùng chỉnh. Scriban mạnh hơn về logic, phù hợp báo cáo nội bộ do dev kiểm soát.
- Cả hai đều hỗ trợ render async và culture; cache template đã parse là yêu cầu bắt buộc nếu render trong request path.
Template engine hay Razor?
Câu hỏi đúng không phải “engine nào đẹp hơn” mà “template đến từ đâu và ai được sửa nó”. Razor biên dịch template thành C# ngay lúc build: type-safe, nhanh, nhưng template phải nằm trong project và đổi template = deploy lại. Template engine đọc template lúc chạy: đổi template không cần build, nhưng bạn mất kiểm tra kiểu và phải tự lo escaping, sandbox, cache.
| Công cụ | Dùng khi |
|---|---|
| Razor | HTML nội bộ của app, template do dev viết, cần IntelliSense và lỗi lúc compile. Mặc định cho mọi trang web. |
| Fluid | Template email/landing page do marketer hoặc khách hàng chỉnh; cần cú pháp Liquid quen thuộc; ưu tiên an toàn. |
| Scriban | Báo cáo, hóa đơn, file cấu hình, code generation; template nội bộ cần vòng lặp, hàm, xử lý chuỗi phức tạp. |
Nếu template là chuỗi trong database và người dùng có thể sửa, bạn đang chạy code do người khác viết. Đó là quyết định bảo mật, không phải quyết định thư viện. Phần sandbox bên dưới quan trọng hơn phần cú pháp.
Fluid: Liquid cho .NET
Fluid parse template một lần thành IFluidTemplate, rồi render nhiều lần với các TemplateContext khác nhau. Hai khái niệm cần nắm: MemberAccessStrategy quyết định type nào được phép đọc property, và TemplateContext giữ dữ liệu, culture, và bộ filter.
// File: Templating/OrderTemplateRenderer.cs
using Fluid;
public sealed class OrderTemplateRenderer
{
private static readonly FluidParser Parser = new();
private readonly IFluidTemplate _template;
public OrderTemplateRenderer()
{
var source = File.ReadAllText("Templates/order-confirmation.liquid");
_template = Parser.Parse(source); // ParseException nếu cú pháp sai
}
public async Task<string> RenderAsync(OrderDto order)
{
var context = new TemplateContext
{
CultureInfo = CultureInfo.GetCultureInfo("vi-VN"),
};
// Chỉ hai type này được phép truy cập property.
context.MemberAccessStrategy.Register<OrderDto>();
context.MemberAccessStrategy.Register<OrderLineDto>();
context.SetValue("order", order);
context.SetValue("supportEmail", "hotro@evotek.vn");
return await _template.RenderAsync(context);
}
}
Register<T>() không phải thủ tục bắt buộc về mặt kỹ thuật — nó là rào chắn. Nếu bạn dùng UnsafeMemberAccessStrategy để “cho nó chạy”, template có thể đi từ order sang bất kỳ property public nào trên đường đi, kể cả những thứ bạn không định lộ. Với template nội bộ điều đó chấp nhận được; với template của khách hàng thì không.
Template Liquid tương ứng:
Xin chào {{ order.CustomerName | escape }},
{% if order.IsVip %}
Ưu đãi thành viên VIP đang áp dụng cho đơn này.
{% endif %}
{% for line in order.Lines %}
- {{ line.ProductName | escape }} × {{ line.Quantity }}
{% endfor %}
Tổng cộng: {{ order.Total }} VND
Ba loại cú pháp cần nhớ: {{ }} xuất giá trị, {% %} điều khiển luồng, và | áp filter. Filter có sẵn đủ dùng cho trình bày: escape, upcase, downcase, size, date, truncate, replace. Filter định dạng tiền theo vùng miền thì bạn tự thêm qua context.Filters.AddFilter("vnd", ...), đừng cố nhồi logic đó vào template.
Scriban: cùng cú pháp, nhiều quyền hơn
Scriban cũng dùng {{ }} nhưng cú pháp lệnh là {{ for item in items }} … {{ end }}. Nếu bạn muốn viết {% for %} kiểu Liquid, phải gọi Template.ParseLiquid — dùng Template.Parse với {% %} sẽ lỗi cú pháp. Đây là nhầm lẫn phổ biến nhất khi chuyển ví dụ Liquid sang Scriban.
// File: Reports/InvoiceRenderer.cs
using Scriban;
using Scriban.Runtime;
public static class InvoiceRenderer
{
public static async Task<string> RenderAsync(InvoiceDto invoice)
{
var source = await File.ReadAllTextAsync("Templates/invoice.sbn");
var template = Template.Parse(source, "invoice");
if (template.HasErrors)
{
throw new InvalidOperationException(
string.Join(Environment.NewLine, template.Messages));
}
var context = new TemplateContext
{
CultureInfo = CultureInfo.GetCultureInfo("vi-VN"),
LoopLimit = 500,
RecursiveLimit = 10,
EnableRelaxedMemberAccess = false,
};
var globals = new ScriptObject();
globals.Import(new { invoice, items = invoice.Items });
context.PushGlobal(globals);
return await template.RenderAsync(context);
}
}
Hóa đơn {{ invoice.code }}
Khách hàng: {{ invoice.customer_name }}
{{ for item in items }}
{{ item.product_name }} | {{ item.quantity }} | {{ item.unit_price }}
{{ end }}
Tổng cộng: {{ invoice.total }}
Chú ý: template viết invoice.customer_name trong khi property C# là CustomerName. Scriban đổi PascalCase sang snake_case qua MemberRenamer mặc định; nếu bạn muốn giữ nguyên tên, gán context.MemberRenamer = m => m.Name; và viết template theo đúng tên C#. Chọn một quy ước và ghi vào README của thư mục template, vì đây là nguồn lỗi “property không tồn tại” khó đoán nhất.
ScriptObject.Import ánh xạ object .NET sang biến template; PushGlobal đưa nó vào scope gốc. Bạn có thể thêm hàm bằng globals.Add("vnd", delegate), nhưng hãy giữ số hàm nhỏ — mỗi hàm là một API công khai cho template.
Escaping, culture và HTML
Cả hai thư viện đều là engine text, không phải engine HTML. Chúng không biết ngữ cảnh output của bạn, nên trách nhiệm escaping thuộc về bạn. Trong template HTML, escape mọi giá trị đến từ người dùng: {{ name | escape }} với Fluid, {{ name | html.escape }} với Scriban. Bỏ qua bước này là mở đường cho XSS ngay trong email hoặc trang in hóa đơn.
Culture phải đặt tường minh. CultureInfo trên context ảnh hưởng cách format số và ngày; máy chủ châu Á và CI ở Mỹ sẽ cho ra 1,234.5 và 1.234,5 khác nhau nếu bạn để mặc định. Với output máy đọc (JSON, CSV), dùng CultureInfo.InvariantCulture; với output cho người đọc, dùng culture của người nhận, không phải culture của server.
Một lưu ý thực chiến với HTML: template engine giữ nguyên whitespace và xuống dòng. Với email, hãy viết template trên một dòng logic hoặc dùng whitespace control của Scriban ({{~ ... ~}}) để tránh khoảng trắng lạ trong bảng. Với HTML gửi mail, CSS phải inline — nhiều client vẫn bỏ qua <style> trong <head>.
Async, cache và chi phí parse
Parse là phần đắt: nó tokenize và dựng AST. Render thì rẻ. Vì vậy đừng parse trong vòng lặp gửi 10.000 email — parse một lần, render 10.000 lần. Với template lấy từ database, cache theo (templateId, version):
// File: Templating/TemplateCache.cs
using System.Collections.Concurrent;
public sealed class TemplateCache
{
private readonly ConcurrentDictionary<string, IFluidTemplate> _cache = new();
private readonly FluidParser _parser = new();
public IFluidTemplate Get(string key, string source)
{
return _cache.GetOrAdd(key, _ => _parser.Parse(source));
}
}
Khóa phải gồm version hoặc hash nội dung; khóa chỉ theo id sẽ khiến template sửa mà app không thấy. Nếu nhiều instance cùng render, cache in-memory vẫn hữu ích vì mỗi instance tự parse một lần — nhưng nếu bạn muốn chia sẻ giữa các instance, đặt template đã compile vào distributed cache là không thực tế (AST không serialize được), hãy cache nội dung template và parse tại chỗ. Với dữ liệu tốn kém hơn, xem các chiến lược cache trong ASP.NET Core.
Async: cả RenderAsync của Fluid và Scriban đều tồn tại vì template có thể gọi filter/hàm async. Nếu bạn tự viết hàm cho template, đảm bảo nó không block; một .Result trong filter sẽ deadlock dưới tải.
Sandbox template không tin cậy
Với Fluid, sandbox là mặc định: chỉ type đã Register mới đọc được property. Đừng bao giờ đăng ký object, type có static method nguy hiểm, hay bất cứ thứ gì chạm tới System.IO, Process, Assembly. Nếu bạn cho phép include/layout, hãy kiểm soát đường dẫn template loader — template không được đọc file ngoài thư mục cho phép.
Với Scriban, mặc định thoáng hơn. Ba biện pháp tối thiểu:
- Đặt
LoopLimitvàRecursiveLimitđể chặn template tự làm treo CPU. - Để
EnableRelaxedMemberAccess = falsevà không gánTemplateLoader; không có loader thìincludekhông đọc được file. - Chỉ
ImportmộtScriptObjectphẳng chứa DTO, không import chính domain object có navigation property sâu, càng không importTypeđể lộ static member.
Cả hai không có cơ chế timeout tuyệt đối đáng tin cậy. Với template do người lạ gửi, chạy render trong worker riêng, áp time budget ở tầng ngoài, và coi việc hủy là best-effort: một template bệnh hoạn vẫn có thể tiêu CPU cho tới khi bị ngắt. Nếu yêu cầu bảo mật cao, template không tin cậy nên render trong container/process cách ly, không phải trong process API chính.
Ghép với MailKit
// File: Notifications/EmailSender.cs
using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;
public sealed class EmailSender
{
public async Task SendAsync(string to, string subject, string html, CancellationToken ct)
{
var message = new MimeMessage();
message.From.Add(new MailboxAddress("Evotek", "no-reply@evotek.vn"));
message.To.Add(MailboxAddress.Parse(to));
message.Subject = subject;
var body = new BodyBuilder { HtmlBody = html };
message.Body = body.ToMessageBody();
using var client = new SmtpClient();
await client.ConnectAsync("smtp.evotek.vn", 587, SecureSocketOptions.StartTls, ct);
await client.AuthenticateAsync("smtp-user", "smtp-password", ct);
await client.SendAsync(message, ct);
await client.DisconnectAsync(quit: true, ct);
}
}
Đừng tạo SmtpClient mỗi email trong vòng lặp lớn — mở TLS và authenticate cho từng message là chi phí thật. Với khối lượng lớn, giữ một connection pool hoặc chuyển sang dịch vụ email chuyên dụng. Và đừng đưa mật khẩu vào code: đọc từ secret store như mọi connection string khác.
Anti-pattern thường gặp
- Nhồi business logic vào template. Template tính thuế, tính giảm giá, gọi API — không. Chuẩn bị DTO đầy đủ trong C#, template chỉ trình bày.
- Parse lại mỗi request. Đây là chi phí CPU và allocation không cần thiết; cache theo version.
- Không escape. XSS trong email ít nguy hiểm hơn trên web, nhưng trong trang preview hoặc PDF thì không.
- Dùng culture mặc định của server. Bug chỉ xuất hiện trên môi trường có locale khác.
- Cho người dùng sửa template mà không giới hạn quyền truy cập. Đây là lỗi nghiêm trọng nhất trong danh sách này.
Checklist
- Xác định template là code của bạn (Razor) hay dữ liệu của người dùng (engine).
- Parse một lần, cache theo id + version; render async.
- Đặt
CultureInfotường minh cho mọi context. - Escape mọi giá trị người dùng trong output HTML.
- Với template không tin cậy: whitelist type, giới hạn loop, không loader, time budget.
- Log lỗi parse bằng structured logging để biết template nào hỏng; xem bài Serilog ở phần đọc tiếp.



