‫نوع‌های اتحادیه (Union Types) در C# 15 و NET 11.

// کنترل جریان برنامه از طریق پرتاب استثنا (رویکرد سنتی)
public User GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : throw new UserNotFoundException(id);

• پنهان‌کاری در امضای متد (Method Signature): توسعه‌دهنده‌ای که این متد را فراخوانی می‌کند، بدون مطالعه بدنه متد یا مستندات، متوجه رفتار ناهمگام یا خطاهای احتمالی آن نخواهد شد.
• کاهش عملکرد و انحراف از مفهوم استثنا: استفاده از استثناها برای کنترل جریان عادی برنامه (Control Flow via Exceptions) هزینه پردازشی بالایی دارد، زیرا فرآیند پشته‌گشایی (Stack Unwinding) سنگین است. استثناها باید صرفاً برای شرایط غیرمنتظره و بحرانی سیستم استفاده شوند، نه برای سناریوهای منطقی کسب‌وکار مانند یافت نشدن یک رکورد.

public union Result<T>(T, Exception);

public record CreditCard(string Last4, string Brand);
public record PayPal(string Email);
public record BankTransfer(string Iban);

public union PaymentMethod(CreditCard, PayPal, BankTransfer);

PaymentMethod method = new CreditCard("4242", "Visa");

string Describe(PaymentMethod method) => method switch
{
    CreditCard card  => $"{card.Brand} ending {card.Last4}",
    PayPal paypal    => $"PayPal ({paypal.Email})",
    BankTransfer ach => $"Bank transfer to {ach.Iban}",
}; // بدون نیاز به بخش default یا دیسکارد (_)

warning CS8509: The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern 'BankTransfer' is not covered.

public record NotFound(int Id);
public union UserResult(User, NotFound);

public UserResult GetUser(int id) =>
    _users.TryGetValue(id, out var user)
        ? user
        : new NotFound(id);

IResult response = GetUser(42) switch
{
    User user      => Results.Ok(user),
    NotFound found => Results.NotFound($"No user with id {found.Id}"),
};

• پیاده‌سازی در سطح ساختار (Struct-based Compiler Representation): در پشت صحنه، کامپایلر یک Union را به یک struct تبدیل می‌کند. این ساختار حاوی یک فیلد متمایزکننده (Discriminator/Tag) برای تشخیص نوع فعلی و یک ارجاع تخصیص‌یافته به داده است.
• مدیریت حافظه و Boxing: در حالت پیش‌فرض، مقادیرِ نوعِ مرجع (Reference Types) و نوع‌های مقدار (Value Types) ممکن است درون یک فیلد مشترک نظیر object? ذخیره شوند که این امر برای انواع ساختاری منجر به بروز پدیده Boxing می‌شود. با این حال، تیم توسعه دات‌نت در حال توسعه یک مسیر بهینه‌سازی بدون نیاز به Boxing (Non-boxing path) با استفاده از الگوهای پیشرفته‌تر چیدمان حافظه (LayoutKind.Explicit) برای کدهای با کارایی بالا (Performance-sensitive) است.
• تفاوت با Discriminated Unions جامع: شایان ذکر است که ویژگی فعلی در C# 15 یک Type Union (اتحادیه‌ای از انواع موجود) است و هنوز به یک Discriminated Union کامل (همراه با برچسب‌های نام‌گذاری شده اختصاصی در یک ساختار درختی واحد، مشابه زبان F# یا Rust) تبدیل نشده‌است. با این حال، این پیاده‌سازی بیش از ۹۰ درصد نیازهای روزمره توسعه‌دهندگان را پوشش می‌دهد.

Public Function LookupCustomer(ByVal customerID As Long) As Variant
    Dim rs As ADODB.Recordset
    On Error GoTo ErrorHandler

    Set rs = New ADODB.Recordset
    rs.Open "SELECT * FROM Customers WHERE ID = " & customerID, _
            gConnection, adOpenStatic, adLockReadOnly

    If rs.EOF Then
        LookupCustomer = Empty
    Else
        LookupCustomer = Array(rs!CustomerName, rs!CreditLimit, rs!Status)
    End If

    rs.Close
    Exit Function

ErrorHandler:
    LookupCustomer = "ERROR: " & Err.Description
End Function

• پرتاب استثنا برای حالت «پیدا نشد»؛ که از نظر معنایی نادرست است.
• استفاده از Tuple nullable یا چندین پارامتر خروجی.
• ایجاد کلاس نتیجه سفارشی با یک enum تشخیص‌دهنده (Discriminator)؛ که بسیار پرحجم و فاقد پشتیبانی کامپایلری قوی بود.

