الانعكاس والسمات في C#: typeof وGetType والسمات المخصصة

يتيح الانعكاس (reflection) لبرنامج فحص الأنواع أثناء عمله: أي خصائص للصنف، وما قيمها، وأي دوال موجودة، وأي سمات مرفقة. والسمات (attributes) هي النصف الآخر: وسوم تصريحية بين أقواس مربعة، مثل [Obsolete] أو [JsonPropertyName("id")]، لا تعني شيئًا بذاتها حتى يقرأها المترجم أو شيفرة ما بالانعكاس. أدوات التسلسل وأدوات ORM ومكتبات التحقق وأطر الاختبار وتوجيه ASP.NET كلها تعمل بهذه الطريقة.

نادرًا ما تحتاج معظم شيفرة التطبيقات إلى الانعكاس مباشرة، لكن معرفة طريقة عمله تشرح كثيرًا من سلوك الأطر.

كائنات Type: typeof وGetType

كل شيء يبدأ من System.Type. هناك طريقتان للحصول على واحد:

using System;

class Employee { public string Name { get; set; } }
class Manager : Employee { public int Reports { get; set; } }

class Program
{
    static void Main()
    {
        Type t1 = typeof(Employee);          // from a type name, at compile time
        Employee e = new Manager();
        Type t2 = e.GetType();               // from an object, at run time

        Console.WriteLine(t1.Name);
        Console.WriteLine(t2.Name);          // the real type, not the variable's type
        Console.WriteLine(t2.BaseType.Name);

        Console.WriteLine(e.GetType() == typeof(Employee));   // exact type check
        Console.WriteLine(e is Employee);                     // "is it an Employee or derived?"
        Console.WriteLine(typeof(Employee).IsAssignableFrom(t2));

        Console.WriteLine(typeof(int).FullName);
        Console.WriteLine(typeof(string).IsValueType);
        Console.WriteLine(nameof(Employee.Name));             // compile-time name, no reflection
    }
}

المخرجات:

Employee
Manager
Employee
False
True
True
System.Int32
False
Name

الفرق الذي يجب تذكّره: typeof(X) تسمّي نوعًا تعرفه حين تكتب الشيفرة، وobj.GetType() تسأل كائنًا عمّا هو حقًا. مقارنة GetType() == typeof(Employee) تطابق تام يفشل مع الأصناف المشتقة، وهذا عادة ليس ما تريده؛ أما is وIsAssignableFrom فتحترمان الوراثة. وnameof تبدو مشابهة لكنها ليست انعكاسًا إطلاقًا: يستبدلها المترجم بثابت نصي.

استدعاء GetType() على مرجع null يرمي NullReferenceException، لأنه لا كائن لتسأله. وعلى نوع قيمة قابل لـ null مغلّف تعيد النوع الأساسي: ((int?)5).GetType() هي System.Int32.

قراءة الخصائص وضبطها

تسرد GetProperties() الخصائص العامة لنوع ككائنات PropertyInfo، يستطيع كل منها قراءة القيمة وكتابتها على مثيل معين:

using System;
using System.Reflection;

class Product
{
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int Stock { get; set; }
    private string supplierCode = "SUP-77";
}

class Program
{
    static void Main()
    {
        var mug = new Product { Name = "Mug", Price = 8.50m, Stock = 12 };
        Type type = mug.GetType();

        foreach (PropertyInfo p in type.GetProperties())
            Console.WriteLine($"{p.Name,-6} {p.PropertyType.Name,-8} = {p.GetValue(mug)}");

        PropertyInfo price = type.GetProperty("Price");
        price.SetValue(mug, 7.90m);
        Console.WriteLine(mug.Price);

        Console.WriteLine(type.GetProperty("Colour") == null);   // no such property

        FieldInfo hidden = type.GetField("supplierCode", BindingFlags.NonPublic | BindingFlags.Instance);
        Console.WriteLine(hidden.GetValue(mug));
    }
}

المخرجات:

Name   String   = Mug
Price  Decimal  = 8.50
Stock  Int32    = 12
7.90
True
SUP-77

ثلاثة أمور يُظهرها هذا:

• تعيد GetValue قيمة object، فتعود أنواع القيم مغلّفة وتحوّلها لتستخدمها.
• تعيد GetProperty باسم غير موجود null، ويرمي الاستدعاء التالي عليها NullReferenceException. افحص قبل الاستخدام.
• يصل BindingFlags.NonPublic | BindingFlags.Instance إلى الأعضاء الخاصة. وهذا مشروع في الأدوات والاختبارات، لكنه يتجاوز التغليف وينكسر بصمت حين يُعاد هيكلة الصنف.

