الأحداث في C#: الكلمة event وEventHandler والاشتراك والإطلاق

يتيح الحدث (event) لصنف الإعلان أن شيئًا حدث دون أن يعرف من يستمع. تشترك كائنات أخرى بـ +=، وحين يطلق الصنف الحدث تُنفَّذ دالة كل مشترك.

using System;

class OrderPlacedEventArgs : EventArgs
{
    public string OrderId { get; }
    public decimal Total { get; }

    public OrderPlacedEventArgs(string orderId, decimal total)
    {
        OrderId = orderId;
        Total = total;
    }
}

class Shop
{
    public event EventHandler<OrderPlacedEventArgs> OrderPlaced;

    public void PlaceOrder(string id, decimal total)
    {
        Console.WriteLine($"Order {id} saved");
        OrderPlaced?.Invoke(this, new OrderPlacedEventArgs(id, total));
    }
}

class Program
{
    static void SendReceipt(object sender, OrderPlacedEventArgs e)
    {
        Console.WriteLine($"  receipt emailed for {e.OrderId}");
    }

    static void Main()
    {
        var shop = new Shop();
        shop.OrderPlaced += SendReceipt;
        shop.OrderPlaced += (sender, e) =>
        {
            if (e.Total > 100m) Console.WriteLine($"  free gift added to {e.OrderId}");
        };

        shop.PlaceOrder("A-17", 45m);
        shop.PlaceOrder("A-18", 180m);
    }
}

المخرجات:

Order A-17 saved
  receipt emailed for A-17
Order A-18 saved
  receipt emailed for A-18
  free gift added to A-18

لا يعرف Shop أن الإيصالات أو الهدايا موجودة. يطلق OrderPlaced، ويتفاعل كل من اشترك. إضافة ردّ فعل جديد (نقاط الولاء، التحليلات) تعني إضافة مشترك، لا تعديل PlaceOrder.

التصريح بحدث

تصريح الحدث عضو من نوع مفوّض مع الكلمة event:

public event EventHandler<OrderPlacedEventArgs> OrderPlaced;

يحدد نوع المفوّض توقيع المعالج. تستخدم شيفرة .NET دائمًا تقريبًا أحد نوعين مدمجين، واتباع هذا العُرف يجعل أحداثك مألوفة لكل مطوّر .NET آخر:

• EventHandler: void (object sender, EventArgs e)، للأحداث التي لا تحمل بيانات. أطلقه بـ EventArgs.Empty.
• EventHandler<TEventArgs>: void (object sender, TEventArgs e)، حيث TEventArgs صنفك الذي يحمل البيانات.

الأعراف المحيطة بهما:

• sender هو الكائن الذي أطلق الحدث، وعادة this.
• يُسمّى صنف البيانات {Something}EventArgs، ويشتق من EventArgs (اختياري منذ .NET 4.5، لكنه ما زال متّبعًا)، ويكشف خصائص للقراءة فقط.
• يُسمّى الحدث بما حدث: OrderPlaced وClosed وPriceChanged. ويُستخدم الاسم بصيغة ...ing (Closing) للأحداث التي تُطلق قبل الفعل، غالبًا مع طريقة لإلغائه.
• يمر الإطلاق عبر دالة protected virtual void OnOrderPlaced(OrderPlacedEventArgs e) في الأصناف المعدّة للوراثة، كي تستطيع الأصناف المشتقة التدخل.

الاشتراك وإلغاؤه

تضيف += معالجًا وتحذفه -=. يمكن أن يكون المعالج دالة أو تعبير lambda. لحذف تعبير lambda لاحقًا احتفظ به في متغيّر، لأن كتابة تعبير lambda نفسه مجددًا تنشئ مفوّضًا مختلفًا لن تجده -=:

using System;

class Thermostat
{
    public event EventHandler<int> TemperatureChanged;

    public void Set(int celsius)
    {
        Console.WriteLine($"set to {celsius}");
        TemperatureChanged?.Invoke(this, celsius);
    }
}

class Program
{
    static void Main()
    {
        var thermostat = new Thermostat();

        EventHandler<int> display = (s, t) => Console.WriteLine($"  display shows {t} C");
        EventHandler<int> alarm = (s, t) =>
        {
            if (t > 30) Console.WriteLine("  alarm: too hot");
        };

        thermostat.TemperatureChanged += display;
        thermostat.TemperatureChanged += alarm;
        thermostat.Set(32);

        thermostat.TemperatureChanged -= alarm;
        thermostat.Set(35);

        thermostat.TemperatureChanged -= (s, t) => Console.WriteLine("never subscribed");
        thermostat.Set(20);
    }
}

المخرجات:

set to 32
  display shows 32 C
  alarm: too hot
set to 35
  display shows 35 C
set to 20
  display shows 20 C

حذف معالج لم يُضف قط ليس خطأ؛ لا يفعل شيئًا. ويُظهر EventHandler<int> أن وسيط النوع لا يلزم أن يشتق من EventArgs في .NET الحديثة، مع أن الصنف المخصص يترك مجالًا لإضافة حقول لاحقًا دون كسر المشتركين.

تُنفَّذ المعالجات بشكل متزامن، بترتيب الاشتراك، على الخيط الذي أطلق الحدث. إن رمى معالج استثناءً فلا تُنفَّذ المعالجات الباقية وينتقل الاستثناء إلى الشيفرة التي أطلقت الحدث.

