Unsafe 類別

定義

命名空間:

System.Runtime.CompilerServices

組件:

System.Runtime.dll

來源:

Unsafe.cs

包含通用且低階的功能，用於操作受管理與非受管理指標。

public ref class Unsafe abstract sealed

public static class Unsafe

type Unsafe = class

Public Class Unsafe

繼承

Object

Unsafe

備註

警告

此類型適用於進階指標操作場景。 來電者假設熟悉 ECMA-335，第 II.14.4 節及第 III.1.1.5 條，以及 ECMA-335 CLI 規範附錄。

大多數此類 API 不會執行任何參數檢查或驗證。 錯誤使用這些 API 可能會損壞程序記憶體或使 .NET 執行環境不穩定。

此型態通常由低階函式庫作者使用，他們希望撰寫高效能程式碼，並願意抑制 .NET 典型的型別安全檢查以達成效能目標。

考慮以下範例，該範例將元素反轉。Span<T>

Note

這些範例僅供示範使用。 在實際應用中，開發者應使用像 Reverse這樣的輔助函數，這些比這些範例更優化。

// A safe, verifiable way to reverse a Span<T>.
static void Reverse<T>(Span<T> span)
{
 while (span.Length > 1)
 {
   T firstElement = span[0];
   T lastElement = span[^1];
   span[0] = lastElement;
   span[^1] = firstElement;
   span = span[1..^1];
 }
}

此方法完全型別安全，且 .NET 執行時可插入邊界檢查以協助執行安全。 然而，低階函式庫作者可能想抑制 .NET 的正常安全檢查，以提升自身程式碼的效能。 這類開發者通常會依賴靜態分析工具或自身的程式碼審查來協助執行正確性。 這些 Unsafe API 允許開發者使用無法驗證的結構重寫這些程式碼，如下範例所示。

// A correct but unverifiable way to reverse a Span<T>.
static void Reverse<T>(Span<T> span)
{
 if (span.Length > 1)
 {
   ref T refLeft = ref MemoryMarshal.GetReference(span);
   ref T refRight = ref Unsafe.Add(ref refLeft, span.Length - 1);
   do
   {
     T leftElement = refLeft;
     T rightElement = refRight;
     refLeft = rightElement;
     refRight = leftElement;
     refLeft = ref Unsafe.Add(ref refLeft, 1);
     refRight = ref Unsafe.Subtract(ref refRight, 1);
   } while (Unsafe.IsAddressLessThan(ref refLeft, ref refRight));
 }
}

由於 Unsafe API 抑制了典型的型別安全驗證，呼叫者必須確保他們所撰寫的程式碼是合法的。 這些 API 的濫用可能導致存取違規、產生 GC 漏洞、產生錯誤的程式碼生成，或在 .NET 執行環境中引發未定義且不穩定的行為。

方法

名稱	Description
Add<T>(T, Int32)	會為給定的管理指標增加一個偏移量。
Add<T>(T, IntPtr)	為所管理指標新增一個元素偏移量。
Add<T>(T, UIntPtr)	為所管理指標新增一個元素偏移量。
Add<T>(Void*, Int32)	為給定的未管理指標加上一個元素偏移量。
AddByteOffset<T>(T, IntPtr)	為所管理指標增加一個位元組偏移量。
AddByteOffset<T>(T, UIntPtr)	為所管理指標增加一個位元組偏移量。
AreSame<T>(T, T)	判斷指定的管理指標是否指向相同位置。
As<T>(Object)	將給定物件投射到指定的類型。
As<TFrom,TTo>(TFrom)	將給定的受管理指標重新詮釋為一個新的受管理指標，指向一個型別 TTo為 的值。
AsPointer<T>(T)	將一個受管理指標轉換成一個未管理指標。
AsRef<T>(T)	將給定的唯讀參考重新詮釋為可變的參考。
AsRef<T>(Void*)	將一個未管理指標轉換為受管理指標，並轉換為型別 T為 的值。
BitCast<TFrom,TTo>(TFrom)	將給定的值 TFrom 重新詮釋為型別 TTo的值。
ByteOffset<T>(T, T)	從給定的管理指標決定從起點到目標的位元組偏移量。
Copy<T>(T, Void*)	將型態 T 的值複製到指定位置。
Copy<T>(Void*, T)	將型態 T 的值複製到指定位置。
CopyBlock(Byte, Byte, UInt32)	將來源位址的位元組複製到目的位址。
CopyBlock(Void*, Void*, UInt32)	將來源位址的位元組複製到目的位址。
CopyBlockUnaligned(Byte, Byte, UInt32)	從來源位址複製位元組到目的位址，且不假設位址依架構對齊。
CopyBlockUnaligned(Void*, Void*, UInt32)	從來源位址複製位元組到目的位址，且不假設位址依架構對齊。
InitBlock(Byte, Byte, UInt32)	在指定位置初始化記憶體區塊，初始值為特定。
InitBlock(Void*, Byte, UInt32)	在指定位置初始化記憶體區塊，初始值為特定。
InitBlockUnaligned(Byte, Byte, UInt32)	在指定位置初始化記憶體區塊，並以給定的初始值，且不假設該位址依架構對齊。
InitBlockUnaligned(Void*, Byte, UInt32)	在指定位置初始化記憶體區塊，並以給定的初始值，且不假設該位址依架構對齊。
IsAddressGreaterThan<T>(T, T)	回傳一個值，表示某個指定的管理指標是否大於另一個指定的管理指標。
IsAddressGreaterThanOrEqualTo<T>(T, T)	判斷 所left參考的記憶體位址是否大於或等於 。right
IsAddressLessThan<T>(T, T)	回傳一個值，表示某個指定管理指標是否小於另一個指定管理指標。
IsAddressLessThanOrEqualTo<T>(T, T)	判斷 所left參考的記憶體位址是否小於或等於 。right
IsNullRef<T>(T)	判斷某個受管理指標指向某值 T 的值是否為空參考。
NullRef<T>()	回傳一個空管理指標，指向型別 T為 的值。
Read<T>(Void*)	讀取給定位置的值 T 。
ReadUnaligned<T>(Byte)	從給定位址讀取型別 T 值，且不假設來源位址依架構對齊。
ReadUnaligned<T>(Void*)	從指定位置讀取 type T 值，且不假設來源地址依架構對齊。
SizeOf<T>()	回傳給定型別參數值的大小。
SkipInit<T>(T)	繞過特定參考的明確指派規則。
Subtract<T>(T, Int32)	從給定的管理指標中減去一個偏移量。
Subtract<T>(T, IntPtr)	從給定的管理指標中減去一個偏移的元素。
Subtract<T>(T, UIntPtr)	從給定的管理指標中減去一個偏移的元素。
Subtract<T>(Void*, Int32)	從給定的未管理指標中減去一個偏移的元素。
SubtractByteOffset<T>(T, IntPtr)	從給定的管理指標減去一個位元組偏移量。
SubtractByteOffset<T>(T, UIntPtr)	從給定的管理指標減去一個位元組偏移量。
Unbox<T>(Object)	將 a mutable ref 回傳為框值。
Write<T>(Void*, T)	會將 type T 值寫入給定位置。
WriteUnaligned<T>(Byte, T)	在不假設目的位址依架構對齊的情況下，將 type T 寫入給定位置。
WriteUnaligned<T>(Void*, T)	在不假設目的位址依架構對齊的情況下，將 type T 寫入給定位置。