هذه الحلقة هي في جوهرها طريقة عمل مصدّر CSV أو أداة تسلسل من كائن إلى JSON: امشِ على الخصائص، واقرأ كل قيمة، ونسّقها.

استدعاء الدوال وإنشاء الكائنات بالاسم

تجد GetMethod دالة، وتستدعيها Invoke بمصفوفة وسائط. وتنشئ Activator.CreateInstance كائنًا من Type، وهكذا تبني أنظمة الإضافات وحاويات حقن الاعتماديات أنواعًا تُختار وقت التشغيل:

using System;
using System.Reflection;

class PriceCalculator
{
    public decimal Rate { get; set; } = 0.20m;
    public decimal WithTax(decimal net) => net * (1 + Rate);
    public string Describe() => $"Tax rate {Rate:P0}";
}

class Program
{
    static void Main()
    {
        Type type = typeof(PriceCalculator);
        object calc = Activator.CreateInstance(type);

        MethodInfo withTax = type.GetMethod("WithTax");
        object result = withTax.Invoke(calc, new object[] { 50m });
        Console.WriteLine(result);

        foreach (MethodInfo m in type.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly))
        {
            if (m.IsSpecialName) continue;   // skip property getters and setters
            Console.WriteLine($"{m.ReturnType.Name} {m.Name}({m.GetParameters().Length} parameters)");
        }

        Type byName = Type.GetType("PriceCalculator");
        Console.WriteLine(byName == type);
    }
}

المخرجات:

60.00
Decimal WithTax(1 parameters)
String Describe(0 parameters)
True

يقصر DeclaredOnly القائمة على الأعضاء المصرّح بها في الصنف نفسه؛ ودونه تعيد GetMethods أيضًا ToString وEquals وGetHashCode وGetType من object. وتحتاج Type.GetType("Name") إلى الاسم المؤهّل بفضاء الأسماء، وللأنواع في تجميعات أخرى إلى اسم التجميع أيضًا ("MyApp.Plugins.Csv, MyApp.Plugins").

إن رمت الدالة المستدعاة استثناءً تغلّفه Invoke في TargetInvocationException؛ والأصلي في InnerException الخاص به.

السمات: وسوم يقرؤها المترجم والأطر

تُكتب السمة بين أقواس مربعة قبل الشيء الذي تصفه. يعرّف الإطار كثيرًا منها؛ بعضها يغيّر ما يفعله المترجم:

public class OrderService
{
    [Obsolete("Use PlaceOrderAsync instead.")]
    public void PlaceOrder(Order order) { }
    // Every call site: warning CS0618: 'OrderService.PlaceOrder(Order)' is obsolete: 'Use PlaceOrderAsync instead.'
    // [Obsolete("...", true)] makes it error CS0619 instead.

    [Conditional("DEBUG")]
    public void Trace(string message) => Console.WriteLine(message);
    // Calls to Trace are removed entirely from builds without the DEBUG symbol.
}

[Flags] enum Channels { None = 0, Email = 1, Sms = 2 }   // changes how ToString formats combinations
[Serializable] class Snapshot { }                     // marks a type for legacy binary serialization

وأخرى تقرؤها المكتبات وقت التشغيل: [JsonPropertyName] و[JsonIgnore] تقرؤهما System.Text.Json، و[Required] و[MaxLength] يقرؤهما التحقق من النماذج في ASP.NET Core وEntity Framework، و[HttpGet("orders/{id}")] يقرؤها توجيه ASP.NET، و[Fact] و[Test] تقرؤهما مشغّلات الاختبارات. السمة نفسها لا تفعل شيئًا؛ الشيفرة التي تبحث عنها هي التي تفعل.

يُختصر الاسم ObsoleteAttribute إلى [Obsolete] عند التطبيق: عرفًا ينتهي اسم كل صنف سمة بـ Attribute، وتتيح لك C# حذف اللاحقة.

التصريح بسمة مخصصة وقراءتها

السمة المخصصة صنف مشتق من Attribute. تحدد [AttributeUsage] ما يمكن تطبيقها عليه. تصبح معاملات المُنشئ وسائط موضعية، وتصبح الخصائص العامة القابلة للضبط وسائط مسمّاة:

using System;
using System.Collections.Generic;
using System.Reflection;

[AttributeUsage(AttributeTargets.Property)]
class RequiredAttribute : Attribute { }

