ref 結構類型 (C# 參考)

  • 發行項

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

  • ref struct 不能是陣列的元素類型。
  • ref struct 不能是類別或非 ref struct 欄位的宣告類型。
  • ref struct 無法實作介面。
  • 無法將 ref struct box 到 System.ValueType 或 System.Object。
  • ref struct 不能是型別引數。
  • Lambda 運算式或區域函式無法擷取 ref struct 變數。
  • ref struct 變數不能用在 async 方法中。 但是您可以在同步方法中使用 ref struct 變數，例如，用在傳回 Task 或 Task<TResult> 的方法中。
  • ref struct 變數不能用於迭代器中。

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

一般而言，當您需要也包含 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 欄位

從 C# 11 開始，您可以在 ref struct 中宣告 ref 欄位，如下列範例所示：

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。

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

  • readonly ref：只有在建構函式或 init 存取子內，可以用 = ref 運算子，ref 重新指定這樣的欄位。 您可以利用欄位存取修飾詞，在允許的任何時間點，使用 = 運算子來指派值。
  • 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> 執行個體避免複製其參考的儲存體。

C# 語言規格

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

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

另請參閱