Dokumentasi C# interaktif: Extension Method

Extension method menambahkan sebuah method ke tipe yang sudah ada tanpa mengubahnya, mewarisinya, atau membungkusnya. Kamu menulis method static biasa, menandai parameter pertamanya dengan this, dan pemanggil memakainya dengan sintaks titik seolah-olah tipe itu sudah punya method tersebut sejak awal:

using System;

static class StringExtensions
{
    public static string Truncate(this string text, int maxLength)
    {
        if (text.Length <= maxLength) return text;
        return text.Substring(0, maxLength) + "...";
    }

    public static int WordCount(this string text) =>
        text.Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries).Length;
}

class Program
{
    static void Main()
    {
        string title = "Extension methods let you add behavior to types you do not own";

        Console.WriteLine(title.Truncate(24));
        Console.WriteLine(title.WordCount());
        Console.WriteLine("short".Truncate(24));

        Console.WriteLine(StringExtensions.Truncate(title, 9));   // the same method, called directly
    }
}

Output:

Extension methods let yo...
12
short
Extension...

title.Truncate(24) di-compile persis menjadi StringExtensions.Truncate(title, 24). Sintaks titik hanyalah kemudahan: method-nya tetap static, tetap berada di StringExtensions, dan hanya bisa memakai member public milik string.

Aturan untuk mendeklarasikannya

Method-nya harus static dan berada di class yang static, tidak generic, dan tidak bersarang di dalam class lain. Class yang tidak static atau generic menghasilkan CS1106, Extension method must be defined in a non-generic static class; class yang bersarang menghasilkan CS1109, Extension methods must be defined in a top level static class.
this hanya ditaruh di parameter pertama, dan tipe parameter itu adalah tipe yang diperluas. Parameter berikutnya biasa saja.
Method-nya sendiri boleh generic (this IEnumerable<T> source), meskipun class-nya tidak boleh.
Method ini hanya melihat apa yang bisa dilihat kode luar mana pun: member public (dan, di assembly yang sama, member internal). Field private tetap private.

Konvensinya adalah memberi nama class sesuai apa yang diperluasnya (StringExtensions, EnumerableExtensions) dan mengelompokkannya di namespace seperti MyApp.Extensions.

Memperluas interface dan IEnumerable<T>

Memperluas sebuah interface menambahkan method-nya ke setiap tipe yang mengimplementasikannya. Karena itu, memperluas IEnumerable<T> memberi method tersebut sekaligus ke array, list, set, koleksi key dictionary, dan hasil query LINQ:

using System;
using System.Collections.Generic;
using System.Linq;

static class EnumerableExtensions
{
    public static decimal Median(this IEnumerable<decimal> source)
    {
        var sorted = source.OrderBy(x => x).ToList();
        if (sorted.Count == 0) throw new InvalidOperationException("sequence is empty");
        int mid = sorted.Count / 2;
        return sorted.Count % 2 == 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
    }

    public static IEnumerable<T> EveryNth<T>(this IEnumerable<T> source, int n)
    {
        int i = 0;
        foreach (T item in source)
        {
            if (i % n == 0) yield return item;
            i++;
        }
    }
}

class Program
{
    static void Main()
    {
        decimal[] prices = { 12m, 3m, 45m, 7m };
        var orderTotals = new List<decimal> { 20m, 80m, 50m };

        Console.WriteLine(prices.Median());
        Console.WriteLine(orderTotals.Median());
        Console.WriteLine(orderTotals.Where(t => t > 25m).Median());

        string[] frames = { "f0", "f1", "f2", "f3", "f4", "f5", "f6" };
        Console.WriteLine(string.Join(" ", frames.EveryNth(3)));
    }
}

Output:

9.5
50
65
f0 f3 f6

EveryNth bersifat generic: T disimpulkan dari receiver-nya, jadi method ini berfungsi untuk string di sini dan untuk tipe elemen apa pun. Karena memakai yield return, method ini lazy seperti operator LINQ bawaan dan bisa dirangkai bersamanya.

LINQ dibangun dari extension method

Where, Select, OrderBy, Sum, First, dan operator LINQ lainnya adalah extension method pada IEnumerable<T>, yang didefinisikan di class static System.Linq.Enumerable. Itulah sebabnya using System.Linq; harus ada di bagian atas file sebelum list.Where(...) bisa di-compile, dan kenapa LINQ berfungsi di setiap tipe koleksi tanpa satu pun dari tipe itu mengimplementasikan method Where:

using System;
using System.Linq;

class Program
{
    static void Main()
    {
        int[] scores = { 72, 95, 58, 88 };

        var passed1 = scores.Where(s => s >= 60).OrderBy(s => s);
        var passed2 = Enumerable.OrderBy(Enumerable.Where(scores, s => s >= 60), s => s);

        Console.WriteLine(string.Join(", ", passed1));
        Console.WriteLine(string.Join(", ", passed2));
    }
}

Output:

72, 88, 95
72, 88, 95

Kedua baris itu kodenya sama. Sintaks extension mengubah panggilan bersarang yang dibaca dari dalam ke luar menjadi rangkaian yang dibaca sesuai urutan langkahnya, dan inilah alasan utama extension method ada: fitur ini ditambahkan di C# 3 bersamaan dengan LINQ. Halaman LINQ membahas operator-operatornya.

Namespace-nya harus diimpor

Extension method hanya berada dalam jangkauan saat namespace class static-nya diimpor dengan using. Tanpa itu, panggilannya gagal seolah-olah method-nya tidak ada:

error CS1061: 'string' does not contain a definition for 'Truncate' and no accessible extension method 'Truncate' accepting a first argument of type 'string' could be found (are you missing a using directive or an assembly reference?)

Tambahkan using untuk namespace extension-nya (atau, sejak C# 10, global using sekali untuk seluruh project):

using System;
using Shop.Extensions;

namespace Shop.Extensions
{
    public static class PriceExtensions
    {
        public static string ToPriceTag(this decimal amount) => $"EUR {amount:F2}";
    }
}

class Program
{
    static void Main()
    {
        decimal total = 49.9m;
        Console.WriteLine(total.ToPriceTag());
    }
}

Output:

EUR 49.90

Sisi sebaliknya juga berguna: extension method yang tidak kamu inginkan di mana-mana bisa ditaruh di namespace yang hanya diimpor oleh sebagian file.

Method instance selalu menang

Saat sebuah tipe sudah punya method instance yang cocok, compiler memakainya dan tidak pernah mempertimbangkan extension-nya. Extension dengan signature yang sama menjadi kode mati di setiap tempat pemanggilan yang memakai sintaks titik:

using System;

class Invoice
{
    public decimal Amount = 120m;
    public string Describe() => $"Invoice (instance method): {Amount}";
}

static class InvoiceExtensions
{
    public static string Describe(this Invoice invoice) => "extension: only reachable as a static call";
    public static string Describe(this Invoice invoice, string currency) =>
        $"Invoice (extension): {invoice.Amount} {currency}";
}

class Program
{
    static void Main()
    {
        var invoice = new Invoice();
        Console.WriteLine(invoice.Describe());
        Console.WriteLine(invoice.Describe("USD"));
        Console.WriteLine(InvoiceExtensions.Describe(invoice));
    }
}

Output:

Invoice (instance method): 120
Invoice (extension): 120 USD
extension: only reachable as a static call

Extension dengan satu argumen kalah dari method instance; yang dengan dua argumen dipakai karena tidak ada method instance yang menerima string. Artinya juga, pembaruan library yang menambahkan method instance dengan nama yang sama seperti extension-mu akan diam-diam mengalihkan panggilanmu ke versi milik library. Pilih nama extension yang kecil kemungkinannya bentrok.

Memanggil pada null

Karena panggilannya sebenarnya pemanggilan static, receiver null tidak melempar exception di tempat pemanggilan. Method-nya menerima null sebagai argumen pertama dan menentukan apa artinya:

using System;

static class TextExtensions
{
    public static bool IsBlank(this string s) => string.IsNullOrWhiteSpace(s);

    public static string Initials(this string fullName)
    {
        if (fullName == null) throw new ArgumentNullException(nameof(fullName));
        string result = "";
        foreach (string part in fullName.Split(' '))
            if (part.Length > 0) result += char.ToUpper(part[0]);
        return result;
    }
}

class Program
{
    static void Main()
    {
        string missing = null;

        Console.WriteLine(missing.IsBlank());
        Console.WriteLine("ada lovelace".Initials());

        try
        {
            missing.Initials();
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine($"{e.GetType().Name}: {e.ParamName}");
        }
    }
}

Output:

True
AL
ArgumentNullException: fullName

missing.IsBlank() yang mengembalikan true memang praktis, tetapi bisa mengejutkan pembaca yang mengira pemanggilan member pada null akan melempar exception. Terima null hanya di method yang namanya membuat hal itu jelas (IsBlank, OrEmpty); di tempat lain, lempar ArgumentNullException seperti yang dilakukan LINQ.

Memperluas enum

Enum tidak bisa punya method sendiri, jadi enum adalah sasaran yang wajar:

enum OrderStatus { Pending, Paid, Shipped, Delivered, Cancelled }

static class OrderStatusExtensions
{
    public static bool IsFinal(this OrderStatus s) =>
        s == OrderStatus.Delivered || s == OrderStatus.Cancelled;
}

// usage: if (order.Status.IsFinal()) { ... }

Extension member di C# 14

Sampai C# 14, hanya method yang bisa menjadi extension. C# 14 menambahkan blok extension, yang mengelompokkan member untuk satu receiver dan juga mengizinkan extension property dan member static:

// C# 14 and later
public static class StringExtensions
{
    extension(string s)
    {
        public bool IsBlank => string.IsNullOrWhiteSpace(s);   // extension property
        public string Truncate(int max) => s.Length <= max ? s : s[..max] + "...";
    }
}

Extension method klasik dengan parameter this tetap valid, dan itulah yang dipakai hampir semua kode dan library yang sudah ada.

Kapan sebaiknya menulisnya

Extension method cocok saat kamu tidak memiliki tipenya (string, DateTime, interface milik framework), saat kamu ingin helper yang sama ada di setiap implementasi sebuah interface, atau saat rangkaian panggilan lebih enak dibaca daripada panggilan bersarang. Saat class-nya milikmu sendiri, tambahkan method instance yang sebenarnya: method itu bisa memakai state private dan muncul di tempat pembaca mencarinya. Hindari juga memperluas object, karena method-mu akan muncul di daftar pelengkapan otomatis untuk setiap nilai di program.

Pertanyaan yang sering diajukan

Apa itu extension method di C#?

Method static yang bisa dipanggil seolah-olah method instance dari tipe lain. Kamu menulisnya di dalam class static dan menaruh this sebelum parameter pertamanya: public static bool IsBlank(this string s) => string.IsNullOrWhiteSpace(s);. Setelah itu name.IsBlank() bisa dipakai pada string apa pun, tanpa mengubah atau mewarisi string.

Kenapa extension method saya tidak ditemukan?

Extension method hanya terlihat saat namespace-nya diimpor. Kalau class static-nya ada di MyApp.Extensions, tambahkan using MyApp.Extensions; ke file yang memanggilnya; kalau tidak, compiler melaporkan CS1061, yang menyatakan bahwa tipe itu tidak punya definisi maupun extension method yang bisa diakses dengan nama tersebut. Cek juga apakah class-nya static, tidak generic, dan tidak bersarang.

Apakah extension method bisa meng-override method instance?

Tidak. Compiler mencari method instance yang cocok lebih dulu dan baru mempertimbangkan extension method kalau tidak ada. Extension dengan nama dan parameter yang sama dengan method instance diam-diam diabaikan di setiap tempat pemanggilan yang memakai sintaks instance.

Apakah extension method bisa dipanggil pada null di C#?

Bisa. Panggilannya di-compile menjadi pemanggilan method static dengan null sebagai argumen pertama, jadi tidak ada NullReferenceException yang dilempar di panggilan itu sendiri. Method-nya yang memutuskan apa yang dilakukan: menganggap null sebagai input yang valid (seperti helper bergaya IsNullOrEmpty) atau melempar ArgumentNullException, seperti yang dilakukan method LINQ.

Apakah ada extension property di C#?

Tidak ada sebelum C# 14. Sampai versi itu, hanya method yang bisa menjadi extension, jadi sesuatu yang seharusnya property ditulis sebagai method (GetFullName()). C# 14 menambahkan extension block, yang bisa mendeklarasikan extension property dan member static selain method.

Konsep terkait

Extension Method C#: Sintaks, IEnumerable, LINQ, dan Aturannya

Aturan untuk mendeklarasikannya

Memperluas interface dan IEnumerable<T>

LINQ dibangun dari extension method

Namespace-nya harus diimpor

Method instance selalu menang

Memanggil pada null

Memperluas enum

Extension member di C# 14

Kapan sebaiknya menulisnya

Pertanyaan yang sering diajukan

Belajar coding dengan Coddy