📖 سری آموزشی کتاب C# 12 in a Nutshell

⚙️ قدرت where: راهنمای کامل Generic Constraints در #C

تو پست قبلی با جنریک‌ها آشنا شدیم. اما پارامتر T به صورت پیش‌فرض یک "لوح سفید" هست و کامپایلر هیچ‌چیزی در موردش نمی‌دونه. چطور می‌تونیم به کامپایلر بگیم که T باید چه قابلیت‌هایی داشته باشه؟

با استفاده از قیدهای جنریک (Generic Constraints) و کلمه کلیدی where.

1️⃣ چرا به قیدها (Constraints) نیاز داریم؟

به صورت پیش‌فرض، شما می‌تونید هر نوعی رو جای T قرار بدید. قیدها این امکان رو محدود می‌کنن، اما هدف اصلی‌شون فعال کردن قابلیت‌های جدیده. وقتی شما یه قید میذارید، به کامپایلر میگید: "من قول میدم که T حتماً این قابلیت‌ها رو داره" و کامپایلر هم در عوض به شما اجازه میده از اون قابلیت‌ها استفاده کنید (مثلاً متدهای یک اینترفیس رو روی T صدا بزنید).

2️⃣ انواع قیدهای جنریک

این لیست کامل قیدهاییه که می‌تونید با where استفاده کنید:

🔹️ where T : base-class
(قید کلاس پایه: T باید از این کلاس ارث‌بری کند)

🔹️ where T : interface
(قید اینترفیس: T باید این اینترفیس را پیاده‌سازی کند)

🔹️ where T : class
(قید نوع ارجاعی: T باید یک کلاس باشد)

🔹️ where T : struct
(قید نوع مقداری: T باید یک struct باشد)

🔹️ where T : new()
(قید سازنده: T باید یک سازنده بدون پارامتر داشته باشد)

🔹️ where U : T
(قید نوع عریان: پارامتر جنریک U باید از T ارث‌بری کند)

3️⃣ مثال‌های کاربردی

قید اینترفیس (: <IComparable<T):
فرض کنید می‌خوایم یه متد Max بنویسیم. برای این کار، باید مطمئن باشیم که T قابلیت مقایسه شدن رو داره.

static T Max<T>(T a, T b) where T : IComparable<T>
{
    // حالا که قید گذاشتیم، کامپایلر اجازه میده متد CompareTo رو صدا بزنیم
    return a.CompareTo(b) > 0 ? a : b;
}
// استفاده:
int z = Max(5, 10); // 10

قید نوع مقداری (: struct):

این قید تضمین می‌کنه که T باید یک Value Type باشد. بهترین مثالش، خودِ System.Nullable<T> هست که فقط برای Value Typeها معنی داره.

struct Nullable<T> where T : struct { /* ... */ }

قید سازنده (: ()new):

این قید تضمین می‌کنه که T یک سازنده عمومی بدون پارامتر داره. این به ما اجازه میده که بتونیم با new T() ازش نمونه بسازیم.

static void Initialize<T>(T[] array) where T : new()
{
    for (int i = 0; i < array.Length; i++)
        array[i] = new T();
}

🤔 حرف حساب و تجربه شما

قیدهای جنریک، ابزار اصلی شما برای ساختن APIهای جنریک قدرتمند، امن و کارآمد هستن.

🔖 هشتگ‌ها:
#CSharp #DotNet #OOP #Generics

📖 سری آموزشی کتاب C# 12 in a Nutshell

🧬 وراثت در دنیای جنریک‌ها: ساختن تایپ‌های پیچیده

تو پست قبلی، با قیدهای جنریک آشنا شدیم. حالا می‌خوایم ببینیم چطور می‌تونیم این دو مفهوم قدرتمند، یعنی وراثت و جنریک‌ها، رو با هم ترکیب کنیم تا سلسله‌مراتب‌های تایپی پیچیده و در عین حال قابل استفاده مجدد بسازیم.

1️⃣ ارث‌بری از کلاس‌های جنریک

یک کلاس جنریک می‌تونه مثل هر کلاس دیگه‌ای به ارث برده بشه. کلاس فرزند (subclass) در این حالت چند تا انتخاب داره:

باز گذاشتن پارامتر نوعی: 📖

در این حالت، کلاس فرزند هم جنریک باقی می‌مونه و پارامتر نوعی T رو از پدر به ارث می‌بره.

class Stack<T> { /* ... */ }
class SpecialStack<T> : Stack<T> { /* ... */ }

بستن پارامتر نوعی:
شما می‌تونید با یه نوع مشخص، پارامتر جنریک کلاس پدر رو ببندید. در این حالت، کلاس فرزند شما دیگه جنریک نیست.

class IntStack : Stack<int> { /* ... */ }

معرفی پارامترهای نوعی جدید: کلاس فرزند می‌تونه علاوه بر پارامترهای پدر، پارامترهای جنریک جدیدی هم برای خودش تعریف کنه.

class List<T> { /* ... */ }
class KeyedList<T, TKey> : List<T> { /* ... */ }

2️⃣ الگوی پیشرفته: Self-Referencing Generics 🤯

یکی از الگوهای خیلی قدرتمند و رایج، اینه که یک تایپ، یک اینترفیس جنریک رو با خودش به عنوان پارامتر نوعی، پیاده‌سازی کنه. این کار برای تعریف قراردادهایی مثل قابلیت مقایسه شدن (<IEquatable<T) عالیه و به شما ایمنی نوع کامل در زمان کامپایل میده.

مثال کتاب (Balloon):