public union CustomerLookupResult
{
    Customer(string Name, decimal CreditLimit, CustomerStatus Status);
    NotFound;
    Error(string Message);
}

public CustomerLookupResult LookupCustomer(long customerId)
{
    try
    {
        using var connection = new SqlConnection(_connectionString);
        connection.Open();

        using var command = new SqlCommand(
            "SELECT Name, CreditLimit, Status FROM Customers WHERE Id = @id", 
            connection);

        command.Parameters.AddWithValue("@id", customerId);
        using var reader = command.ExecuteReader();

        if (!reader.Read())
            return new CustomerLookupResult.NotFound();

        return new CustomerLookupResult.Customer(
            reader.GetString(0),
            reader.GetDecimal(1),
            Enum.Parse<CustomerStatus>(reader.GetString(2)));
    }
    catch (SqlException ex)
    {
        return new CustomerLookupResult.Error(ex.Message);
    }
}

var result = LookupCustomer(12345);

var message = result switch
{
    CustomerLookupResult.Customer c => 
        $"Found {c.Name}, credit limit {c.CreditLimit:C}",
    CustomerLookupResult.NotFound => "No customer with that ID",
    CustomerLookupResult.Error e => $"Lookup failed: {e.Message}"
};

• Minimal APIs: شما می‌توانید از نوع‌های اتحادی مستقیماً به عنوان پارامتر ورودی یا خروجی متدها استفاده کنید. این پشتیبانی هم در بخش زمان اجرا (RequestDelegateFactory) و هم در لایه‌ی سورس‌جنراتورها (Source-Generated Request Delegates) پیاده‌سازی شده است. همچنین ساختارهایی مثل Task، IAsyncEnumerable و Results به طور کامل پوشش داده شده‌اند.
• MVC و Razor Pages: مدل‌سازی داده‌ها در بدنه درخواست‌ها و پاسخ‌های JSON در کنترلرهای سنتی به راحتی با Union Typeها ممکن است.
• SignalR: در صورت استفاده از پروتکل JSON Hub، می‌توانید از اتحادیه‌ها به عنوان پارامتر متدهای هاب، مقادیر بازگشتی و آیتم‌های استریم (Stream Items) استفاده کنید.
• Blazor: در دنیای فرانت‌اند دات‌نت، اتحادیه‌ها می‌توانند به عنوان پارامترهای کامپوننت، آرگومان‌ها و نتایج ارتباط با جاوااسکریپت (JS Interop) و همچنین برای ذخیره‌سازی وضعیت کامپوننت‌ها (Persisted Component State) به کار گرفته شوند.

// فعال‌سازی نسخه پیش‌نمایش در فایل پروژه الزامی است: preview 
public record class Dog(string Name); 
public record class Cat(int Lives); 
public union Pet(Dog, Cat);

// خروجی بر اساس منطق برنامه می‌تواند سگ یا گربه باشد 
app.MapGet("/pets/{id}", Pet (int id) => id == 0 ? new Dog("Rex") : new Cat(9));

{"Name":"Rex"}

• در حالت فعال بودن رشته: "hello"
• در حالت فعال بودن عدد: 42

• سازنده‌های غیرعمومی (Non-public Constructors): اعلان‌های اتحادیه اکنون می‌توانند از سازنده‌های غیرعمومی (مانند private یا internal) که تنها یک پارامتر می‌گیرند استفاده کنند.
• اصلاح الگوی Not (Not Pattern): الگوی not در انطباق الگو (Pattern Matching) اکنون به خودِ مقدار ورودی اتحادیه اعمال می‌شود، نه به ارزش درونی آن.
• ارث‌بری متدهای ساخت: نوع‌های اتحادی سفارشی (Custom Union Types) اکنون از ارث‌بری متدهای تولید شده‌ی Create پشتیبانی می‌کنند.
• خطاهای صریح زمان کامپایل: اگر در اعلان یک اتحادیه سفارشی، حداقل مجموعه APIهای مورد نیاز وجود نداشته باشد، کامپایلر خطاهای بسیار شفاف و دقیقی را گزارش می‌کند تا توسعه‌دهنده سردرگم نشود.

• Union Types: نوعی پیوند بدون وراثت بین چند تایپ کاملاً بی‌ارتباط با یکدیگر است.
• Closed Class: کلاسی پایه که ذاتاً شبیه یک کلاس انتزاعی (abstract) رفتار می‌کند، اما اجازه ارث‌بری از آن تنها در درون همان اسمبلی (Assembly) ممکن است. تلاش برای ارث‌بری از کلاسی با نشانگر closed خارج از اسمبلی منجر به خطای کامپایل (CS9382) خواهد شد.

