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

جزء من قسم Object Oriented Programming في رحلة C# على Coddy — الدرس 49 من 70.

تتيح لك الوسائط المسماة (Named arguments) تحديد المعامل الذي يتلقى القيمة باستخدام اسمه، بدلاً من الاعتماد على الموضع. وهذا يجعل استدعاءات الدوال أكثر وضوحاً ويسمح لك بتمرير الوسائط بأي ترتيب.

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

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 arguments) عند دمجها مع المعلمات الاختيارية. فبدلاً من توفير جميع القيم الاختيارية السابقة، يمكنك الانتقال مباشرة إلى القيمة التي تحتاجها:

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);

يمكنك المزج بين الوسائط الموضعية (positional arguments) والوسائط المسماة (named arguments)، ولكن يجب أن تأتي الوسائط الموضعية أولاً. تعمل الوسائط المسماة على تحسين قابلية القراءة، خاصة بالنسبة للدوال (methods) التي تحتوي على معلمات متعددة من نفس النوع أو الأعلام المنطقية (boolean flags) حيث لا يكون المعنى واضحاً من القيمة وحدها.

التحدي

سهل

لنقم ببناء مولد تقارير يستفيد من الوسائط المسماة (named arguments) لجعل استدعاءات الدوال واضحة تماماً. عندما تحتوي الدوال على معلمات متعددة - خاصة تلك التي من نفس النوع أو الأعلام المنطقية (boolean flags) - تجعل الوسائط المسماة كودك يوثق نفسه بنفسه.

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

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. هذا يجعل استدعاءات الدوال الخاصة بك أكثر قابلية للقراءة ويكشف عن الغرض منها بوضوح!

ورقة مرجعية

تسمح لك الوسائط المسماة (Named arguments) بتحديد المعلمة التي تتلقى القيمة باستخدام اسمها، بدلاً من الاعتماد على الموضع. وهذا يجعل استدعاءات الدوال أكثر وضوحاً ويسمح لك بتمرير الوسائط بأي ترتيب.

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

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");  // أي ترتيب يعمل

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

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);

يمكنك المزج بين الوسائط الموضعية والمسماة، ولكن يجب أن تأتي الوسائط الموضعية أولاً. تعمل الوسائط المسماة على تحسين قابلية القراءة، خاصة بالنسبة للدوال التي تحتوي على معلمات متعددة من نفس النوع أو علامات منطقية (boolean flags).

جرّب بنفسك

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)
        

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