public interface IEquatable<T> 
{
    bool Equals(T obj); 
}
// کلاس Balloon، قرارداد مقایسه شدن با یک Balloon دیگر را پیاده‌سازی می‌کند
public class Balloon : IEquatable
{
public string Color { get; set; }
public int CC { get; set; }

public bool Equals(Balloon b)
{
    if (b == null) return false;
    return b.Color == Color && b.CC == CC;
}
}

این الگو خیلی قدرتمنده و تو قیدهای جنریک هم استفاده میشه:

// این کلاس جنریک، فقط تایپ‌هایی رو به عنوان T قبول می‌کنه
// که خودشون قابل مقایسه با خودشون باشن!
class Foo<T> where T : IComparable<T> { /* ... */ }

🤔 حرف حساب و تجربه شما

ترکیب وراثت و جنریک‌ها به شما اجازه میده ساختارهای تایپی بسیار قدرتمند و انعطاف‌پذیری طراحی کنید که اساس خیلی از کتابخانه‌ها و فریم‌ورک‌های مدرن دات‌نت هستن.

🔖 هشتگ‌ها:
#CSharp #DotNet #OOP #Generics

چگونه Middlewareهای سفارشی در ASP.NET Core بسازیم 🔧

معماری middleware در ASP.NET Core راهی قدرتمند برای ساخت و پیکربندی پایپ‌لاین درخواست HTTP در اپلیکیشن‌های شما ارائه می‌دهد. در این پست، شما بررسی خواهید کرد که middleware چیست و چگونه middlewareهای سفارشی در ASP.NET Core بسازید.

Middleware در ASP.NET Core چیست؟ 🤔

میدلور در ASP.NET Core یک کامپوننت نرم‌افزاری است که بخشی از پایپ‌لاین اپلیکیشن است که درخواست‌ها و پاسخ‌ها را مدیریت می‌کند. در ASP.NET Core چندین middleware وجود دارد که با یکدیگر در یک زنجیره ترکیب شده‌اند. ⛓️

هر کامپوننت middleware در پایپ‌لاین مسئول فراخوانی کامپوننت بعدی در توالی است. هر middleware می‌تواند در صورت لزوم با short-circuit کردن زنجیره، اجرای middlewareهای دیگر را متوقف کند. Middlewareها در ASP.NET Core یک پیاده‌سازی کلاسیک از الگوی طراحی chain of responsibility هستند.

ASP.NET Core
تعداد زیادی middleware داخلی دارد و بسیاری نیز توسط پکیج‌های Nuget ارائه شده‌اند. ترتیبی که middlewareها به پایپ‌لاین اپلیکیشن اضافه می‌شوند، حیاتی است. ⚠️ این ترتیب تعریف می‌کند که چگونه درخواست‌های HTTP ورودی از طریق پایپ‌لاین عبور می‌کنند و پاسخ‌ها با چه توالی‌ای بازگردانده می‌شوند.

میدلور ها به ترتیبی که به پایپ‌لاین در آبجکت WebApplication اضافه شده‌اند، اجرا می‌شوند.

چگونه یک Middleware سفارشی در ASP.NET Core بسازیم ✍️

شما می‌توانید یک middleware سفارشی را به روش‌های زیر ایجاد کنید:

1️⃣ ارائه یک delegate برای متد Use در کلاس WebApplication.

2️⃣ ایجاد یک کلاس Middleware بر اساس قرارداد (by convention).

3️⃣ ایجاد یک کلاس Middleware با ارث‌بری از اینترفیس IMiddleware.

1️⃣ با یک متد Use در کلاس WebApplication

شما می‌توانید یک متد Use را روی کلاس WebApplication فراخوانی کنید تا یک middleware بسازید:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddConsole();
var app = builder.Build();

app.Use(async (context, next) =>
{
    Console.WriteLine("Request is starting...");
    await next();
    Console.WriteLine("Request has finished");
});

app.MapGet("/api/books", () =>
{
    var books = SeedService.GetBooks(10);
    return Results.Ok(books);
});

await app.RunAsync();

در این مثال هنگام فراخوانی یک endpoint به آدرس /api/books، ابتدا middleware تعریف شده در متد Use فراخوانی می‌شود. await next.Invoke() خودِ endpoint کتاب‌ها را فراخوانی می‌کند، اما قبل و بعد از آن ما یک پیام در کنسول لاگ کرده‌ایم:

Request is starting...
Request has finished

میدلور ها به ترتیبی که به پایپ‌لاین در آبجکت WebApplication اضافه شده‌اند، اجرا می‌شوند. هر middleware می‌تواند عملیاتی را قبل و بعد از middleware بعدی انجام دهد:

🔹 قبل: اجرای عملیات قبل از فراخوانی middleware بعدی می‌تواند شامل تسک‌هایی مانند لاگینگ، احراز هویت، اعتبارسنجی و غیره باشد.

🔹 بعد: عملیات پس از فراخوانی middleware بعدی می‌تواند شامل تسک‌هایی مانند تغییر پاسخ یا مدیریت خطا باشد.

قدرت واقعی middlewareها این است که شما می‌توانید آن‌ها را آزادانه به هر ترتیبی که می‌خواهید، زنجیره‌ای کنید. برای متوقف کردن اجرای درخواست و short-cut کردن زنجیره middleware (متوقف کردن اجرای middlewareهای دیگر) - یک پاسخ را مستقیماً در HttpContext بنویسید به جای فراخوانی متد await next.Invoke():

await context.Response.WriteAsync("Some response here");

2️⃣ با یک کلاس Middleware بر اساس قرارداد (By Convention)

شما می‌توانید یک middleware را به یک کلاس جداگانه که از قرارداد خاصی پیروی می‌کند، استخراج کنید:

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;

    public LoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        Console.WriteLine($"Request: {context.Request.Method} {context.Request.Path}");
        await _next(context);
        Console.WriteLine($"Response: {context.Response.StatusCode}");
    }
}

