Argumen Bernama dan Opsional (Panduan Pemrograman C#)

Argumen bernama memungkinkan Anda menentukan argumen sebagai parameter dengan mencocokkan argumen berdasarkan namanya dan bukan posisinya di dalam daftar parameter. Argumen opsional memungkinkan Anda menghilangkan argumen untuk beberapa parameter. Kedua teknik dapat digunakan dengan metode, pengindeks, konstruktor, dan delegasi.

Saat Anda menggunakan argumen bernama dan opsional, argumen dievaluasi dalam urutan munculnya dalam daftar argumen, bukan daftar parameter.

Parameter bernama dan opsional memungkinkan Anda menyediakan argumen untuk parameter yang dipilih. Kemampuan ini sangat memudahkan panggilan ke antarmuka COM seperti API Microsoft Office Automation.

Argumen bernama

Argumen bernama membebaskan Anda dari pencocokan urutan argumen dengan urutan parameter dalam daftar parameter metode yang disebut. Argumen untuk setiap parameter dapat ditentukan oleh nama parameter. Misalnya, fungsi yang mencetak detail pesanan (seperti, nama penjual, nomor pesanan & nama produk) dapat dipanggil dengan mengirim argumen berdasarkan posisi, dalam urutan yang ditentukan oleh fungsi.

PrintOrderDetails("Gift Shop", 31, "Red Mug");

Jika Anda tidak ingat urutan parameter tetapi mengetahui namanya, Anda dapat mengirim argumen dalam urutan apa pun.

PrintOrderDetails(orderNum: 31, productName: "Red Mug", sellerName: "Gift Shop");
PrintOrderDetails(productName: "Red Mug", sellerName: "Gift Shop", orderNum: 31);

Argumen bernama juga meningkatkan keterbacaan kode Anda dengan mengidentifikasi apa yang diwakili setiap argumen. Dalam metode contoh di bawah ini, sellerName tidak boleh null atau spasi kosong. Karena sellerName dan productName merupakan jenis string, alih-alih mengirim argumen berdasarkan posisi, masuk akal untuk menggunakan argumen bernama untuk membedakan keduanya dan mengurangi kebingungan bagi siapa pun yang membaca kode.

Argumen bernama, ketika digunakan dengan argumen posisi, bersifat valid selama

• tidak diikuti oleh argumen posisi apa pun, atau

  PrintOrderDetails("Gift Shop", 31, productName: "Red Mug");
  

• mereka digunakan dalam posisi yang benar. Dalam contoh di bawah ini, parameter orderNum berada dalam posisi yang benar tetapi tidak diberi nama secara eksplisit.

  PrintOrderDetails(sellerName: "Gift Shop", 31, productName: "Red Mug");
  

Argumen posisional yang mengikuti argumen bernama di luar urutan tidak valid.

// This generates CS1738: Named argument specifications must appear after all fixed arguments have been specified.
PrintOrderDetails(productName: "Red Mug", 31, "Gift Shop");

Contoh

Kode berikut mengimplementasikan contoh dari bagian ini bersama dengan beberapa kode tambahan.

class NamedExample
{
    static void Main(string[] args)
    {
        // The method can be called in the normal way, by using positional arguments.
        PrintOrderDetails("Gift Shop", 31, "Red Mug");

        // Named arguments can be supplied for the parameters in any order.
        PrintOrderDetails(orderNum: 31, productName: "Red Mug", sellerName: "Gift Shop");
        PrintOrderDetails(productName: "Red Mug", sellerName: "Gift Shop", orderNum: 31);

        // Named arguments mixed with positional arguments are valid
        // as long as they are used in their correct position.
        PrintOrderDetails("Gift Shop", 31, productName: "Red Mug");
        PrintOrderDetails(sellerName: "Gift Shop", 31, productName: "Red Mug"); 
        PrintOrderDetails("Gift Shop", orderNum: 31, "Red Mug");

        // However, mixed arguments are invalid if used out-of-order.
        // The following statements will cause a compiler error.
        // PrintOrderDetails(productName: "Red Mug", 31, "Gift Shop");
        // PrintOrderDetails(31, sellerName: "Gift Shop", "Red Mug");
        // PrintOrderDetails(31, "Red Mug", sellerName: "Gift Shop");
    }

    static void PrintOrderDetails(string sellerName, int orderNum, string productName)
    {
        if (string.IsNullOrWhiteSpace(sellerName))
        {
            throw new ArgumentException(message: "Seller name cannot be null or empty.", paramName: nameof(sellerName));
        }

        Console.WriteLine($"Seller: {sellerName}, Order #: {orderNum}, Product: {productName}");
    }
}

Argumen opsional

Definisi dari metode, konstruktor, pengindeks, atau delegasi dapat menentukan parameternya diperlukan atau opsional. Setiap panggilan harus memberikan argumen untuk semua parameter yang diperlukan, tetapi dapat menghilangkan argumen untuk parameter opsional.

Setiap parameter opsional memiliki nilai default sebagai bagian dari definisinya. Jika tidak ada argumen yang dikirim untuk parameter tersebut, nilai default akan digunakan. Nilai default harus merupakan salah satu jenis ekspresi berikut:

• ekspresi konstanta;
• ekspresi formulir new ValType(), di mana ValType adalah jenis nilai, seperti enum atau struct;
• ekspresi formulir default(ValType), di mana ValType adalah jenis nilai.

Parameter opsional ditentukan di akhir daftar parameter, setelah parameter yang diperlukan. Jika pemanggil memberikan argumen untuk salah satu dari keberhasilan parameter opsional, pemanggil harus memberikan argumen untuk semua parameter opsional sebelumnya. Celah yang dipisahkan koma dalam daftar argumen tidak didukung. Misalnya, dalam kode berikut, metode ExampleMethod instans didefinisikan dengan satu parameter yang diperlukan dan dua parameter opsional.

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

Panggilan berikut untuk ExampleMethod menyebabkan kesalahan kompilator, karena argumen disediakan untuk parameter ketiga tetapi tidak untuk yang kedua.

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

Namun, jika Anda mengetahui nama parameter ketiga, Anda dapat menggunakan argumen bernama untuk menyelesaikan tugas.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense menggunakan tanda kurung siku untuk menunjukkan parameter opsional, seperti yang ditunjukkan dalam ilustrasi berikut:

Catatan

Anda juga dapat mendeklarasikan parameter opsional dengan menggunakan kelas .NET OptionalAttribute . OptionalAttribute parameter tidak memerlukan nilai default. Namun, jika nilai default diinginkan, lihat DefaultParameterValueAttribute kelas .

Contoh

Dalam contoh berikut, konstruktor untuk ExampleClass memiliki satu parameter, yang bersifat opsional. Metode instans ExampleMethod memiliki satu parameter wajib, required, dan dua parameter opsional, optionalstr dan optionalint. Kode dalam Main menunjukkan berbagai cara di mana konstruktor dan metode dapat dipanggil.

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(
                $"{_name}: {required}, {optionalstr}, and {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.
}

Kode sebelumnya menunjukkan sejumlah contoh di mana parameter opsional tidak diterapkan dengan benar. Yang pertama menggambarkan bahwa argumen harus disediakan untuk parameter pertama, yang diperlukan.

Atribut informasi penelepon

Atribut informasi pemanggil, seperti CallerFilePathAttribute, , CallerLineNumberAttributeCallerMemberNameAttribute, dan CallerArgumentExpressionAttribute, digunakan untuk mendapatkan informasi tentang pemanggil ke metode . Atribut ini sangat berguna saat Anda menelusuri kesalahan atau saat Anda perlu mencatat informasi tentang panggilan metode.

Atribut ini adalah parameter opsional dengan nilai default yang disediakan oleh pengkompilasi. Pemanggil tidak boleh secara eksplisit memberikan nilai untuk parameter ini.

Antarmuka COM

Argumen bernama dan opsional, bersama dengan dukungan untuk objek dinamis, sangat meningkatkan interoperabilitas dengan API COM, seperti API Office Automation.

Misalnya, metode AutoFormat dalam antarmuka Microsoft Office Excel Range memiliki tujuh parameter, yang semuanya bersifat opsional. Pengaturan ini diperlihatkan dalam ilustrasi berikut:

Namun, Anda dapat sangat menyederhanakan panggilan ke AutoFormat dengan menggunakan argumen bernama dan opsional. Argumen bernama dan opsional memungkinkan Anda menghilangkan argumen untuk parameter opsional jika Anda tidak ingin mengubah nilai default parameter. Dalam panggilan berikut, nilai ditentukan hanya untuk salah satu dari tujuh parameter.

var excelApp = new Microsoft.Office.Interop.Excel.Application();
excelApp.Workbooks.Add();
excelApp.Visible = true;

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

excelApp.Range["A1", "B4"].AutoFormat( Format: myFormat );

Untuk informasi dan contoh selengkapnya, lihat Cara menggunakan argumen bernama dan opsional dalam pemrograman Office dan Cara mengakses objek interop Office dengan menggunakan fitur C#.

Resolusi saat kelebihan muatan

Penggunaan argumen bernama dan opsional memengaruhi resolusi kelebihan beban dengan cara berikut:

• Metode, pengindeks, atau konstruktor adalah kandidat untuk eksekusi jika masing-masing parameternya bersifat opsional atau sesuai, berdasarkan nama atau posisi, ke argumen tunggal dalam pernyataan panggilan, dan argumen tersebut dapat dikonversi ke jenis parameter.
• Jika lebih dari satu kandidat ditemukan, aturan resolusi yang berlebihan untuk konversi pilihan akan diterapkan ke argumen yang ditentukan secara eksplisit. Argumen yang dihilangkan untuk parameter opsional diabaikan.
• Jika dua kandidat dinilai sama baiknya, preferensi masuk ke kandidat yang tidak memiliki parameter opsional yang argumennya dihilangkan dalam panggilan. Resolusi kelebihan beban umumnya lebih memilih kandidat yang memiliki lebih sedikit parameter.

Spesifikasi bahasa C#

Untuk informasi selengkapnya, lihat Spesifikasi Bahasa C#. Spesifikasi bahasa adalah sumber definitif untuk sintaks dan penggunaan C#.