الوسيطات المسماة والوسيطات الاختيارية (دليل البرمجة لـ #C)

يقدم Visual C# 2010 الوسيطات المسماة والوسيطات الاختيارية. تتيح لك الوسيطات المسماة تحديد وسيطة لمعلمة معينة عن طريق إقران الوسيطة مع اسم المعلمة بدلاً من موضع المعلمة في قائمة المعلمات. تتيح لك الوسيطات الاختيارية إمكانية تجاهل الوسيطات لبعض المعلمات. يمكن استخدام كلا التقنيتين مع الأساليب والمفهرسات والدوال الإنشائية والمفوضين.

عند استخدام الوسيطات المسماة والوسيطات الاختيارية يتم تقييم الوسيطات بالترتيب الذي تظهر به في قائمة الوسيطات وليس قائمة المعلمات.

يمكّنك استخدام المعلمات المسماة والمعلمات الاختيارية مع بعضها البعض من توفير وسيطات لمعلمات قليلة فقط من قائمة لمعلمات اختيارية. تسهل هذه الإمكانية بشكل كبير استدعاء واجهات COM مثل واجهات برمجة التطبيقات لـ Microsoft Office Automation.

الوسيطات المسماة

تحررك الوسيطات المسماة من الحاجة إلى التذكر أو البحث عن ترتيب المعلمات في قوائم المعلمات للأساليب المستدعاة. يمكن أن يتم تعيين معلمة لكل وسيطة بواسطة اسم المعلمة. على سبيل المثال، يمكن استدعاء دالة تحسب مؤشر كتلة الجسم (BMI) بطريقة قياسية عن طريق إرسال وسيطات للوزن والارتفاع حسب الموضع بالترتيب الذي تم تعريفها بواسطة الدالة.

CalculateBMI(123, 64);

إن لم تتذكر ترتيب المعلمات ولكن تعرف أسمائها، يمكنك إرسال الوسيطات في أي ترتيب تريد الوزن، أولاً أو الارتفاع أولاً.

CalculateBMI(weight: 123, height: 64);

CalculateBMI(height: 64, weight: 123);

الوسيطات المسماة أيضاً تحسن قابلية القراءة للتعليمات البرمجية بتعريف ما تمثله كل وسيطة.

يمكن للوسيطة المسماة أن تتبع الوسيطات الموضعية، كما هو موضح هنا.

CalculateBMI(123, height: 64);

مع ذلك، لا يمكن للوسيطة الموضعية أن تتبع الوسيطة المسمّاة. تؤدي العبارة التالية إلى خطأ في المحول البرمجي.

//CalculateBMI(weight: 123, 64);

المثال

تنفذ التعليمات البرمجية التالية الأمثلة من هذا المقطع.

class NamedExample
{
    static void Main(string[] args)
    {
        // The method can be called in the normal way, by using positional arguments.
        Console.WriteLine(CalculateBMI(123, 64));

        // Named arguments can be supplied for the parameters in either order.
        Console.WriteLine(CalculateBMI(weight: 123, height: 64));
        Console.WriteLine(CalculateBMI(height: 64, weight: 123));

        // Positional arguments cannot follow named arguments.
        // The following statement causes a compiler error.
        //Console.WriteLine(CalculateBMI(weight: 123, 64));

        // Named arguments can follow positional arguments.
        Console.WriteLine(CalculateBMI(123, height: 64));
    }

    static int CalculateBMI(int weight, int height)
    {
        return (weight * 703) / (height * height);
    }
}

الوسيطات الاختيارية

يمكن لتعريف الأسلوب أو الدالة الإنشائية أو المفهرس أو المفوض أن يحدد ما إذا كانت المعلمات مطلوبة أو اختيارية. يجب على أي اتصال أن يوفر وسيطات لكل المعلمات المطلوبة لكن يمكن تجاهل وسيطات المعلمات الاختيارية.

لدى كل معلمة اختيارية قيمة افتراضية كجزء من تعريفها. إذا لم يتم تمرير وسيطة للمعلمة، يتم استخدام القيمة الافتراضية. يجب على القيم الافتراضية أن تكون قيم ثابتة.

يتم تعريف المعلمات الاختيارية في نهاية قائمة المعلمات بعد أي معلمات مطلوبة. إذا وفّر المتصل وسيطة لأحد من المعلمات الاختيارية، فيجب عليه توفير وسيطات لجميع المعلمات الاختيارية السابقة. الفتحات المفصوله بواسطة الفواصل في قائمة الوسيطات غير مدعومة. على سبيل المثال، في التعليمات البرمجية التالية، أسلوب المثيل ExampleMethod تم تعريفه بمعلمة مطلوبة واحدة ومعلمتين اختياريتين اثنتين.

public void ExampleMethod(int required, string optionalstr = "default string",
    int optionalint = 10)

الاتصال التالي بـ ExampleMethod يؤدي إلى خطأ في المحول البرمجي لأنه تم توفير وسيطة للمعلمة الثالثة ولم يتم توفير وسيطة للمعلمة الثانية.

//anExample.ExampleMethod(3, ,4);

ومع ذلك، إذا كنت تعرف اسم المعلمة الثالثة يمكنك استخدام وسيطة مسماة لتنفيذ المهمة.

anExample.ExampleMethod(3, optionalint: 4);

يستخدم IntelliSense أقواساً للإشارة إلى المعلمات الاختيارية، كما هو مبين في التوضيح التالي.

المعلمات الاختيارية في ExampleMethod

ملاحظة

يمكن أيضاً تعريف المعلمات الاختيارية باستخدام فئة الـ .NET OptionalAttribute. معلمات OptionalAttribute لا تتطلب قيم افتراضية.

المثال

في المثال التالي الدالة الإنشائية لـ ExampleClass تحتوي معلمة واحدة وهي اختيارية. أسلوب المثيل ExampleMethod يحتوي على معلمة مطلوبة واحدة required، ومعلمتين اختياريتين optionalstr و optionalint. التعليمات البرمجية في Main تعرض الطرق المختلفة التي يمكن استدعاء الدالة الإنشائية واستدعاء الأسلوب فيها.

namespace OptionalNamespace
{
    class OptionalExample
    {
        static void Main(string[] args)
        {
            // Instance anExample does not send an argument for the constructor's
            // optional parameter.
            ExampleClass anExample = new ExampleClass();
            anExample.ExampleMethod(1, "One", 1);
            anExample.ExampleMethod(2, "Two");
            anExample.ExampleMethod(3);

            // Instance anotherExample sends an argument for the constructor's
            // optional parameter.
            ExampleClass anotherExample = new ExampleClass("Provided name");
            anotherExample.ExampleMethod(1, "One", 1);
            anotherExample.ExampleMethod(2, "Two");
            anotherExample.ExampleMethod(3);

            // The following statements produce compiler errors.

            // An argument must be supplied for the first parameter, and it
            // must be an integer.
            //anExample.ExampleMethod("One", 1);
            //anExample.ExampleMethod();

            // You cannot leave a gap in the provided arguments. 
            //anExample.ExampleMethod(3, ,4);
            //anExample.ExampleMethod(3, 4);

            // You can use a named parameter to make the previous 
            // statement work.
            anExample.ExampleMethod(3, optionalint: 4);
        }
    }

    class ExampleClass
    {
        private string _name;

        // Because the parameter for the constructor, name, has a default
        // value assigned to it, it is optional.
        public ExampleClass(string name = "Default name")
        {
            _name = name;
        }

        // The first parameter, required, has no default value assigned
        // to it. Therefore, it is not optional. Both optionalstr and 
        // optionalint have default values assigned to them. They are optional.
        public void ExampleMethod(int required, string optionalstr = "default string",
            int optionalint = 10)
        {
            Console.WriteLine("{0}: {1}, {2}, and {3}.", _name, required, optionalstr,
                optionalint);
        }
    }

    // The output from this example is the following:
    // Default name: 1, One, and 1.
    // Default name: 2, Two, and 10.
    // Default name: 3, default string, and 10.
    // Provided name: 1, One, and 1.
    // Provided name: 2, Two, and 10.
    // Provided name: 3, default string, and 10.
    // Default name: 3, default string, and 4.

}

واجهات COM

تحسّن الوسيطات المسماة والوسيطات الاختيارية مع دعم الكائنات الحيوية والتحسينات الأخرى بشكل كبير إمكانية التشغيل التفاعلي مع واجهات برمجة التطبيقات لـ COM مثل واجهات برمجة التطبيقات لـ Office Automation.

على سبيل المثال، للأسلوب AutoFormat في الواجهة Range من Microsoft Office Excel سبع معلمات كلها اختيارية. يتم عرض هذه المعلمات في الرسم التوضيحي التالي.

معلمات AutoFormat

في C# 3.0 والإصدارات السابقة، يتم طلب وسيطة لكل معلمة كما هو موضح في المثال التالي.

// In C# 3.0 and earlier versions, you need to supply an argument for
// every parameter. The following call specifies a value for the first
// parameter, and sends a placeholder value for the other six. The
// default values are used for those parameters.
var excelApp = new Microsoft.Office.Interop.Excel.Application();
excelApp.Workbooks.Add();
excelApp.Visible = true;

var myFormat = 
    Microsoft.Office.Interop.Excel.XlRangeAutoFormat.xlRangeAutoFormatAccounting1;

excelApp.get_Range("A1", "B4").AutoFormat(myFormat, Type.Missing, 
    Type.Missing, Type.Missing, Type.Missing, Type.Missing, Type.Missing);

ومع ذلك، بإمكانك تبسيط استدعاء AutoFormat بشكل كبير باستخدام الوسيطات المسماة والوسيطات الاختيارية المقدمة في C# 4.0. تتيح لك الوسيطات المسماة والوسيطات الاختيارية حذف الوسيطة للمعلمة الاختيارية إن لم تكن تريد تغيير القيمة الافتراضية للمعلمة. في الاتصال التالي، يتم تحديد قيمة واحدة فقط من المعلمات السبعة.

// The following code shows the same call to AutoFormat in C# 4.0. Only
// the argument for which you want to provide a specific value is listed.
excelApp.Range["A1", "B4"].AutoFormat( Format: myFormat );

و لمزيد من المعلومات والأمثلة، راجع كيفية القيام بما يلي: استخدام الوسيطات المسماة والاختيارية في برمجة المكتب (إرشادات برمجة C#) و كيفية القيام بما يلي: الوصول إلى كائنات Office Interop باستخدام ميزات Visual #C 2010 (دليل برمجة C# ) .

دقة التحميل الزائد

يؤثر استخدام الوسيطات المسماة والوسيطات الاختيارية على دقة التحميل الزائد بالطرق التالية:

• يكون الأسلوب أو المفهرس أو الدالة الإنشائية مرشحة للتنفيذ إذا كانت كل معلماتها اختيارية أو مطابقة حسب الاسم أو حسب الموضع لوسيطة مفردة في عبارة الاستدعاء ويتم تحويل الوسيطة إلى نوع المعلمة.

• إذا تم العثور على أكثر من ترشيح يتم تطبيق قواعد دقة التحميل الزائد للتحويلات المفضلة على الوسيطات التي تم تعيينها بوضوح. يتم تجاهل الوسيطات المحذوفة للمعلمات الاختيارية.

• إذا تم الحكم على مرشحين بأنهم متساوي الامتياز، ينتقل التفضيل إلى الترشيح الذي ليس لديه معلمات اختيارية للوسيطات التي تم تجاهلها في الاتصال. هذه نتيجة لتفضيل عام في دقة التحميل الزائد للترشيحات التي لها معلمات أقل.

مواصفات لغة #C

لمزيد من المعلومات، راجع مواصفات لغة #C. مواصفات اللغة هي المصدر النهائي لبناء جملة C# واستخدامها.

راجع أيضًا:

المهام

كيفية القيام بما يلي: استخدام الوسيطات المسماة والاختيارية في برمجة المكتب (إرشادات برمجة C#)

المرجع

استخدام المنشئات (البرمجة C# إرشادات)

استخدام المفهرسات (دليل البرمجة لـ #C)

موارد أخرى

استخدام نوع الحيوي (C# "برمجة" إرشادات)