برای افزودن این middleware به پایپ‌لاین، متد UseMiddleware را روی کلاس WebApplication فراخوانی کنید:

app.Use(async (context, next) =>
{
    // Middleware از مثال قبلی
});

app.UseMiddleware<LoggingMiddleware>();

در نتیجه اجرای این middleware، موارد زیر هنگام اجرای یک endpoint به آدرس /api/books در کنسول لاگ خواهد شد:

Request is starting...
Request: GET /api/books
Response: 200
Request has finished

این رویکرد "بر اساس قرارداد" نامیده می‌شود، زیرا کلاس middleware باید از این قوانین پیروی کند:

✅ کلاس middleware باید یک متد InvokeAsync با یک آرگومان الزامی HttpContext داشته باشد.

✅ کلاس middleware باید یک RequestDelegate بعدی را در سازنده تزریق کند.

✅ کلاس middleware، delegate RequestDelegate بعدی را فراخوانی کرده و آرگومان HttpContext را به آن پاس دهد.

3️⃣ با یک کلاس Middleware که اینترفیس IMiddleware را پیاده‌سازی می‌کند 🛡

رویکرد قبلی معایب خود را دارد: توسعه‌دهنده باید یک کلاس middleware بسازد که از تمام قوانین ذکر شده در بالا پیروی کند، در غیر این صورت middleware کار نخواهد کرد. اما یک راه امن‌تر برای ایجاد middleware وجود دارد: پیاده‌سازی اینترفیس IMiddleware:

public class ExecutionTimeMiddleware : IMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        var watch = Stopwatch.StartNew();
        
        await next(context);
        
        watch.Stop();
        
        Console.WriteLine($"Request executed in {watch.ElapsedMilliseconds}ms");
    }
}

این رویکرد بسیار امن‌تر است زیرا کامپایلر به شما می‌گوید که کلاس middleware چگونه باید باشد.
برای این رویکرد شما باید به صورت دستی ExecutionTimeMiddleware را در کانتینر DI ثبت کنید:

builder.Services.AddScoped<ExecutionTimeMiddleware>();

برای افزودن این middleware به پایپ‌لاین، متد UseMiddleware را روی کلاس WebApplication فراخوانی کنید:

app.Use(async (context, next) =>
{
    // Middleware از مثال قبلی
});
app.UseMiddleware<LoggingMiddleware>();
app.UseMiddleware<ExecutionTimeMiddleware>();

در نتیجه اجرای این middleware، موارد زیر هنگام اجرای یک endpoint به آدرس /api/books در کنسول لاگ خواهد شد:

Request is starting...
Request: GET /api/books
Request executed in 68ms
Response: 200
Request has finished

میدلرور ها و تزریق وابستگی (Dependency Injection) 💉

میدلور هایی که بر اساس قرارداد ساخته می‌شوند، به طور پیش‌فرض طول عمر Singleton دارند و تمام وابستگی‌های تزریق شده در سازنده نیز باید singleton باشند. همانطور که می‌دانیم، middlewareها به ازای هر درخواست اجرا می‌شوند و شما می‌توانید وابستگی‌های scoped را در متد InvokeAsync بعد از HttpContext تزریق کنید. در اینجا ما یک ILoggingService را که به عنوان سرویس scoped در DI ثبت شده است، تزریق می‌کنیم:

builder.Services.AddScoped<ILoggingService, ConsoleLoggingService>();

در مرحله بعد:

public class LoggingMiddleware
{
    private readonly RequestDelegate _next;
    public LoggingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context, ILoggingService loggingService)
    {
        loggingService.LogRequest(context.Request.Method, context.Request.Path);
        await _next(context);
        loggingService.LogResponse(context.Response.StatusCode);
    }
}

این رویکرد فقط برای کلاس‌های middleware که بر اساس قرارداد ایجاد شده‌اند، مناسب است. برای تزریق سرویس‌های scoped به کلاس‌های middleware که اینترفیس IMiddleware را پیاده‌سازی می‌کنند، به سادگی از سازنده استفاده کنید:

public class ExecutionTimeMiddleware : IMiddleware
{
    private readonly ILoggingService _loggingService;
    public ExecutionTimeMiddleware(ILoggingService loggingService)
    {
        _loggingService = loggingService;
    }
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        // ...
    }
}

📌 نکته: هنگام ایجاد یک کلاس middleware که اینترفیس IMiddleware را پیاده‌سازی می‌کند - شما مسئول انتخاب یک طول عمر DI مناسب برای آن هستید. شما می‌توانید middleware را به صورت Singleton, Scoped یا Transient ایجاد کنید، آنچه را که در هر مورد استفاده بهترین است، انتخاب کنید.

خلاصه 📝

شما می‌توانید یک middleware سفارشی را به روش‌های زیر ایجاد کنید:

🔹 ارائه یک delegate برای متد Use در کلاس WebApplication.

🔹 ایجاد یک کلاس Middleware بر اساس قرارداد.

🔹 ایجاد یک کلاس Middleware با ارث‌بری از اینترفیس IMiddleware.

انتخاب ترجیحی من، ایجاد یک middleware با ارث‌بری از اینترفیس IMiddleware است. این رویکرد یک راه امن‌تر و راحت‌تر برای ایجاد middlewareها و یک استراتژی تزریق وابستگی سرراست از طریق سازنده ارائه می‌دهد. و همچنین کنترل کاملی بر روی طول عمر middleware به شما می‌دهد.

امیدوارم این مقاله برایتان مفید باشد.👋🏻

📖 سری آموزشی کتاب C# 12 in a Nutshell

🔬 نکات عمیق جنریک‌ها: Static Data و مقدار default