إطلاق حدث بأمان

الحدث بلا مشتركين يحمل null. استدعاؤه مباشرة سيرمي NullReferenceException، فأطلقه بالمعامل الشرطي لـ null:

OrderPlaced?.Invoke(this, args);

قبل C# 6 كان النمط نسخ الحقل إلى متغيّر محلي، وفحصه، واستدعاء النسخة. النسخة مهمة في الشيفرة متعددة الخيوط: فحص OrderPlaced != null ثم استدعاء OrderPlaced(...) يقرأ الحقل مرتين، وقد يحذف خيط آخر المعالج الأخير بينهما. أما ?. فتقرؤه مرة واحدة، فهي أقصر وصحيحة معًا.

لماذا event لا حقل مفوّض عام

دون الكلمة event يعمل حقل المفوّض العام للاشتراك، لكنه يسلّم كل مشترك تحكمًا كاملًا:

using System;

class Button
{
    public Action Clicked;                   // no 'event' keyword
    public void Click() => Clicked?.Invoke();
}

class Program
{
    static void Main()
    {
        var button = new Button();
        button.Clicked += () => Console.WriteLine("save document");
        button.Clicked += () => Console.WriteLine("play click sound");

        button.Clicked = () => Console.WriteLine("analytics ping");   // '=' instead of '+='
        button.Click();

        button.Clicked();                    // any code can fire it, too
    }
}

المخرجات:

analytics ping
analytics ping

حذفت = واحدة كُتبت بدل += المعالجين السابقين بصمت، واستطاعت الشيفرة الخارجية إطلاق "النقرة" دون أي نقرة. تعليم الحقل بـ event يجعل السطرين خطأَي ترجمة:

error CS0070: The event 'Button.Clicked' can only appear on the left hand side of += or -= (except when used from within the type 'Button')

داخل Button ما زال الحدث يتصرف كحقل مفوّض عادي، فيستطيع الصنف استدعاءه وفحصه لـ null.

تسرّب نسيان إلغاء الاشتراك

حين تشترك يخزّن الحدث مفوّضًا، ويحمل المفوّض مرجعًا إلى كائن المشترك. ما دام الناشر حيًا والمعالج مرتبطًا لا يمكن جمع المشترك كنفايات، ويظل يتلقى الأحداث بعد أن تنتهي منه:

using System;

class PriceFeed
{
    public event EventHandler<decimal> PriceChanged;

    public void Publish(decimal price) => PriceChanged?.Invoke(this, price);

    public int SubscriberCount =>
        PriceChanged == null ? 0 : PriceChanged.GetInvocationList().Length;
}

class PriceWidget : IDisposable
{
    private readonly PriceFeed feed;
    private readonly string name;

    public PriceWidget(PriceFeed feed, string name)
    {
        this.feed = feed;
        this.name = name;
        feed.PriceChanged += OnPriceChanged;
    }

    private void OnPriceChanged(object sender, decimal price) =>
        Console.WriteLine($"  {name} shows {price}");

    public void Dispose() => feed.PriceChanged -= OnPriceChanged;
}

class Program
{
    static void Main()
    {
        var feed = new PriceFeed();                 // lives for the whole app

        var leaky = new PriceWidget(feed, "closed widget");   // never disposed
        leaky = null;

        using (var widget = new PriceWidget(feed, "open widget"))
        {
            feed.Publish(101.5m);
        }                                            // Dispose unsubscribes

        Console.WriteLine($"subscribers left: {feed.SubscriberCount}");
        feed.Publish(99.0m);
    }
}

المخرجات:

  closed widget shows 101.5
  open widget shows 101.5
subscribers left: 1
  closed widget shows 99.0

ضبط leaky على null لم يفعل شيئًا للتغذية: ما زالت قائمة معالجاتها تشير إلى تلك الأداة، فتظل الأداة "المغلقة" تتحدّث وتبقى في الذاكرة. أما الأداة في كتلة using فألغت اشتراكها في Dispose وتوقفت عن التلقي. هذا من أشيع تسرّبات الذاكرة في شيفرة سطح المكتب والخوادم في .NET، خاصة مع الأحداث الساكنة والخدمات على مستوى التطبيق، التي تعيش حتى تنتهي العملية.

القاعدة: من يشترك في حدث على كائن يعيش أطول منه يجب أن يلغي اشتراكه، عادة في Dispose (راجع العبارة using). وحين يكون للناشر والمشترك العمر نفسه، مثل نموذج وأزراره الخاصة، لا حاجة إلى إلغاء الاشتراك.

موصّلات add وremove المخصصة

يمكن للحدث أن يحدد ما تفعله += و-=، مثل get وset في الخاصية. هذا نادر، لكنه طريقة الأطر في تخزين المعالجات في قاموس مشترك أو تمريرها إلى كائن آخر:

private EventHandler closed;

public event EventHandler Closed
{
    add    { Console.WriteLine("subscriber added");   closed += value; }
    remove { Console.WriteLine("subscriber removed"); closed -= value; }
}

مع الموصّلات المخصصة يطلق الصنف الحدث عبر الحقل الداعم (closed?.Invoke(this, EventArgs.Empty))، لأن الحدث نفسه لم يعد له تخزين.