• سطح دسترسی (Accessibility): تمام کلاس‌های فرزند استنتاج‌شده باید دست‌کم هم‌سطح کلاس پایه باشند (کلاس فرزند نمی‌تواند internal باشد اگر کلاس والد public است).
• سلسله‌مراتب چندلایه‌ای (Nested Hierarchies): در صورتی که ساختار وراثت بیش از یک لایه عمق داشته باشد (مثلاً کلاس فرزند واسطه‌ای خودش closed یا abstract باشد)، استنتاج خودکار با خطا مواجه می‌شود و توسعه‌دهنده کماکان ناچار است از اتریبیوت‌های صریح [JsonDerivedType] به همراه تفکیک‌کننده $type استفاده کند.

• نوع IntOrString(42) دقیقاً به صورت عدد 42 نوشته می‌شود، نه { "Value": 42 }.
• نوع Windows("11") به صورت شیء {"Version": "11"} ذخیره می‌گردد.

// این اتحادیه‌ها به درستی Deserialized می‌شوند (عدم تداخل توکن)
public union IntOrString(int, string);        // Number در برابر String
public union DoubleOrGuid(double, Guid);      // Number در برابر String
public union BoolOrDict(bool, Dictionary);     // Boolean در برابر Object

// این اتحادیه‌ها به صورت پیش‌فرض در مرحله Deserialization شکست می‌خورند!
public union Pet(Cat, Dog);                  // هر دو به صورت Object ذخیره می‌شوند
public union SupportedOS(Windows, Linux, MacOS); // هر سه به صورت Object ذخیره می‌شوند
public union Num(int, long);                  // هر دو توکن Number تولید می‌کنند
public union When(DateTime, DateTimeOffset);  // هر دو توکن String تولید می‌کنند

public class SupportedOSClassifier : JsonTypeClassifierFactory<SupportedOS>
{
    public override JsonTypeClassifier CreateJsonClassifier(
        JsonTypeClassifierContext context, JsonSerializerOptions options)
    {
        return static (ref Utf8JsonReader reader) =>
        {
            if (reader.TokenType is not JsonTokenType.StartObject)
                return null;

            bool sawVersion = false;

            while (reader.Read() && reader.TokenType is not JsonTokenType.EndObject)
            {
                // این فیلدها در هر کلاس منحصربه‌فرد هستند
                if (reader.ValueTextEquals("Distro"u8)) return typeof(Linux);
                if (reader.ValueTextEquals("Name"u8)) return typeof(MacOS);

                if (reader.ValueTextEquals("Version"u8))
                    sawVersion = true;

                reader.Read(); // رفتن به سمت مقدار
                reader.Skip(); // رد کردن مقدار فیلد
            }

            return sawVersion ? typeof(Windows) : null;
        };
    }
}

// انتساب کلاس‌بند به اتحادیه
[JsonUnion(TypeClassifier = typeof(SupportedOSClassifier))]
public union SupportedOS(Windows, Linux, MacOS);

• بار پردازشی (Performance Penalty): بررسی تفاوت نام فیلدها قبل از ساخت شیء، نیازمند اسکن بایت‌های اولیه JSON در حافظه است که عملکرد پردازشی را کاهش می‌دهد.
• نیاز به فیلدهای متمایز و الزامی: اگر کلاس‌های موجود در اتحادیه هیچ فیلد انحصاری نداشته باشند، یا فیلدهای اختصاصی به عنوان required یا [JsonRequired] تعریف نشده باشند، طبقه‌بندی ساختاری همچنان در ابهام باقی می‌ماند:

// جهت تضمین عملکرد طبقه‌بند ساختاری خودکار:
public record Windows([property: JsonRequired] string Version);
public record Linux([property: JsonRequired] string Distro, string Version);
public record MacOS([property: JsonRequired] string Name, int Version);