در دو پست قبلی، با قیدها و وراثت در دنیای جنریک‌ها آشنا شدیم. امروز در قسمت آخر این سری، به دو تا از نکات خیلی ظریف و فنی شیرجه می‌زنیم که رفتار جنریک‌ها رو در سطح حافظه و مقادیر پیش‌فرض نشون میده.

این نکات، درک شما رو از جنریک‌ها کامل می‌کنه.

1️⃣ مقدار پیش‌فرض T (default(T))

چطور می‌تونیم مقدار پیش‌فرض یک پارامتر جنریک T رو بدست بیاریم؟ چون T می‌تونه هر چیزی باشه (value type یا reference type)، ما نمی‌تونیم مستقیماً null یا 0 بهش بدیم.

راه حل #C، کلمه کلیدی default هست.

default(T)
به ما مقدار پیش‌فرض T رو میده:

🔹 اگه T یک Reference Type باشه، مقدارش null میشه.

🔹 اگه T یک Value Type باشه، مقدارش صفر میشه (نتیجه صفر کردن بیت‌های حافظه).

static void Zap<T>(T[] array)
{
    for (int i = 0; i < array.Length; i++)
    {
        // مقدار پیش‌فرض T را در آرایه قرار می‌دهد
        array[i] = default(T);
    }
}
// از #C 7.1 به بعد، می‌تونیم خلاصه‌تر بنویسیم:
// array[i] = default;

2️⃣ تله‌ی داده‌های استاتیک در جنریک‌ها ⚠️

این یکی از اون نکات خیلی مهمه که خیلی‌ها رو غافلگیر می‌کنه.

قانون اینه: داده‌های استاتیک (Static Fields/Properties) برای هر نوع بسته‌ی جنریک (Closed Type)، منحصر به فرد و جداگانه هستن.

یعنی static فیلدِ <Bob<int هیچ ربطی به static فیلدِ <Bob<string نداره و هر کدوم در حافظه، جای خودشون رو دارن.

مثال کتاب برای درک بهتر این موضوع:

class Bob<T> 
{
    public static int Count; 
}
// --- نتایج ---
Console.WriteLine(++Bob.Count);    // خروجی: 1 (شمارنده مخصوص int)
Console.WriteLine(++Bob.Count);    // خروجی: 2 (شمارنده مخصوص int)

Console.WriteLine(++Bob.Count); // خروجی: 1 (شمارنده مخصوص string، کاملاً جداست!)

Console.WriteLine(++Bob.Count); // خروجی: 1 (شمارنده مخصوص object، این هم جداست!)

🤔 حرف حساب و تجربه شما

این جزئیات فنی، نشون میده که جنریک‌ها در #C فقط یه جایگزینی ساده متن نیستن، بلکه یه مکانیزم قدرتمند در سطح CLR هستن که تایپ‌های کاملاً جدیدی رو در زمان اجرا تولید می‌کنن.

🔖 هشتگ‌ها:
#CSharp #DotNet #OOP #Generics #AdvancedCSharp

به نظرم یه پست دیگه در مورد Vertical Slice باید بریم هنوز جا داره✌🏻
پست امشب:
Vertical Slice Architecture Is Easier Than You Think🔥

معماری برش عمودی آسان‌تر از آن چیزی است که فکر می‌کنید 🔪

فرض کنید شما باید یک ویژگی "خروجی گرفتن از داده‌های کاربر" 📤 را به اپلیکیشن NET. خود اضافه کنید. کاربران روی یک دکمه کلیک می‌کنند، سیستم شما خروجی داده‌هایشان را تولید می‌کند، آن را در فضای ذخیره‌سازی ابری آپلود می‌کند و یک لینک دانلود امن به آن‌ها ایمیل می‌کند.

در معماری لایه‌ای فعلی شما با یک ساختار پوشه فنی، احتمالاً شش پوشه مختلف را لمس خواهید کرد: Controllers, Services, Models, DTOs, Repositories, و Validators. شما در solution explorer خود بالا و پایین اسکرول خواهید کرد، رشته افکار خود را از دست خواهید داد، و از خود خواهید پرسید که چرا افزودن یک ویژگی نیازمند ویرایش فایل‌هایی است که در سراسر پایگاه کد شما پراکنده شده‌اند. 🤯

اگر این برایتان آشنا به نظر می‌رسد، شما تنها نیستید. اکثر توسعه‌دهندگان NET. با معماری لایه‌ای "استاندارد" شروع می‌کنند، و کد را بر اساس دغدغه‌های فنی به جای ویژگی‌های بیزینسی سازماندهی می‌کنند.

اما یک راه بهتر وجود دارد: معماری برش عمودی. ✨

معماری برش عمودی چیست؟🤔

به جای سازماندهی کد خود بر اساس لایه‌های فنی (Controllers, Services, Repositories)، معماری برش عمودی آن را بر اساس ویژگی‌های بیزینسی سازماندهی می‌کند. هر ویژگی به یک "برش" خودکفا تبدیل می‌شود که شامل همه چیز مورد نیاز برای آن عملکرد خاص است.

اینطور به آن فکر کنید: معماری لایه‌ای سنتی مانند سازماندهی یک کتابخانه بر اساس اندازه یا رنگ کتاب است 📚، در حالی که برش‌های عمودی مانند سازماندهی بر اساس موضوع است. وقتی می‌خواهید در مورد تاریخ یاد بگیرید، نمی‌خواهید در کل کتابخانه جستجو کنید، شما تمام کتاب‌های تاریخ را در یک مکان می‌خواهید.

رویکرد سنتی در برابر برش‌های عمودی

بیایید به مثال خروجی داده ما نگاه کنیم. در اینجا نحوه ساختاردهی این ویژگی در یک پروژه معمولی NET. آمده است:

ساختار لایه‌ای سنتی: 👎

📁 Controllers/
└── UsersController.cs (export endpoint)
📁 Services/
├── IDataExportService.cs
├── DataExportService.cs
├── ICloudStorageService.cs
├── CloudStorageService.cs
├── IEmailService.cs
└── EmailService.cs
📁 Models/
├── ExportDataRequest.cs
└── ExportDataResponse.cs
📁 Repositories/
├── IUserRepository.cs
└── UserRepository.cs

حالا همان عملکرد که به صورت برش‌های عمودی سازماندهی شده است:

ساختار برش عمودی: 👍

📁 Features/
└──📁 Users/
   └──📁 ExportData/
      ├── ExportUserData.cs
      └── ExportUserDataEndpoint.cs
   📁 Create/
      └── CreateUser.cs
   📁 GetById/
      └── GetUserById.cs

پوشه ExportData شامل همه چیز مربوط به خروجی گرفتن از داده‌های کاربر است: درخواست، پاسخ، منطق بیزینس و endpoint API.

توجه داشته باشید که من هنوز هم ICloudStorageClient و IEmailSender را تزریق می‌کنم به جای اینکه آن منطق را مستقیماً در handler قرار دهم. این‌ها دغدغه‌های مشترک (cross-cutting concerns) واقعی هستند که چندین ویژگی از آن‌ها استفاده خواهند کرد. نکته کلیدی 🔑، تمایز بین "اشتراکی چون باید باشد" در مقابل "اشتراکی چون این الگو به من گفت" است.

کد را به من نشان بده 👨‍💻

من ابتدا بر اساس دامنه (Users) و سپس بر اساس ویژگی (ExportData) سازماندهی می‌کنم. 📂 برخی تیم‌ها مستقیماً Features/ExportUserData را ترجیح می‌دهند، اما من متوجه شده‌ام که گروه‌بندی دامنه زمانی که ویژگی‌های زیادی دارید، کمک می‌کند. ویژگی‌های مرتبط به صورت بصری گروه‌بندی شده باقی می‌مانند.

در اینجا ظاهر برش ویژگی (feature slice) خروجی داده ما با استفاده از یک request، handler و minimal APIها آمده است: 👇

Features/Users/ExportData/ExportUserData.cs

public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;

    public record Response(string DownloadUrl, DateTime ExpiresAt);

    public class Handler(
        AppDbContext dbContext,
        ICloudStorageClient storageClient,
        IEmailSender emailSender)
        : IRequestHandler<Request, Response>
    {
        public async Task<Response> Handle(Request request, CancellationToken ct = default)
        {
            // Get user data
            var user = await dbContext.Users
                .Include(u => u.Orders)
                .Include(u => u.Preferences)
                .FirstOrDefaultAsync(u => u.Id == request.UserId, ct);

            if (user == null)
            {
                throw new NotFoundException($"User {request.UserId} not found");
            }

            // Generate export data
            var exportData = new
            {
                user.Email,
                user.Name,
                user.CreatedAt,
                Orders = user.Orders.Select(o => new { o.Id, o.Total, o.Date }),
                Preferences = user.Preferences
            };

            // Upload to cloud storage
            var fileName = $"user-data-{user.Id}-{DateTime.UtcNow:yyyyMMdd}.json";
            var expiresAtUtc = DateTime.UtcNow.AddDays(7);

            var downloadUrl = await storageClient.UploadAsJsonAsync(
                fileName,
                exportData,
                expiresAtUtc,
                ct);

            // Send email notification
            await emailSender.SendDataExportEmailAsync(user.Email, downloadUrl, ct);

            return new Response(downloadUrl, expiresAtUtc);
        }
    }

    // Simple validation using FluentValidation
    public sealed class Validator : AbstractValidator<Request>
    {
        public Validator()
        {
            RuleFor(r => r.UserId).NotEmpty();
        }
    }
}

همه چیز مربوط به خروجی گرفتن از داده‌های کاربر در یک مکان قرار دارد: کوئری دیتابیس، اعتبارسنجی، منطق بیزینس، یکپارچه‌سازی با فضای ذخیره‌سازی ابری، و نوتیفیکیشن ایمیل.

endpoint Minimal API سرراست است: 👇

public static class ExportUserDataEndpoint
{
    public static void Map(IEndpointRouteBuilder app)
    {
        app.MapPost("/users/{userId}/export", async (
            Guid userId,
            IRequestHandler<ExportUserData.Request, ExportUserData.Response> handler) =>
        {
            var response = await handler.Handle(new ExportUserData.Request(userId));
            return Results.Ok(response);
        });
    }
}

ما حتی می‌توانستیم endpoint را داخل فایل ExportUserData.cs تعریف کنیم اگر می‌خواستیم همه چیز را کنار هم نگه داریم. این بیشتر یک موضوع ترجیح و قراردادهای تیمی است. هر دو رویکرد به خوبی کار می‌کنند. 👍

یک فایل در برابر چند فایل: انتخاب شما 📂 vs 🗂

شاید متوجه چیزی شده باشید: من همه چیز را در یک فایل واحد قرار دادم. این یک انتخاب طراحی با مزایا و معایب است.

رویکرد یک فایل (ExportUserData.cs):

public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;
    public record Response(string DownloadUrl, DateTime ExpiresAt);
    public class Handler : IRequestHandler<Request, Response> { /* ... */ }
    public class Validator : AbstractValidator<Request> { /* ... */ }
}

رویکرد چند فایل:

📁 ExportData/
├── ExportUserDataCommand.cs
├── ExportUserDataResponse.cs
├── ExportUserDataHandler.cs
├── ExportUserDataValidator.cs
└── ExportUserDataEndpoint.cs