[AttributeUsage(AttributeTargets.Property)]
class MaxLengthAttribute : Attribute
{
    public int Length { get; }
    public string Message { get; set; }            // optional, set as a named argument
    public MaxLengthAttribute(int length) { Length = length; }
}

class SignupForm
{
    [Required, MaxLength(20)]
    public string Username { get; set; }

    [Required]
    public string Email { get; set; }

    [MaxLength(10, Message = "Keep the city code short")]
    public string CityCode { get; set; }
}

static class Validator
{
    public static List<string> Validate(object model)
    {
        var errors = new List<string>();
        foreach (PropertyInfo p in model.GetType().GetProperties())
        {
            var value = p.GetValue(model) as string;

            if (p.GetCustomAttribute<RequiredAttribute>() != null && string.IsNullOrWhiteSpace(value))
                errors.Add($"{p.Name} is required");

            var max = p.GetCustomAttribute<MaxLengthAttribute>();
            if (max != null && value != null && value.Length > max.Length)
                errors.Add(max.Message ?? $"{p.Name} must be at most {max.Length} characters");
        }
        return errors;
    }
}

class Program
{
    static void Main()
    {
        var form = new SignupForm { Username = "a_very_long_username_indeed", CityCode = "LISBON-CENTRAL" };
        foreach (var error in Validator.Validate(form))
            Console.WriteLine(error);

        var ok = new SignupForm { Username = "ana", Email = "ana@example.com", CityCode = "LIS" };
        Console.WriteLine(Validator.Validate(ok).Count);
    }
}

المخرجات:

Username must be at most 20 characters
Email is required
Keep the city code short
0

هذه نسخة مصغّرة مما يفعله التحقق من النماذج في ASP.NET Core مع System.ComponentModel.DataAnnotations. يجب أن تكون وسائط السمات ثوابت وقت الترجمة (أرقام، نصوص، typeof(...)، قيم تعدادات، أو مصفوفات منها)، لأنها تُخزَّن في البيانات الوصفية للتجميع. وGetCustomAttribute<T>() دالة توسيع في System.Reflection؛ وتوجد أيضًا IsDefined(typeof(T)) حين لا تحتاج إلا إلى معرفة هل السمة موجودة.

كلفة الانعكاس

يقايض الانعكاس السرعة والأمان بالمرونة:

• السرعة. البحث عن عضو بالاسم واستدعاؤه عبر Invoke أو GetValue أبطأ بكثير من الاستدعاء المباشر، ويغلّف أنواع القيم. للاستخدام المتكرر ابحث عن PropertyInfo أو MethodInfo مرة واحدة واحتفظ به، أو حوّله إلى مفوّض بـ Delegate.CreateDelegate أو MethodInfo.CreateDelegate واستدعِ ذلك.
• الأمان. الاسم المكتوب خطأ أو التوقيع المتغيّر يُترجم بلا مشكلة ويفشل وقت التشغيل. فضّل nameof(Product.Price) على النص "Price" حيثما استطعت، كي تُلتقط إعادة التسمية.
• التقليم وAOT. تزيل التطبيقات المقلّمة وتطبيقات Native AOT الأعضاء التي لا يبدو أن شيئًا يستخدمها، والانعكاس يخفي الاستخدام عن ذلك التحليل. والمكتبات الحديثة (System.Text.Json وGeneratedRegex والتسجيل) تنتقل إلى مولّدات المصدر، التي تؤدي العمل نفسه وقت الترجمة.

استخدم الانعكاس لأجزاء البرنامج التي لا تعرف أنواعها مسبقًا حقًا: الإضافات، والأدوات العامة، وأدوات التسلسل، ومساعدات الاختبار. وحين تكون الأنواع معروفة تكون الشيفرة العادية أو الأنواع العامة أو الواجهات أسرع ويفحصها المترجم.

أخطاء شائعة

• GetType() == typeof(Base) لاختبار صنف أساس. يفشل مع الأنواع المشتقة. استخدم is أو IsAssignableFrom.
• عدم فحص null. تعيد GetProperty وGetMethod وType.GetType القيمة null حين لا يطابق شيء.
• الانعكاس في حلقة ساخنة دون تخزين مؤقت. خزّن MemberInfo أو ترجم مفوّضًا.
• التقاط الاستثناء الخطأ من Invoke. الاستثناء الحقيقي هو InnerException في TargetInvocationException.
• نصوص سحرية لأسماء الأعضاء. استخدم nameof.