چکیده: با معرفی اولیه و آزمایشی انواع اجتماع (Discriminated Unions / Union Types) در نسخه پیش‌نمایش #C 15 و پلتفرم NET 11.، زبان سی‌شارپ گام بلندی به‌سوی سیستم‌های نوع‌بندی جبری (Algebraic Data Types) و همگامی با الگوهای برنامه‌نویسی تابعی مدرن برداشته است. بااین‌حال، در نگارش‌های نخستین این ویژگی، قابلیت داخلی زبان یا API مستقیمی برای استخراج فهرستی از کلیه حالت‌های معتبر یک نوع اجتماع (Case Types) در زمان اجرا یا کامپایل بدون بررسی دستی پیش‌بینی نشده است. این مقاله با تکیه بر ساختار کامپایلر Roslyn و پیاده‌سازی زیربنایی رابط IUnion، متدهای توسعه‌یافته‌ای (Extension Methods) مبتنی بر Reflection ارائه می‌دهد که امکان کشف پویا و استاتیک حالت‌های تشکیل‌دهنده Union را فراهم می‌سازد. همچنین ضمن تحلیل چالش‌های عملکردی Reflection سنتی، راهکارهای بهینه‌سازی از جمله کش‌گذاری حافظه و استفاده از مولدهای سورس (Source Generators) به‌عنوان راهکار جایگزین مورد ارزیابی قرار می‌گیرند.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net11.0</TargetFramework>
    <LangVersion>preview</LangVersion>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>

• پیش‌نمایش SDK نسخه .NET 11
• نسخه Visual Studio Code Insiders
• آخرین ویرایش افزونه‌های C# Dev Kit و C# در حالت پیش‌نمایش

public record Dog(string Name);
public record Cat(int NumberOfLives, string? Name = default);
public record Parrot(bool WantsCrackers, string? Name = default);
public record GoldFish(bool MakesBubbles, string? Name = default);

// تعریف Union در C# 15
public union Pet(Dog, Cat, Parrot, GoldFish)
{
    public string Description => this switch
    {
        Dog dog => $"Bark Bark! {dog.Name} says! 🦴 🐕",
        Cat cat => $"{cat.Name} says: Meow! I got {cat.NumberOfLives} lives left 🐈",
        Parrot parrot => $"🦜 Squawk! {parrot.Name} says: {(parrot.WantsCrackers ? "I want crackers!" : "Give us a kiss!")}",
        GoldFish goldFish => $"🐠 {goldFish.Name} says: Blub Blub! {(goldFish.MakesBubbles ? "I make bubbles!" : "I don't make bubbles!")}"
    };
}

• Pet(Dog caseValue)
• Pet(Cat caseValue)
• Pet(Parrot caseValue)
• Pet(GoldFish caseValue)

using System.Reflection;

namespace System.Runtime.CompilerServices;

/// <summary>
/// ابزارهای کمکی مبتنی بر Reflection برای کاوش در ساختار انواع Union در C# 15
/// </summary>
public static class UnionExtensions
{
    /// <summary>
    /// استخراج انواع حالت‌های معتبر در زمان کامپایل از طریق پارامتر جنریک
    /// </summary>
    public static IReadOnlyList<Type> GetCaseTypes<TUnion>() where TUnion : IUnion
    {
        return GetUnionCaseTypes(typeof(TUnion));
    }

    /// <summary>
    /// استخراج پویای انواع حالت‌های معتبر در زمان اجرا بر اساس شیء Type
    /// </summary>
    public static IReadOnlyList<Type> GetUnionCaseTypes(this Type? type)
    {
        // بررسی ایمن نوع: در صورت نامعتبر بودن یا عدم پیاده‌سازی IUnion، آرایه تهی بازگردانده می‌شود
        if (type is null || !typeof(IUnion).IsAssignableFrom(type))
        {
            return Array.Empty<Type>();
        }

        return type
            .GetConstructors(BindingFlags.Public | BindingFlags.Instance)
            .Where(ctor => ctor.GetParameters().Length == 1)
            .Select(ctor => ctor.GetParameters()[0].ParameterType)
            .Distinct()
            .ToArray();
    }
}

public class Program
{
    public static void Main()
    {
        // ۱. استخراج استاتیک از طریق متد جنریک
        var caseNames = UnionExtensions.GetCaseTypes<Pet>().Select(t => t.Name);
        Console.WriteLine($"Pet union cases: {string.Join(", ", caseNames)}");

        // ۲. تست الگوهای تطبیق و رفتار مشترک
        Pet[] pets = [
            new Dog("Rex"),
            new Cat(7, "Whiskers"),
            new Parrot(true, "Polly"),
            new GoldFish(true, "Timmy")
        ];

        foreach (var pet in pets)
        {
            Console.WriteLine(pet.Description);
        }

        Console.WriteLine("\nListing all pet union case types with properties:");
        Console.WriteLine(new string('-', 50));

        // ۳. استخراج پویا و بررسی فراداده‌های هر حالت
        foreach (var caseType in typeof(Pet).GetUnionCaseTypes())
        {
            var propNames = caseType
                .GetProperties(BindingFlags.Instance | BindingFlags.Public)
                .Select(p => p.Name);

            Console.WriteLine($"* {caseType.Name,-10} => Props: {string.Join(", ", propNames)}");
        }
    }
}