یک فایل عالی است وقتی: ویژگی سرراست است، شما حداکثر نزدیکی و انسجام مکانی (locality) را می‌خواهید، و فایل از چند صد خط کد فراتر نمی‌رود.

تعداد خطوط کد یک قانون سختگیرانه نیست، اما اگر یک فایل فراتر از ۳۰۰-۴۰۰ خط رشد کند، برای خوانایی بهتر، تقسیم آن را در نظر بگیرید. باز هم، این یک موضوع ترجیح تیمی است و یک قانون سخت که من از آن پیروی کنم، نیست. مهم است که به غرایز خود و آنچه برای تیم شما درست به نظر می‌رسد، اعتماد کنید.

چند فایل بهتر کار می‌کند وقتی: شما منطق اعتبارسنجی پیچیده، چندین نوع پاسخ دارید، یا وقتی handler به اندازه‌ای بزرگ می‌شود که می‌خواهید هر بار روی یک دغدغه تمرکز کنید.

شما حتی می‌توانید هر دو رویکرد را در یک پروژه ترکیب کنید.

هر دو رویکرد کدهای مرتبط را کنار هم نگه می‌دارند. و این همان چیزی است که در معماری برش عمودی بیشترین اهمیت را دارد.

چرا این واقعاً کار می‌کند (و چگونه شروع کنیم) 🧠

مزایای برش‌های عمودی به محض اینکه آن را امتحان کنید، آشکار می‌شود. مغز شما نیازی ندارد به خاطر بسپارد که کدام فایل‌ها به کدام ویژگی‌ها مرتبط هستند. همه چیز با هم زندگی می‌کند.

نیاز به اصلاح ویژگی خروجی داده دارید؟ همه چیز در پوشه ExportData است. نیازی به جستجو در لایه‌های Controllers, Services, و Repositories نیست. هر برش می‌تواند به طور مستقل تکامل یابد، بنابراین عملیات ساده CRUD ساده باقی می‌مانند در حالی که ویژگی‌های پیچیده مانند خروجی داده می‌توانند از رویکردهای پیشرفته استفاده کنند.

شما نیازی ندارید کل اپلیکیشن خود را یک شبه بازنویسی کنید. 🚀 با ویژگی‌های جدید با استفاده از برش‌های عمودی شروع کنید. همانطور که به کدهای موجود دست می‌زنید، به تدریج قطعات مرتبط را به پوشه‌های ویژگی منتقل کنید.

معماری خوب یعنی آسان‌تر کردن درک و اصلاح پایگاه کد شما. وقتی تمام کدها برای یک ویژگی با هم زندگی می‌کنند، شما انرژی ذهنی کمتری را صرف ناوبری در سولوشن خود می‌کنید و زمان بیشتری را صرف حل مشکلات واقعی می‌کنید.

تمام این مفاهیم به هم گره خورده‌اند تا به شما در ساخت اپلیکیشن‌های NET. قابل نگهداری و مقیاس‌پذیر کمک کنند.

📖 سری آموزشی کتاب C# 12 in a Nutshell

🤯 تله‌ی کستینگ در جنریک‌ها: چرا کامپایلر گیج می‌شود و راه حل چیست؟

به این کد نگاه کنید. به نظر کاملاً منطقی میاد، ولی کامپایل نمیشه! چرا؟

StringBuilder Foo<T>(T arg)
{
    if (arg is StringBuilder)
        return (StringBuilder)arg; // ❌ خطای زمان کامپایل!
    // ...
}

امروز می‌خوایم یه نکته خیلی عمیق و فنی در مورد کست کردن پارامترهای جنریک (T) رو یاد بگیریم.

1️⃣ مشکل کجاست؟ ابهام در نوع تبدیل

مشکل اینه که کامپایلر در زمان کامپایل، نمی‌دونه T قراره چه نوعی باشه. وقتی شما می‌نویسید (SomeType)arg، کامپایلر نمی‌دونه منظور شما کدوم یکی از ایناست:

🔹 تبدیل عددی (Numeric)

🔹 تبدیل رفرنس (Reference)

🔹 تبدیل Boxing/Unboxing

🔹 تبدیل سفارشی (Custom)

این ابهام باعث میشه کامپایلر جلوی شما رو بگیره تا از خطاهای پیش‌بینی نشده جلوگیری کنه.

2️⃣ راه حل‌ها: شفاف‌سازی برای کامپایلر

برای رفع این ابهام، باید به کامپایلر بگیم دقیقاً منظورمون چه نوع تبدیلیه. دو راه حل اصلی وجود داره:

راه حل اول: استفاده از اپراتور as (برای Reference Typeها) ✅

اپراتور as فقط و فقط برای تبدیل‌های رفرنس استفاده میشه. چون ابهامی نداره، کامپایلر قبولش می‌کنه. اگه تبدیل شکست بخوره، null برمی‌گردونه.

StringBuilder Foo<T>(T arg)
{
    StringBuilder sb = arg as StringBuilder;
    if (sb != null) 
        return sb;
    // ...
}

راه حل دوم: کست کردن به object (راه حل عمومی) 🚀

راه حل عمومی‌تر که برای Value Typeها (Unboxing) هم کار می‌کنه، اینه که اول متغیر رو به object کست کنید. این کار به کامپایلر میگه "منظور من یه تبدیل رفرنس یا unboxing هست، نه عددی یا سفارشی".

برای Reference Type:

// کامپایلر می‌فهمه که منظور، تبدیل رفرنس است
return (StringBuilder)(object)arg;
برای Value Type:
______

// کامپایلر می‌فهمه که منظور، Unboxing است
int Foo<T>(T x) => (int)(object)x;

🤔 حرف حساب و تجربه شما

