Bagikan melalui

ref jenis struktur (referensi C#)

Gunakan pengubah ref saat mendeklarasikan jenis struktur. Anda mengalokasikan instans jenis ref struct pada tumpukan, dan tidak dapat lolos ke tumpukan terkelola. Untuk memastikan properti ini, pengkompilasi membatasi penggunaan jenis ref struct sebagai berikut:

  • Anda tidak dapat menggunakan ref struct sebagai jenis elemen array.
  • Anda tidak dapat mendeklarasikan ref struct sebagai jenis bidang di kelas atau non-ref struct.
  • Anda tidak dapat menkotak ref struct ke System.ValueType atau System.Object.
  • Anda tidak dapat mengambil ref struct variabel dalam ekspresi lambda atau fungsi lokal.
  • Sebelum C# 13, Anda tidak dapat menggunakan ref struct variabel dalam async metode . Dimulai dengan C# 13, ref struct variabel tidak dapat digunakan dalam blok await yang sama dengan ekspresi dalam async metode . Namun, Anda dapat menggunakan ref struct variabel dalam metode sinkron, misalnya, dalam metode yang mengembalikan Task atau Task<TResult>.
  • Sebelum C# 13, Anda tidak dapat menggunakan ref struct variabel dalam iterator. Dimulai dengan C# 13, ref struct jenis dan ref lokal dapat digunakan dalam iterator, asalkan mereka tidak berada dalam segmen kode dengan yield return pernyataan.
  • Sebelum C# 13, ref struct antarmuka tidak dapat diterapkan. Dimulai dengan C# 13, ref struct dapat menerapkan antarmuka, tetapi harus mematuhi aturan keamanan ref. Misalnya, ref struct jenis tidak dapat dikonversi ke jenis antarmuka karena memerlukan konversi tinju.
  • Sebelum C# 13, ref struct tidak boleh berupa argumen jenis. Dimulai dengan C# 13, ref struct dapat berupa argumen jenis ketika parameter jenis menentukan dalam klausanya allows ref structwhere .

Referensi bahasa C# mendanai versi bahasa C# yang terbaru dirilis. Ini juga berisi dokumentasi awal untuk fitur dalam pratinjau publik untuk rilis bahasa yang akan datang.

Dokumentasi mengidentifikasi fitur apa pun yang pertama kali diperkenalkan dalam tiga versi terakhir bahasa atau dalam pratinjau publik saat ini.

Tip

Untuk menemukan kapan fitur pertama kali diperkenalkan di C#, lihat artikel tentang riwayat versi bahasa C#.

Biasanya, Anda menentukan ref struct jenis saat Anda memerlukan jenis yang juga menyertakan anggota data dari jenis ref struct :

public ref struct CustomRef
{
    public bool IsValid;
    public Span<int> Inputs;
    public Span<int> Outputs;
}

Untuk mendeklarasikan ref struct sebagai readonly, gabungkan readonly pengubah dan ref dalam deklarasi jenis ( readonly pengubah harus datang sebelum pengubah ref ):

public readonly ref struct ConversionRequest
{
    public ConversionRequest(double rate, ReadOnlySpan<double> values)
    {
        Rate = rate;
        Values = values;
    }

    public double Rate { get; }
    public ReadOnlySpan<double> Values { get; }
}

Di .NET, contoh ref struct adalah System.Span<T> dan System.ReadOnlySpan<T>.

ref Bidang

Anda dapat mendeklarasikan ref bidang dalam ref struct, seperti yang ditunjukkan contoh berikut:

public ref struct RefFieldExample
{
    private ref int number;

    public int GetNumber()
    {
        if (System.Runtime.CompilerServices.Unsafe.IsNullRef(ref number))
        {
            throw new InvalidOperationException("The number ref field is not initialized.");
        }

        return number;
    }
}

Bidang ref dapat memiliki nilai .null Unsafe.IsNullRef<T>(T) Gunakan metode untuk menentukan apakah ref bidang adalah null.

Anda bisa menerapkan pengubah readonly ke ref bidang dengan cara berikut:

  • readonly ref: Anda dapat menetapkan ulang bidang ini dengan menggunakan = ref operator hanya di dalam konstruktor atau init aksesor. Anda dapat menetapkan nilai dengan = operator kapan saja yang diizinkan oleh pengubah akses bidang.
  • ref readonly: Pada titik mana pun, Anda tidak dapat menetapkan nilai dengan = operator ke bidang ini. Namun, Anda dapat menetapkan ulang bidang dengan menggunakan = ref operator.
  • readonly ref readonly: Anda hanya dapat menetapkan ulang bidang ini di konstruktor atau init aksesor. Pada titik mana pun, Anda tidak dapat menetapkan nilai ke bidang .

Pengkompilasi memastikan bahwa referensi yang disimpan di ref bidang tidak melampaui referensinya.

Fitur ref bidang memungkinkan implementasi jenis yang aman seperti System.Span<T>:

public readonly ref struct Span<T>
{
    internal readonly ref T _reference;
    private readonly int _length;

    // Omitted for brevity...
}

Jenis menyimpan Span<T> referensi di mana ia mengakses elemen yang bersebelahan dalam memori. Dengan menggunakan referensi, Span<T> instans menghindari penyalinan penyimpanan yang dirujuknya.

Pola sekali pakai

Anda dapat menentukan sekali pakai ref struct. Untuk melakukan itu, pastikan bahwa ref struct sesuai dengan pola sekali pakai. Artinya, ia memiliki metode instans Dispose yang dapat diakses, tanpa parameter, dan memiliki void jenis pengembalian. Anda dapat menggunakan pernyataan penggunaan atau deklarasi dengan instans sekali pakai ref struct.

Dimulai dengan C# 13, Anda juga dapat menerapkan IDisposable jenisnya ref struct . Namun, resolusi kelebihan beban lebih memilih pola sekali pakai ke metode antarmuka. Pengkompilasi diselesaikan ke IDisposable.Dispose metode hanya ketika metode yang sesuai Dispose tidak ditemukan.

Pembatasan untuk ref struct jenis yang mengimplementasikan antarmuka

Pembatasan ini memastikan bahwa ref struct jenis yang mengimplementasikan antarmuka mengikuti aturan keamanan ref yang diperlukan.

  • Anda tidak dapat mengonversi ref struct ke instans antarmuka yang diterapkannya. Pembatasan ini mencakup konversi implisit saat Anda menggunakan ref struct jenis sebagai argumen dan parameter adalah jenis antarmuka. Konversi menghasilkan konversi tinju, yang melanggar keamanan ref. ref struct dapat mendeklarasikan metode sebagai deklarasi antarmuka eksplisit. Namun, Anda hanya dapat mengakses metode tersebut dari metode generik tempat jenis parameter allows ref struct jenis.
  • ref struct yang mengimplementasikan antarmuka harus mengimplementasikan semua anggota antarmuka instans. ref struct harus menerapkan anggota instans bahkan ketika antarmuka menyertakan implementasi default.

Kompilator memberlakukan pembatasan ini. Jika Anda menulis ref struct jenis yang menerapkan antarmuka, setiap pembaruan baru mungkin menyertakan anggota antarmuka default baru. Hingga Anda memberikan implementasi untuk metode instans baru apa pun, aplikasi Anda tidak dikompilasi. Anda tidak dapat memberikan implementasi tertentu untuk metode antarmuka static dengan implementasi default.

Penting

Menerapkan antarmuka dengan ref struct jenis memperkenalkan potensi perubahan pemecahan sumber dan pemecahan biner nanti. Jeda terjadi jika ref struct mengimplementasikan antarmuka yang ditentukan dalam rakitan lain, dan perakitan tersebut menyediakan pembaruan yang menambahkan anggota default ke antarmuka tersebut.

Pemisah sumber terjadi ketika Anda mengkompilasi ref structulang : Ini harus mengimplementasikan anggota baru, meskipun ada implementasi default.

Pemutus biner terjadi jika Anda meningkatkan rakitan eksternal tanpa mengkompilasi ref struct ulang jenis dan kode yang diperbarui memanggil implementasi default metode baru. Runtime melemparkan pengecualian saat anggota default diakses.

Spesifikasi bahasa C#

Untuk informasi selengkapnya, lihat bagian berikut dari spesifikasi bahasa C#:

Untuk informasi selengkapnya tentang ref bidang, lihat catatan proposal peningkatan struct tingkat rendah.

Lihat juga

  • Last updated on