Pet union cases: Dog, Cat, Parrot, GoldFish
Bark Bark! Rex says! 🦴 🐕
Whiskers says: Meow! I got 7 lives left 🐈
🦜 Squawk! Polly says: I want crackers!
🐠 Timmy says: Blub Blub! I make bubbles!

Listing all pet union case types with properties:
--------------------------------------------------
* Dog        => Props: Name
* Cat        => Props: NumberOfLives, Name
* Parrot     => Props: WantsCrackers, Name
* GoldFish   => Props: MakesBubbles, Name

private static readonly ConcurrentDictionary<Type, IReadOnlyList<Type>> _caseCache = new();

public static IReadOnlyList<Type> GetUnionCaseTypesCached(this Type type)
{
    return _caseCache.GetOrAdd(type, t => t.GetUnionCaseTypes());
}

چکیده: یکی از چالش‌های مکرر در طراحی رابط‌های برنامه‌نویسی (API Design) در زبان #C، نیاز به پشتیبانی هم‌زمان از یک شیء منفرد و مجموعه‌ای از اشیاء است. رویکرد مرسوم برای حل این مسئله، ارائه چندریختی یا اورلودهای متعدد متدها (Overloads Explosion) است که منجر به پیچیدگی و افزونگی کد می‌شود. با مطرح شدن و پیشرفت طرح انواع اجتماعی تفکیک‌شده (Discriminated Unions) در سی‌شارپ مدرن، قابلیت تعریف بدنه برای انواع اجتماعی (Unions with Bodies) امکان غنی‌سازی این ساختارها با متدهای کمکی و اعضای سفارشی را فراهم کرده است. در ادامه، ساختار اتحادیه‌های دارای بدنه، پیاده‌سازی الگوی OneOrMore، مدیریت حالت‌های پوچ‌پذیری (Nullability) و وضعیت مقدار پیش‌فرض (Default State) بررسی می‌شود؛ همچنین مقایسه‌ای فنی میان این رویکرد نوین و راهکارهای سنتی مبتنی بر اورلود متدها ارائه خواهد شد.

// رویکرد سنتی: انفجار اورلودها
public void ApplyTags(string tag) { /* ... */ }
public void ApplyTags(IEnumerable<string> tags) { /* ... */ }
public void ApplyTags(params string[] tags) { /* ... */ }

public union OneOrMore<T>(T, IEnumerable<T>)
{
    public IEnumerable<T> AsEnumerable() => Value switch
    {
        T single => [single],
        IEnumerable<T> multiple => multiple,
        null => []
    };
}

// ارسال یک مقدار منفرد
OneOrMore<string> tags = "dotnet";

// ارسال یک آرایه یا مجموعه
OneOrMore<string> moreTags = new[] { "csharp", "unions", "preview" };

// پردازش یکپارچه در سمت متد
public void ProcessTags(OneOrMore<string> input)
{
    foreach (var tag in input.AsEnumerable())
    {
        Console.WriteLine(tag);
    }
}

null => []

• وضعیت پیش‌فرض مشخصه درونی Value در Union، حالت شاید پوچ (maybe-null) است. این قاعده تحلیلی کامپایلر را قادر می‌سازد تا هشدارهای مربوط به Nullability را در موارد زیر به‌درستی صادر کند:
• تعریف آرایه‌ای از Unionها (مانند OneOrMore) که عناصر اولیه آن‌ها مقداردهی نشده‌اند.
• نمونه‌های پیش‌فرض ناشی از انواع مقداری (default(OneOrMore).

• اگر ساختار زیرین به شکل struct پیاده‌سازی شود، ایجاد ساختار با کلیدواژه default هیچ‌کدام از شاخه‌های معتبر (T یا IEnumerable) را مقداردهی نمی‌کند. شاخه null => [] تضمین می‌کند که اجرای متد تحت هیچ شرایطی با شکست مواجه نشده و همواره یک دنباله خالی اما معتبر بازگردانده شود.

• در شاخه T single => [single]، استفاده از سینتکس Collection Expressions در صورت هدف‌گیری آرایه‌ها ممکن است برای مقادیر منفرد تخصیص حافظه کوچک ایجاد کند. در سناریوهای با کارایی بسیار بالا، پیاده‌سازی یک Enumerator سفارشی بر پایه struct برای پیمایش بدون تخصیص حافظه (Zero-allocation) گزینه‌ای ایده‌آل است.

• چنانچه نوع پایه T یک ساختار (struct) باشد، تفاوت رفتار بین مقدار پیش‌فرض default(T) و null باید در منطق دامنه در نظر گرفته شود.