این یه نکته ظریف ولی خیلی مهمه که نشون میده کامپایلر #C چقدر به ایمنی نوع و رفع ابهام اهمیت میده.

🔖 هشتگ‌ها:
#CSharp #DotNet #OOP #Generics #AdvancedCSharp

📖 سری آموزشی کتاب C# 12 in a Nutshell

🧬 جنریک‌های پیشرفته: Covariance و راز تبدیل <IEnumerable<string به <IEnumerable<object

تا حالا براتون سوال شده چرا این کد در #C درسته:

IEnumerable<object> list = new List<string>();

ولی این کد خطا میده:

List<object> list = new List<string>();

جواب این سوال تو یه مفهوم پیشرفته و خیلی مهم به اسم Covariance نهفته‌ست.

1️⃣ Covariance چیست؟

به زبان ساده، Covariance میگه شما می‌تونید یه نوع جنریک با پارامتر فرزند (مثل <string>) رو به همون نوع جنریک با پارامتر پدر (مثل <object>) تبدیل کنید. (چون string یک نوع از object است).

این قابلیت در #C فقط برای اینترفیس‌ها و دلیگیت‌ها فعاله، نه برای کلاس‌ها.

2️⃣ چرا کلاس‌ها Covariant نیستن؟ (تله‌ی Type Safety) ⚠️

چرا نمی‌تونیم یه <List<Bear رو به <List<Animal تبدیل کنیم؟ چون اگه این کار مجاز بود، می‌تونستیم یه فاجعه منطقی به بار بیاریم و ایمنی نوع (Type Safety) رو که #C بهش افتخار می‌کنه، از بین ببریم:

class Animal { }
class Bear : Animal { }
class Camel : Animal { }
// لیستی از خرس‌ها
List bears = new List();

// ❌ خطای زمان کامپایل! اگر این خط مجاز بود...
// List animals = bears;

// ...اونوقت می‌تونستیم یه شتر رو تو لیست خرس‌ها بریزیم!
// animals.Add(new Camel()); // 💥 فاجعه در زمان اجرا!

برای جلوگیری از این خطای منطقی، کلاس‌های جنریک مثل <List<T که متدهای Add دارن (یعنی "نوشتنی" هستن)، به صورت پیش‌فرض Covariant نیستن. اما اینترفیسی مثل <IEnumerable<T که فقط "خواندنی" هست، می‌تونه Covariant باشه.

3️⃣ پس چطور با این محدودیت کار کنیم؟

حالا فرض کنید یه متد Wash داریم که می‌خواد یه لیستی از حیوانات رو بشوره. اگه ورودی رو <List<Animal بذاریم، نمی‌تونیم بهش <List<Bear پاس بدیم.

راه حل، جنریک کردن خود متد با استفاده از قیدهاست:

public class ZooCleaner
{
    // این متد، هر نوع لیستی رو قبول می‌کنه که T اون از Animal ارث برده باشه
    public static void Wash<T>(List<T> animals) where T : Animal 
    {
        foreach (T animal in animals)
        {
            Console.WriteLine($"Washing a {animal.GetType().Name}");
        }
    }
}
// --- نحوه استفاده ---
List bears = new List();
ZooCleaner.Wash(bears); // ✅ حالا درسته!

🤔 حرف حساب و تجربه شما

Covariance
یه مفهوم عمیقه که اساس کارکرد خیلی از اینترفیس‌های مهم دات‌نت مثل <IEnumerable<T هست. درک اون، شما رو به درک عمیق‌تری از سیستم تایپینگ #C می‌رسونه.

🔖 هشتگ‌ها:
#CSharp #DotNet #OOP #Generics #AdvancedCSharp

خودش serialize میکنه براتون.

مصرف‌کننده Idempotent - مدیریت پیام‌های تکراری 🛡

چه اتفاقی می‌افتد وقتی یک پیام دوباره تلاش (retry) می‌شود در یک سیستم رویداد-محور (event-driven)؟
این اتفاق بیشتر از آن چیزی که فکر می‌کنید، رخ می‌دهد.

بدترین سناریو 😱 این است که پیام دو بار پردازش شود، و عوارض جانبی (side effects) نیز می‌توانند بیش از یک بار اعمال شوند.

آیا می‌خواهید حساب بانکی شما دو بار شارژ شود؟ 💳
من فرض می‌کنم پاسخ منفی است، البته.

شما می‌توانید از الگوی مصرف‌کننده Idempotent برای حل این مشکل استفاده کنید.

در این مقاله به شما نشان خواهم داد:

🔹 الگوی مصرف‌کننده Idempotent چگونه کار می‌کند

🔹 چگونه یک مصرف‌کننده Idempotent را پیاده‌سازی کنیم

🔹 مزایا و معایبی که باید در نظر بگیرید

بیایید ببینیم چرا الگوی مصرف‌کننده Idempotent ارزشمند است.

الگوی مصرف‌کننده Idempotent چگونه کار می‌کند؟ 🤔
ایده پشت الگوی مصرف‌کننده Idempotent چیست؟

یک عملیات idempotent عملیاتی است که اگر بیش از یک بار با همان پارامترهای ورودی فراخوانی شود، هیچ تأثیر اضافی ندارد.

ما می‌خواهیم از مدیریت یک پیام یکسان بیش از یک بار، اجتناب کنیم.
این امر نیازمند تضمین تحویل پیام دقیقاً-یک‌باره (Exactly-once) از سیستم پیام‌رسانی ما خواهد بود. و این یک مشکل واقعاً سخت برای حل کردن در سیستم‌های توزیع‌شده است.

