الوسائط المسماة

جزء من قسم البرمجة كائنية التوجه في رحلة C# على Coddy. الدرس 49 من 70.

المعاملات named تتيح لك تحديد المَعلمة التي تستقبل قيمةً باستخدام اسمها، بدلاً من الاعتماد على الموضع. وهذا يجعل استدعاءات method أكثر وضوحًا، ويسمح لك بتمرير المعاملات بأي ترتيب.

استخدم اسم المعلمة متبوعًا بنقطتين قبل القيمة:

public static void CreateUser(string name, int age, bool isActive)
{
    Console.WriteLine($"{name}, Age: {age}, Active: {isActive}");
}

// استخدام الوسائط المسماة
CreateUser(name: "Alice", age: 25, isActive: true);
CreateUser(age: 30, isActive: false, name: "Bob");  // أي ترتيب يعمل

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

public static void Configure(string host, int port = 8080, bool useSSL = false, int timeout = 30)
{
    Console.WriteLine($"{host}:{port}, SSL: {useSSL}, Timeout: {timeout}");
}

// تخطي port و useSSL، حدد فقط timeout
Configure("localhost", timeout: 60);
Configure("server.com", useSSL: true);

يمكنك مزج المعاملات الموضعية وnamed arguments، لكن يجب أن تأتي المعاملات الموضعية أولًا. تجعل named arguments الشيفرة أسهل قراءة، لا سيما في الأساليب التي تحتوي على عدة معاملات من النوع نفسه أو على علامات منطقية حيث لا يكون المعنى واضحًا من القيمة وحدها.

التحدي

سهل

لنُنشئ مولّد تقارير يستفيد من الوسائط المسماة لجعل استدعاءات method واضحة تمامًا. عندما تحتوي الأساليب على عدة معلمات - وخاصةً المعلمات من النوع نفسه أو علامات bool - تجعل الوسائط المسماة الكود موضحًا لنفسه.

ستنظّم الكود عبر ملفين:

ReportGenerator.cs: أنشئ فئة ReportGenerator في مساحة الاسم Reports، مع أسلوب يحتوي على عدة معلمات اختيارية:
- GenerateReport(string title, string author = "Anonymous", bool includeHeader = true, bool includeSummary = false, int maxPages = 10)
- يجب أن يعيد هذا الأسلوب سلسلة منسّقة تصف إعدادات التقرير
- التنسيق: Report: {title} by {author} | Header: {Yes/No}, Summary: {Yes/No}, Max Pages: {maxPages}
Program.cs: في ملفك الرئيسي، وضّح قوة الوسائط المسماة من خلال استدعاء GenerateReport بطرق مختلفة - مع تخطّي المعلمات الاختيارية التي لا تحتاج إليها وتحديد المعلمات المهمة فقط لكل تقرير.

ستتلقى ثلاث مدخلات:

عنوان التقرير الأول
عنوان التقرير الثاني
عنوان التقرير الثالث

أنشئ ثلاثة تقارير بإعدادات مختلفة:

التقرير الأول: استخدم العنوان فقط (تنطبق جميع القيم الافتراضية)
التقرير الثاني: استخدم العنوان مع includeSummary: true وmaxPages: 25 (تخطَّ author وincludeHeader، مع الإبقاء على القيم الافتراضية لهما)
التقرير الثالث: استخدم العنوان مع author: "Admin" وincludeHeader: false وincludeSummary: true (أبقِ القيمة الافتراضية لـ maxPages)

اطبع نتيجة كل تقرير في سطر مستقل.

على سبيل المثال، إذا كانت المدخلات هي Sales Q1 وAnnual Review وInventory Check، فيجب أن يكون الناتج:

Report: Sales Q1 by Anonymous | Header: Yes, Summary: No, Max Pages: 10
Report: Annual Review by Anonymous | Header: Yes, Summary: Yes, Max Pages: 25
Report: Inventory Check by Admin | Header: No, Summary: Yes, Max Pages: 10

لاحظ كيف تتيح لك الوسائط المسماة الانتقال مباشرةً إلى المعلمات التي تهمك - فلا تحتاج إلى تحديد author أو includeHeader لمجرد تغيير includeSummary. وهذا يجعل استدعاءات method أكثر قابلية للقراءة وكشفًا للغرض منها!

جرّب بنفسك

using System;
using Reports;

class Program
{
    public static void Main(string[] args)
    {
        // اقرأ عناوين التقارير الثلاثة
        string title1 = Console.ReadLine();
        string title2 = Console.ReadLine();
        string title3 = Console.ReadLine();

        // أنشئ مثيلاً من ReportGenerator
        ReportGenerator generator = new ReportGenerator();

        // TODO: أنشئ التقرير الأول - استخدم العنوان فقط (تُطبق جميع القيم الافتراضية)
        

        // TODO: أنشئ التقرير الثاني - استخدم العنوان مع includeSummary: true و maxPages: 25
        // (تخطَّ author و includeHeader، مع الإبقاء على قيمهما الافتراضية)
        

        // TODO: أنشئ التقرير الثالث - استخدم العنوان مع author: "Admin" و includeHeader: false و includeSummary: true
        // (أبقِ القيمة الافتراضية لـ maxPages)
        

        // اطبع نتيجة كل تقرير
    }
}