Reflection in .NET has traditionally been powerful but slow. Starting with .NET 8, the [UnsafeAccessor] attribute provides a zero-overhead alternative for accessing private members, offering performance comparable to direct access and a strongly typed syntax at call site.
Traditional Reflection
Before UnsafeAccessor, accessing private fields or methods required this reflection syntax:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
using System.Reflection; var employee = new Employee(); var field = typeof(Employee).GetField("_ssn", BindingFlags.NonPublic | BindingFlags.Instance); var ssn = (string)field.GetValue(employee); // Boxing, slow Console.ReadKey(); public class Employee { private string _ssn = "123-45-6789"; private void CalculateBonus() { } } |
This approach suffers from:
- Runtime overhead from reflection calls
- Boxing/unboxing for value types
- Difficult to optimize for the JIT compiler
- Multiple API calls: GetField(), GetValue()…
.NET 8: UnsafeAccessor Introduction
.NET 8 introduced System.Runtime.CompilerServices.UnsafeAccessor to solve these problems. It works by declaring extern methods that the runtime implements with direct access:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
using System.Runtime.CompilerServices; // Usage - fast, consice, type-safe var employee = new Employee(); ref string ssn = ref EmployeeAccessor.GetSSN(employee); Console.WriteLine(ssn); // "123-45-6789" ssn = "999-99-9999"; // Direct modification of the field EmployeeAccessor.CallCalculateBonus(employee, 0.15m); public static class EmployeeAccessor { // Access private field [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_ssn")] public static extern ref string GetSSN(Employee employee); // Access private method [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "CalculateBonus")] public static extern void CallCalculateBonus(Employee employee, decimal percentage); } public class Employee { private string _ssn = "123-45-6789"; private int _salary = 50000; private void CalculateBonus(decimal percentage) { Console.WriteLine($"Bonus: {_salary * percentage}"); } } |
Remarks:
GetSSN()returns aref string, meaning it doesn’t return a reference to the string but a managed pointer to the actual field inside theemployeeobject. Through this managed pointer, you can both read the current value and directly assign a new string to the underlying field.- If the member specified by the
Nameparameter doesn’t exist, the runtime throws aMissingFieldExceptionorMissingMethodException. The extern method’s signature is strongly typed, ensuring compile-time safety at the call site. However, like with traditional reflection, there are no compile-time guarantees that the target specified by the string actually exists. - The enum
System.Runtime.CompilerServices.UnsafeAccessorKindis defined as follow:
|
1 2 3 4 5 6 7 |
public enum UnsafeAccessorKind { Field, // Access private fields Method, // Call private methods Constructor, // Access private constructors StaticField, // Access private static fields StaticMethod // Call private static methods } |
- Finally, unsafe accessor methods can be declared within the current type and also as a local method within a method. Below is the code rewritten with these methods declared in the
Programclass generated by the top-level statements syntax:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
using System.Runtime.CompilerServices; // Usage - fast, consice, type-safe var employee = new Employee(); ref string ssn = ref GetSSN(employee); Console.WriteLine(ssn); // "123-45-6789" ssn = "999-99-9999"; // Direct modification of the field CallCalculateBonus(employee, 0.15m); [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_ssn")] static extern ref string GetSSN(Employee employee); [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "CalculateBonus")] static extern void CallCalculateBonus(Employee employee, decimal percentage); public class Employee { private string _ssn = "123-45-6789"; private int _salary = 50000; private void CalculateBonus(decimal percentage) { Console.WriteLine($"Bonus: {_salary * percentage}"); } } |
.NET 9: Enhanced Generic Support
.NET 9 improved UnsafeAccessor with better generic type handling and more flexible member access:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
using System.Runtime.CompilerServices; var cache = new Cache<int>(); ref var items = ref CacheAccessor<int>.GetItems(cache); items["key1"] = 100; CacheAccessor<int>.CallEvict(cache, "key1"); public class Cache<T> { // Custom generic type private Dictionary<string, T> _items = new(); private void Evict(string key) { _items.Remove(key); } } public static class CacheAccessor<T> { [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_items")] public static extern ref Dictionary<string, T> GetItems(Cache<T> cache); [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "Evict")] public static extern void CallEvict(Cache<T> cache, string key); } |
Unlike in the previous section, here the generic class CacheAccessor<T> is required to declare the type parameter T. This is because the unsafe accessor methods cannot be declared as generic themselves. Doing so compiles since it is valid C#, but it fails at runtime:
Accessing private members of generic class is useful, for instance, to access the internals of generic collections. This can also be achieved also using System.Runtime.InteropServices.CollectionsMarshal. Both ways are illustrated by the program below:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
using System.Diagnostics; using System.Runtime.CompilerServices; using System.Runtime.InteropServices; var list = new List<int>(Enumerable.Range(0, 691)); int[] items = Accessors<int>.GetItems(list); // Obtain the array backing the List<T> Span<int> span = CollectionsMarshal.AsSpan(list); // Obtain a Span<T> over the same array Debug.Assert(span.Length == items.Length); Debug.Assert(items[0] == 0); span[0] = 42; Debug.Assert(items[0] == 42); static class Accessors<T> { [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_items")] public static extern ref T[] GetItems(List<T> list); } |
Naturally, the array backing a List<T> is private for a reason. When elements are added or removed, the list implementation may reallocate a larger or smaller array. Directly manipulating this private array can therefore cause subtle and complex bugs if the list’s size changes concurrently.
Benchmarking UnsafeAccessor Reflection vs Traditional reflection
The benchmark below extracted from the article Performance Improvements in .NET 10 by Stephen Toub, proves that UnsafeAccessor based reflection is faster than traditional reflection:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
using BenchmarkDotNet.Attributes; using BenchmarkDotNet.Running; using System.Reflection; using System.Runtime.CompilerServices; BenchmarkSwitcher.FromAssembly(typeof(Tests).Assembly).Run(args); [HideColumns("Job", "Error", "StdDev", "Median", "RatioSD")] public partial class Tests { private List<int> _list = new List<int>(16); private FieldInfo _itemsField = typeof(List<int>).GetField("_items", BindingFlags.NonPublic | BindingFlags.Instance)!; private static class Accessors<T> { [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_items")] public static extern ref T[] GetItems(List<T> list); } [Benchmark] public int[] WithReflection() => (int[])_itemsField.GetValue(_list)!; [Benchmark] public int[] WithUnsafeAccessor() => Accessors<int>.GetItems(_list); } |
Here is the result:
|
1 2 3 4 |
| Method | Mean | |------------------- |----------:| | WithReflection | 3.4947 ns | | WithUnsafeAccessor | 0.9290 ns | |
.NET 10.0 UnsafeAccessorType
Before .NET 10.0, if a parameter or return type could not be resolved at compile time, UnsafeAccessor-based reflection would fail at runtime. This typically occurs when encapsulation restricts type visibility, such as with a private nested type or an internal type not visible to external assemblies.
.NET 10.0 addresses this limitation with the UnsafeAccessorType attribute. The fully-qualified name of the hidden type name must be provided as a string. The following program demonstrates how it works with the private nested type HiddenClass.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
using System.Diagnostics; using System.Runtime.CompilerServices; using MyNamespace; var visibleObject = new VisibleClass(); object hiddenObject = ReadVisibleClassField(visibleObject); string value = ReadHiddenClassProperty(hiddenObject); Debug.Assert(value == "Hello world"); // "MyNamespace.VisibleClass+HiddenClass" is the fully-qualified name of the private hidden class [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "GetField")] [return: UnsafeAccessorType("MyNamespace.VisibleClass+HiddenClass")] static extern object ReadVisibleClassField(VisibleClass instance); [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "get_Prop")] static extern string ReadHiddenClassProperty([UnsafeAccessorType("MyNamespace.VisibleClass+HiddenClass")] object instance); namespace MyNamespace { public class VisibleClass { private readonly HiddenClass _field = new("Hello world"); private HiddenClass GetField() => _field; private class HiddenClass(string prop) { internal string Prop { get; } = prop; } } } |
Commenting UnsafeAccessorType usage leads to an exception thrown at runtime:
Conclusion
Bypassing visibility isn’t something you do every day, but it’s convenient to have a concise, zero-overhead way to do it when needed.
Accessing private members via reflection is generally discouraged, but it can be justified in certain situations. For example when accessing dictionary internal layout with managed pointers to increase performance.
In the blog post already referenced Performance Improvements in .NET 10, Stephen Toub explains another scenario:
“An example of where this is handy is with a cyclic relationship between System.Net.Http and System.Security.Cryptography. System.Net.Http sits above System.Security.Cryptography, referencing it for critical features like X509Certificate. But System.Security.Cryptography needs to be able to make HTTP requests in order to download OCSP information, and with System.Net.Http referencing System.Security.Cryptography, System.Security.Cryptography can’t in turn explicitly reference System.Net.Http. It can, however, use reflection or [UnsafeAccessor] and [UnsafeAccessorType] to do so, and it does. It used to use reflection, now in .NET 10 it uses [UnsafeAccessor].”