یک تضمین تحویل سست‌تر، حداقل-یک‌باره (At-least-once) است، که در آن ما آگاه هستیم که تلاش مجدد می‌تواند اتفاق بیفتد و می‌توانیم یک پیام یکسان را بیش از یک بار دریافت کنیم.

الگوی مصرف‌کننده Idempotent با تحویل پیام حداقل-یک‌باره به خوبی کار می‌کند و مشکل پیام‌های تکراری را حل می‌کند.

در اینجا الگوریتم از لحظه‌ای که ما یک پیام دریافت می‌کنیم، به این شکل است: ⚙️

1️⃣ آیا پیام قبلاً پردازش شده است؟

2️⃣ اگر بله، این یک پیام تکراری است و کاری برای انجام دادن وجود ندارد.

3️⃣ اگر نه، ما باید پیام را مدیریت کنیم.

4️⃣ ما همچنین باید شناسه پیام را ذخیره کنیم.

ما به یک شناسه منحصر به فرد 🆔 برای هر پیامی که دریافت می‌کنیم، و یک جدول در دیتابیس برای ذخیره پیام‌های پردازش شده نیاز داریم.

با این حال، جالب است که چگونه ما مدیریت پیام و ذخیره‌سازی شناسه پیام پردازش شده را پیاده‌سازی می‌کنیم.

شما می‌توانید مصرف‌کننده idempotent را به عنوان یک دکوراتور (decorator) 🎨 در اطراف یک message handler معمولی پیاده‌سازی کنید.

من دو پیاده‌سازی را به شما نشان خواهم داد:

🔹 مصرف‌کننده idempotent تنبل (Lazy)

🔹 مصرف‌کننده idempotent مشتاق (Eager)

مصرف‌کننده Idempotent تنبل (Lazy) 😴

مصرف‌کننده idempotent تنبل با جریانی که در الگوریتم بالا نشان داده شد، مطابقت دارد.
"تنبل" به نحوه ذخیره‌سازی شناسه پیام برای علامت‌گذاری آن به عنوان پردازش شده، اشاره دارد.

در مسیر خوشحال (happy path) ✅، ما پیام را مدیریت کرده و شناسه پیام را ذخیره می‌کنیم.
اگر message handler یک استثنا پرتاب کند 💥، ما هرگز شناسه پیام را ذخیره نمی‌کنیم و مصرف‌کننده می‌تواند دوباره اجرا شود.

در اینجا شکل پیاده‌سازی آمده است: 👇

public class IdempotentConsumer<T> : IHandleMessages<T>
    where T : IMessage
{
    private readonly IMessageRepository _messageRepository;
    private readonly IHandleMessages<T> _decorated;

    public IdempotentConsumer(
        IMessageRepository messageRepository,
        IHandleMessages<T> decorated)
    {
        _messageRepository = messageRepository;
        _decorated = decorated;
    }

    public async Task Handle(T message)
    {
        if (_messageRepository.IsProcessed(message.Id))
        {
            return;
        }
        
        await _decorated.Handle(message);
        
        _messageRepository.Store(message.Id);
    }
}

مصرف‌کننده Idempotent مشتاق (Eager) 💪

مصرف‌کننده idempotent مشتاق کمی با پیاده‌سازی تنبل متفاوت است، اما نتیجه نهایی یکسان است.

در این نسخه، ما مشتاقانه شناسه پیام را در دیتابیس ذخیره کرده و سپس به مدیریت پیام ادامه می‌دهیم.

اگر handler یک استثنا پرتاب کند، ما باید در دیتابیس پاک‌سازی انجام داده و شناسه پیام ذخیره شده مشتاقانه را حذف کنیم.
در غیر این صورت، ما با ریسک رها کردن سیستم در یک وضعیت ناسازگار مواجه می‌شویم، زیرا پیام هرگز به درستی مدیریت نشده است.

در اینجا شکل پیاده‌سازی آمده است:

public class IdempotentConsumer<T> : IHandleMessages<T>
    where T : IMessage
{
    private readonly IMessageRepository _messageRepository;
    private readonly IHandleMessages<T> _decorated;

    public IdempotentConsumer(
        IMMessageRepository messageRepository,
        IHandleMessages<T> decorated)
    {
        _messageRepository = messageRepository;
        _decorated = decorated;
    }

    public async Task Handle(T message)
    {
        try
        {
            if (_messageRepository.IsProcessed(message.Id))
            {
                return;
            }
            
            _messageRepository.Store(message.Id);
            
            await _decorated.Handle(message);
        }
        catch (Exception e)
        {
            _messageRepository.Remove(message.Id);
            throw;
        }
    }
}

به طور خلاصه 📝

Idempotency
یک مشکل جالب برای حل کردن در یک سیستم نرم‌افزاری است.
برخی عملیات به طور طبیعی idempotent هستند و ما به سربار (overhead) الگوی مصرف‌کننده Idempotent نیازی نداریم.
با این حال، برای آن دسته از عملیاتی که به طور طبیعی idempotent نیستند، مصرف‌کننده Idempotent یک راه‌حل عالی است.

الگوریتم سطح بالا ساده است و شما می‌توانید دو رویکرد را در پیاده‌سازی در پیش بگیرید:

🔹 ذخیره‌سازی تنبل (Lazy) شناسه‌های پیام

🔹 ذخیره‌سازی مشتاق (Eager) شناسه‌های پیام

من ترجیح می‌دهم از رویکرد تنبل استفاده کنم، و فقط شناسه پیام را در دیتابیس زمانی ذخیره کنم که handler با موفقیت کامل شود.
استدلال در مورد آن آسان‌تر است و یک فراخوانی کمتر به دیتابیس وجود دارد.

ممنون برای مطالعه.
امیدوارم که مفید بوده باشد. 👋

حساسیت خوبه،ولی به موقع‌ش👍🏻