Anggota parsial (Referensi C#)

Anggota parsial memiliki satu deklarasi yang menyatakan dan sering kali satu mengimplementasikan deklarasi. Deklarasi deklarasi tidak termasuk isi. Deklarasi pelaksana menyediakan isi anggota. Anggota parsial memungkinkan perancang kelas untuk menyediakan kait anggota untuk alat seperti generator sumber untuk diterapkan. Jenis dan anggota parsial menyediakan cara bagi pengembang manusia untuk menulis bagian dari jenis sementara alat menulis bagian lain dari jenis tersebut. Jika pengembang tidak menyediakan deklarasi penerapan opsional, kompilator dapat menghapus deklarasi deklarasi pada waktu kompilasi. Kondisi berikut berlaku untuk anggota parsial:

• Deklarasi harus dimulai dengan kata kunci kontekstual parsial.
• Tanda tangan di kedua bagian jenis parsial harus cocok.

Kata partial kunci tidak diizinkan pada konstruktor statis, finalizer, atau operator yang kelebihan beban. Sebelum C# 14, partial tidak diizinkan pada konstruktor instans atau deklarasi peristiwa. Sebelum C# 13, partial tidak diizinkan pada properti atau pengindeks.

Metode parsial tidak diperlukan untuk memiliki deklarasi penerapan dalam kasus berikut:

• Ini tidak memiliki pengubah aksesibilitas (termasuk default private).
• Hal ini mengembalikan void.
• Ini tidak memiliki parameter apa pun out .
• Ini tidak memiliki salah satu pengubah virtualberikut , , override, sealed, newatau extern.

Contoh berikut menunjukkan metode parsial yang sesuai dengan pembatasan sebelumnya:

partial class MyPartialClass
{
    // Declaring definition
    partial void OnSomethingHappened(string s);
}

// This part can be in a separate file.
partial class MyPartialClass
{
    // Comment out this method and the program
    // will still compile.
    partial void OnSomethingHappened(string s) =>
        Console.WriteLine($"Something happened: {s}");
}

Setiap anggota yang tidak sesuai dengan semua batasan tersebut (misalnya, public virtual partial void metode), harus memberikan implementasi.

Properti parsial, pengindeks, dan peristiwa tidak dapat menggunakan sintaks yang diimplementasikan secara otomatis untuk deklarasi penerapan. Deklarasi yang mendefinisikan menggunakan sintaks yang sama. Deklarasi penerapan harus mencakup setidaknya satu aksesor yang diimplementasikan. Aksesor tersebut dapat menjadi properti yang didukung bidang. Deklarasi penerapan untuk peristiwa parsial harus menentukan penangan add dan remove .

Anggota parsial juga dapat berguna dalam kombinasi dengan generator sumber. Misalnya regex dapat didefinisikan menggunakan pola berikut:

public partial class RegExSourceGenerator
{
    [GeneratedRegex("cat|dog", RegexOptions.IgnoreCase, "en-US")]
    private static partial Regex CatOrDogGeneratedRegex();

    private static void EvaluateText(string text)
    {
        if (CatOrDogGeneratedRegex().IsMatch(text))
        {
            // Take action with matching text
        }
    }
}

Contoh sebelumnya menunjukkan metode parsial yang harus memiliki deklarasi penerapan. Sebagai bagian dari build, generator sumber ekspresi reguler membuat deklarasi penerapan.

Contoh berikut menunjukkan deklarasi deklarasi dan deklarasi penerapan untuk kelas. Karena jenis pengembalian metode bukan void ( stringadalah ) dan aksesnya adalah public, metode harus memiliki deklarasi penerapan:

// Declaring declaration
public partial class PartialExamples
{
    /// <summary>
    /// Gets or sets the number of elements that the List can contain.
    /// </summary>
    public partial int Capacity { get; set; }

    /// <summary>
    /// Gets or sets the element at the specified index.
    /// </summary>
    /// <param name="index">The index</param>
    /// <returns>The string stored at that index</returns>
    public partial string this[int index] { get; set; }

    public partial string? TryGetAt(int index);
}

public partial class PartialExamples
{
    private List<string> _items = [
        "one",
        "two",
        "three",
        "four",
        "five"
        ];

    // Implementing declaration

    /// <summary>
    /// Gets or sets the number of elements that the List can contain.
    /// </summary>
    /// <remarks>
    /// If the value is less than the current capacity, the list will shrink to the
    /// new value. If the value is negative, the list isn't modified.
    /// </remarks>
    public partial int Capacity
    {
        get => _items.Count;
        set
        {
            if ((value != _items.Count) && (value >= 0))
            {
                _items.Capacity = value;
            }
        }
    }

    public partial string this[int index]
    {
        get => _items[index];
        set => _items[index] = value;
    }

    /// <summary>
    /// Gets the element at the specified index.
    /// </summary>
    /// <param name="index">The index</param>
    /// <returns>The string stored at that index, or null if out of bounds</returns>
    public partial string? TryGetAt(int index)
    {
        if (index < _items.Count)
        {
            return _items[index];
        }
        return null;
    }
}

Contoh sebelumnya menggambarkan aturan tentang bagaimana dua deklarasi digabungkan:

• Tanda tangan cocok: Secara umum, tanda tangan untuk deklarasi deklarasi dan penerapan harus cocok. Ini termasuk pengubah aksesibilitas pada metode, properti, pengindeks, dan aksesor individual. Ini termasuk jenis parameter dan pengubah jenis ref pada semua parameter. Jenis pengembalian dan pengubah jenis ref apa pun harus cocok. Nama anggota Tuple harus cocok. Namun, beberapa aturan bersifat fleksibel:
  • Deklarasi deklarasi dan penerapan dapat memiliki pengaturan anotasi nullable yang berbeda. Berarti bahwa seseorang dapat menjadi tidak sadar null dan yang lain diaktifkan nullable.
  • Perbedaan nullability yang tidak melibatkan nullability oblivious menghasilkan peringatan.
  • Nilai parameter default tidak perlu cocok. Kompilator mengeluarkan peringatan jika deklarasi penerapan metode atau pengindeks mendeklarasikan nilai parameter default.
  • Pengkompilasi mengeluarkan peringatan saat nama parameter tidak cocok. IL yang dipancarkan berisi nama parameter deklarasi yang mendeklarasikan.
• Komentar dokumentasi: Komentar dokumentasi dapat disertakan dari salah satu deklarasi. Jika pernyataan deklarasi dan penerapan menyertakan komentar dokumentasi, komentar dari deklarasi pelaksana disertakan. Dalam contoh sebelumnya, komentar dokumentasi meliputi:
  • Capacity Untuk properti , komentar diambil dari deklarasi penerapan. Komentar deklarasi penerapan digunakan ketika kedua deklarasi memiliki /// komentar.
  • Untuk pengindeks, komentar diambil dari deklarasi deklarasi. Deklarasi penerapan tidak menyertakan komentar apa pun /// .
  • Untuk TryGetAt, komentar diambil dari deklarasi penerapan. Deklarasi deklarasi tidak menyertakan komentar apa pun /// .
  • XML yang dihasilkan memiliki komentar dokumentasi untuk semua public anggota.
• Sebagian besar deklarasi Atribut digabungkan. Namun, semua atribut info penelepon didefinisikan dengan AllowMultiple=false. Kompilator mengenali atribut info pemanggil apa pun pada deklarasi deklarasi. Semua atribut info penelepon pada deklarasi penerapan diabaikan. Kompilator mengeluarkan peringatan jika Anda menambahkan atribut info penelepon pada deklarasi penerapan.

Lihat juga

• jenis parsial