`ref` 結構類型 (C# 參考)

您可以在ref的宣告中，使用修飾詞。 ref struct 類型的執行個體，會配置在堆疊上，且無法逸出至受控堆積。為確保這一點，編譯器對於 ref struct 類型的使用限制如下：

ref struct 不能是陣列的元素類型。
ref struct 不能是類別或非 ref struct 欄位的宣告類型。
無法將 ref struct box 到 System.ValueType 或 System.Object。
ref struct或區域函式無法擷取變數。
在 C# 13 之前， ref struct 無法在方法中使用 async 變數。從 C# 13 開始，ref struct 變數不能用於 await 方法中 async 表達式的相同區塊中。但是您可以在同步方法中使用 ref struct 變數，例如，用在傳回 Task 或 Task<TResult> 的方法中。
在 C# 13 之前，ref struct 變數不能用於迭代器中。從 C# 13 開始，可以在迭代器中使用 ref struct 類型和 ref 區域變數，前提是其不在 yield return 陳述式的程式碼區段中。
在 C# 13 之前，ref struct 無法實作介面。從 C# 13 開始，ref 結構可以實作介面，但必須遵守 ref 安全規則。例如，ref struct 型別無法轉換成介面型別，因為需要 Boxing 轉換。
在 C# 13 之前，ref struct 不能是型別引數。從 C# 13 開始，當型別參數在其 ref struct 子句中指定 allows ref struct 時，where 可以是型別引數。

一般而言，當您需要也包含 ref struct 類型的資料成員之類型時，要定義 ref struct 類型：

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

若要將 ref struct 宣告為 readonly，請在型別宣告中合併 readonly 和 ref 修飾詞 (readonly 修飾詞必須位於 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; }
}

在 NET 中，ref struct 的範例為 System.Span<T> 和 System.ReadOnlySpan<T>。

`ref` 欄位

你可以宣告 ref 一個欄位， ref struct如下範例所示：

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;
    }
}

ref 欄位的值可能為 null。使用 Unsafe.IsNullRef<T>(T) 方法可判斷 ref 欄位是否為 null。

您可用下列方式，對 readonly 欄位套用 ref 修飾詞：

readonly ref：只有在建構函式或內，可以用 = ref 運算子，init這樣的欄位。您可以利用欄位存取修飾詞，在允許的任何時間點，使用 = 運算子來指派值。
ref readonly：您任何時間點都無法對此類欄位指派包含 = 運算子的值。但可以使用 = ref 運算子，ref 重新指派欄位。
readonly ref readonly：您只能在建構函式或 init 存取子中，重新指派。這樣的欄位。您任何時間點都無法對欄位指派值。

編譯器可確保儲存在 ref 欄位中的參考不會比其所參考的值存留更久。

ref 欄位功能可讓您安全實作類型，例如 System.Span<T>：

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

    // Omitted for brevity...
}

Span<T> 類型會儲存參考，以透過參考來存取記憶體中的連續元素。使用參考可讓 Span<T> 執行個體避免複製其參考的儲存體。

可處置模式

您可以定義可處置的 ref struct。若要這樣做，請確定 ref struct 符合可處置模式。也就是說，它有一個可存取、無參數且具有Dispose傳回類型的實例void方法。您可以使用 using 陳述式或宣告，搭配可處置 ref struct 的執行個體。

從 C# 13 開始，您也可以在 IDisposable 型別上實作 ref struct。不過，多載解析偏好介面方法的可處置模式。只有在找不到適當的IDisposable.Dispose方法時，編譯程式才會解析為 Dispose 方法。

實作介面的 `ref struct` 型別限制

這些限制可確保實作介面的 ref struct 型別遵守必要的 ref 安全規則。

ref struct 無法轉換成它所實作之介面的執行個體。參數若為介面型別，當您使用 ref struct 型別作為引數時，此限制會包括隱含轉換。轉換會導致 Boxing 轉換，這違反了 ref 安全。 ref struct 可以將方法宣告為明確的介面宣告。不過，這些方法只能從擁有類型參數 allows ref struct 的泛型方法中存取。
實作介面 的 ref struct 必須 實作所有實例介面成員。即使介面包含預設實作，ref struct 也必須實作實例成員。

編譯器會強制執行這些限制。如果您撰寫實作介面的 ref struct 型別，則每個新的更新都可能包括新的預設介面成員。除非你提供任何新實例方法的實作，否則你的應用程式不會編譯。您無法為具有預設實作的 static 介面方法提供特定的實作。

重要

實作介面的 ref struct 包括後續原始檔中斷和二進位中斷變更的可能性。若 a ref struct 實作了另一個組件中定義的介面，而該組件提供了更新，將預設成員加入該介面，則會發生中斷。

當您重新編譯 ref struct時，會發生源碼中斷：即使有預設的實作，它仍必須實作新的成員。

如果您升級外部組件而不重新編譯 ref struct 型別，而且更新的程式碼會呼叫新方法的預設實作，即會發生二進位中斷。存取預設成員時，執行階段會擲回例外狀況。

C# 語言規格

如需詳細資訊，請參閱 C# 語言規格的下列幾節：

如需 ref 欄位的詳細資訊，請參閱低階結構改善提案附註。

另請參閱

C# 類型系統

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-20

共用方式為

ref 結構類型 (C# 參考)

ref 欄位