Refactor symbol cache to unified, view-based API

Major overhaul of the symbol reflection info cache:
- Introduced view-based, memory-safe, ALC-aware API for all symbol kinds (type, method, property, event, field, parameter, constructor)
- Added TryGet*CacheEntry and GetOrCreateCacheEntry methods returning view interfaces (e.g., ITypeDataView) instead of internal cache entries
- Unified symbol lookup with s_wellKnownSymbolCacheKeyTable keyed by object
- Updated all data classes to expose their view via a .View property
- Improved parameter handling, including normalization of ambiguous indexer parameters
- Enhanced detection of ref readonly and in parameters
- Improved and clarified XML documentation throughout
- Moved AnonymousSymbolDescriptorContainer to its own file and restored implementation
- General code cleanup, null checks, and error handling improvements

Author: BionicCode

src/BionicCode.Utilities.Reflection/AnonymousSymbolDescriptorContainer.cs

@@ -0,0 +1,266 @@
+namespace BionicCode.Utilities.Net.Reflection;
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Reflection;
+using System.Runtime.CompilerServices;
+
+internal readonly struct AnonymousSymbolDescriptorContainer : IEquatable<AnonymousSymbolDescriptorContainer>
+{
+    /// <summary>
+    /// Represents an unknown or unspecified parameter count.
+    /// </summary>
+    /// <remarks>Use this constant to indicate that the number of parameters is not known or cannot be
+    /// determined. This value is typically used in APIs where the parameter count is optional or
+    /// variable.</remarks>
+    public const int UnknownParameterCountOrPosition = SymbolReflectionInfoCacheKeyInternal.UnknownParameterCountOrPosition;
+
+    /// <summary>
+    /// Gets the name of the symbol represented by this instance.
+    /// </summary>
+    /// <value>The name of the symbol, such as the method name, property name, event name, field name, or type name.</value>
+    public readonly string SymbolName { get; }
+
+    /// <summary>
+    /// Gets the kind of symbol represented by this instance.
+    /// </summary>
+    /// <value>The kind of symbol, such as type, method, property, event, field, constructor, or parameter.</value>
+    public readonly SymbolKind SymbolKind { get; }
+
+    private readonly AnonymousParameterDescriptor _parameterDescriptor;
+    public AnonymousParameterDescriptor ParameterDescriptor => SymbolKind is SymbolKind.Parameter
+        ? _parameterDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousParameterDescriptor>([SymbolKind.Parameter]);
+
+    private readonly AnonymousPropertyDescriptor _propertyDescriptor;
+    public AnonymousPropertyDescriptor PropertyDescriptor => SymbolKind is SymbolKind.MemberProperty
+        ? _propertyDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousPropertyDescriptor>([SymbolKind.MemberProperty]);
+
+    private readonly AnonymousMethodDescriptor _methodDescriptor;
+    public AnonymousMethodDescriptor MethodDescriptor => SymbolKind is SymbolKind.MemberMethod
+        ? _methodDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousMethodDescriptor>([SymbolKind.MemberMethod]);
+
+    private readonly AnonymousConstructorDescriptor _constructorDescriptor;
+    public AnonymousConstructorDescriptor ConstructorDescriptor => SymbolKind is SymbolKind.MemberConstructor
+        ? _constructorDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousConstructorDescriptor>([SymbolKind.MemberConstructor]);
+
+    private readonly AnonymousFieldDescriptor _fieldDescriptor;
+    public AnonymousFieldDescriptor FieldDescriptor => SymbolKind is SymbolKind.MemberField
+        ? _fieldDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousFieldDescriptor>([SymbolKind.MemberField]);
+
+    private readonly AnonymousEventDescriptor _eventDescriptor;
+    public AnonymousEventDescriptor EventDescriptor => SymbolKind is SymbolKind.MemberEvent
+        ? _eventDescriptor
+        : ThrowInvalidPropertyContextException<AnonymousEventDescriptor>([SymbolKind.MemberEvent]);
+
+    private readonly bool _isExplicitInterfaceImplementation;
+    public bool IsExplicitInterfaceImplementation => SymbolKind is SymbolKind.MemberProperty or SymbolKind.MemberEvent or SymbolKind.MemberMethod
+        ? _isExplicitInterfaceImplementation
+        : ThrowInvalidPropertyContextException<bool>([SymbolKind.MemberProperty, SymbolKind.MemberEvent, SymbolKind.MemberMethod]);
+
+    private readonly int _hashCode;
+
+    private AnonymousSymbolDescriptorContainer(
+        string name,
+        SymbolKind symbolKind,
+        AnonymousParameterDescriptor parameterDescriptor,
+        AnonymousMethodDescriptor methodDescriptor,
+        AnonymousConstructorDescriptor constructorDescriptor,
+        AnonymousPropertyDescriptor propertyDescriptor,
+        AnonymousFieldDescriptor fieldDescriptor,
+        AnonymousEventDescriptor eventDescriptor)
+    {
+        ArgumentExceptionAdvanced.ThrowIfEnumIsNotDefined<SymbolKind>(symbolKind, nameof(symbolKind));
+        ArgumentExceptionAdvanced.ThrowIfEnumEqualsAny(symbolKind, [SymbolKind.Undefined], nameof(symbolKind));
+        ArgumentNullExceptionAdvanced.ThrowIfNullOrWhiteSpace(name, nameof(name));
+
+        SymbolKind = symbolKind;
+        _parameterDescriptor = parameterDescriptor;
+        _constructorDescriptor = constructorDescriptor;
+        _methodDescriptor = methodDescriptor;
+        _propertyDescriptor = propertyDescriptor;
+        _fieldDescriptor = fieldDescriptor;
+        _eventDescriptor = eventDescriptor;
+        SymbolName = name;
+
+        _hashCode = ComputeHashCode();
+    }
+
+    /// <summary>
+    /// Creates a cache key for an event symbol.
+    /// </summary>
+    /// <param name="eventDescriptor">The event descriptor.</param>
+    /// <returns>The unique cache key for the event symbol.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="eventDescriptor"/> is <see langword="null"/>.</exception>
+    public static AnonymousSymbolDescriptorContainer CreateForEvent(AnonymousEventDescriptor eventDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(eventDescriptor);
+
+        return new AnonymousSymbolDescriptorContainer(
+            eventDescriptor.EventName,
+            SymbolKind.MemberEvent,
+            default,
+            default,
+            default,
+            default,
+            default,
+            eventDescriptor);
+    }
+
+    public static AnonymousSymbolDescriptorContainer CreateForProperty(AnonymousPropertyDescriptor propertyDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(propertyDescriptor);
+
+        // Anonymous keys will never be used to cache items.
+        // Instead they will always be converted to well-known keys by attempting to identify the runtime metadata object
+        // based on the provided information. Therefore we can use an empty AssemblyId here.
+        return new AnonymousSymbolDescriptorContainer(
+            propertyDescriptor.PropertyName,
+            SymbolKind.MemberProperty,
+            default,
+            default,
+            default,
+            propertyDescriptor,
+            default,
+            default);
+    }
+
+    /// <summary>
+    /// Creates a cache key for an anonymous method symbol.
+    /// </summary>
+    /// <param name="methodDescriptor">The <see cref="Net.AnonymousMethodDescriptor"/> that describes an anonymous method (which is where the <see cref="MethodInfo"/> is not available and instead only the signature information is available).</param>
+    /// <remarks>This method creates a unique cache key for well-known or anonymous method symbols, including regular methods, property accessors, and event accessors.
+    /// <para/>For maximum performance and zero ambiguity, always prefer to create method cache keys using well-known <see cref="MethodInfo"/> instances via the <see cref="Net.WellKnownMethodDescriptor"/>.</remarks>
+    /// <returns>The unique cache key for the well-known method symbol.</returns>
+    public static AnonymousSymbolDescriptorContainer CreateForMethod(AnonymousMethodDescriptor methodDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(methodDescriptor);
+
+        return new AnonymousSymbolDescriptorContainer(
+            methodDescriptor.MethodName,
+            SymbolKind.MemberMethod,
+            default,
+            methodDescriptor,
+            default,
+            default,
+            default,
+            default);
+    }
+
+    /// <summary>
+    /// Creates a new cache key for an anonymous field using the specified <see cref="AnonymousFieldDescriptor"/>.
+    /// </summary>
+    /// <param name="fieldDescriptor">The <see cref="Net.AnonymousFieldDescriptor"/> that describes an anonymous field (which is where the <see cref="FieldInfo"/> is not available and instead only the signature information is available).</param>
+    /// <remarks>This method is used to create a unique cache key for field symbols of which the caller does not have a direct representation <see cref="FieldInfo"/> and instead only signature information is available.</remarks>
+    /// <returns>A new instance of <see cref="SymbolReflectionInfoCacheKeyInternal"/> representing the specified anonymous field.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="fieldDescriptor"/> is <see langword="default"/>.</exception>
+    public static AnonymousSymbolDescriptorContainer CreateForField(AnonymousFieldDescriptor fieldDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(fieldDescriptor);
+
+        return new AnonymousSymbolDescriptorContainer(
+            fieldDescriptor.FieldName,
+            SymbolKind.MemberField,
+            default,
+            default,
+            default,
+            default,
+            fieldDescriptor,
+            default);
+    }
+
+    /// <summary>
+    /// Creates a new cache key for an anonymous constructor using the specified <see cref="AnonymousMethodDescriptor"/>.
+    /// </summary>
+    /// <remarks>This method is used to create a unique cache key for constructor symbols of which the caller does not have a direct representation <see cref="ConstructorInfo"/> and instead only signature information is available.
+    ///<para/>For maximum performance and zero ambiguity, always prefer to create constructor cache keys using well-known <see cref="ConstructorInfo"/> instances via the <see cref="Net.WellKnownMethodDescriptor"/>.</remarks>
+    /// <param name="constructorDescriptor"></param>
+    /// <returns>A new instance of <see cref="SymbolReflectionInfoCacheKeyInternal"/> representing the specified anonymous constructor.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="constructorDescriptor"/> is <see langword="default"/>.</exception>
+    public static AnonymousSymbolDescriptorContainer CreateForConstructor(AnonymousConstructorDescriptor constructorDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(constructorDescriptor);
+
+        return new AnonymousSymbolDescriptorContainer(
+            string.Empty,
+            SymbolKind.MemberConstructor,
+            default,
+            default,
+            constructorDescriptor,
+            default,
+            default,
+            default);
+    }
+
+    public static AnonymousSymbolDescriptorContainer CreateForParameter(AnonymousParameterDescriptor parameterDescriptor)
+    {
+        ArgumentNullExceptionAdvanced.ThrowIfDefault(parameterDescriptor);
+
+        return new AnonymousSymbolDescriptorContainer(
+            parameterDescriptor.ParameterName,
+            SymbolKind.Parameter,
+            parameterDescriptor,
+            default,
+            default,
+            default,
+            default,
+            default);
+    }
+
+    public override int GetHashCode()
+        => _hashCode;
+
+    private int ComputeHashCode()
+    {
+        unchecked
+        {
+            if (_hashCode != 0)
+            {
+                return _hashCode;
+            }
+
+            var hashCode = new HashCode();
+            hashCode.Add(SymbolName);
+            hashCode.Add(SymbolKind);
+            hashCode.Add(_parameterDescriptor);
+            hashCode.Add(_methodDescriptor);
+            hashCode.Add(_constructorDescriptor);
+            hashCode.Add(_propertyDescriptor);
+            hashCode.Add(_fieldDescriptor);
+            hashCode.Add(_eventDescriptor);
+            hashCode.Add(_isExplicitInterfaceImplementation);
+
+            return hashCode.ToHashCode();
+        }
+    }
+
+    public override bool Equals(object obj) => obj is AnonymousSymbolDescriptorContainer other && Equals(other);
+
+    public bool Equals(AnonymousSymbolDescriptorContainer other) => SymbolName == other.SymbolName
+        && SymbolKind == other.SymbolKind
+        && _parameterDescriptor == other._parameterDescriptor
+        && _methodDescriptor == other._methodDescriptor
+        && _constructorDescriptor == other._constructorDescriptor
+        && _propertyDescriptor == other._propertyDescriptor
+        && _fieldDescriptor == other._fieldDescriptor
+        && _eventDescriptor == other._eventDescriptor
+        && _isExplicitInterfaceImplementation == other._isExplicitInterfaceImplementation;
+
+    public static bool operator ==(AnonymousSymbolDescriptorContainer left, AnonymousSymbolDescriptorContainer right) => left.Equals(right);
+    public static bool operator !=(AnonymousSymbolDescriptorContainer left, AnonymousSymbolDescriptorContainer right) => !(left == right);
+
+    [DoesNotReturn]
+    private TResult ThrowInvalidPropertyContextException<TResult>(ReadOnlySpan<SymbolKind> allowedSymbolKinds, [CallerMemberName] string? propertyName = null)
+    {
+        ArgumentExceptionAdvanced.ThrowIfTrue(allowedSymbolKinds.IsEmpty, nameof(allowedSymbolKinds), "At least one allowed symbol kind must be provided.");
+
+        string allowedKinds = allowedSymbolKinds.JoinToString(kind => $"{typeof(SymbolKind).FullName}.{kind}", ", ");
+        return allowedSymbolKinds.Length > 1
+            ? throw new InvalidOperationException($"The property '{propertyName}' is only available for symbols, where the property '{nameof(SymbolKind)}' returns any of the following values: {allowedKinds}.")
+            : throw new InvalidOperationException($"The property '{propertyName}' is only available for symbols, where the property '{nameof(SymbolKind)}' returns the value '{allowedKinds[0]}'.");
+    }
+}

src/BionicCode.Utilities.Reflection/ConstructorData.cs

@@ -30,6 +30,7 @@ internal sealed class ConstructorData : ParameterizedMemberData
     private Func<object?[], object>? _invocator;
     private string? _assemblyName;
     private SymbolComponentInfo? _symbolComponentInfo;
+    private IConstructorDataView? _constructorDataView;
 
     internal ConstructorData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheKey)
         : base(symbolInfoDataCacheKey)
@@ -43,6 +44,9 @@ internal ConstructorData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCach
         IsExplicitInterfaceImplementation = false;
     }
 
+    internal IConstructorDataView View => _constructorDataView
+        ??= new ConstructorDataView(SymbolReflectionInfoCacheKey.CreateForConstructor(this));
+
     internal ConstructorInfo ConstructorInfo { get; }
 
     internal override MethodBase GetMethodBase() => ConstructorInfo;

src/BionicCode.Utilities.Reflection/EventData.cs

@@ -38,6 +38,7 @@ internal sealed class EventData : MemberData
     private RuntimeTypeHandle? _declaringTypeHandle;
     private RuntimeTypeHandle? _implementingTypeHandle;
     private bool? _isExplicitInterfaceImplementation;
+    private IEventDataView? _eventDataView;
 
     internal EventData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheKey)
         : base(symbolInfoDataCacheKey.EventDescriptor.EventName, SymbolKind.MemberEvent, symbolInfoDataCacheKey)
@@ -48,6 +49,9 @@ internal EventData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheKey)
         EventInfo = symbolInfoDataCacheKey.EventDescriptor.EventInfo;
     }
 
+    internal IEventDataView View => _eventDataView
+        ??= new EventDataView(SymbolReflectionInfoCacheKey.CreateForEvent(this));
+
     protected override MemberInfo GetMemberInfo()
       => EventInfo;
 

src/BionicCode.Utilities.Reflection/EventDataView.cs

@@ -3,9 +3,10 @@
 using System;
 using System.Reflection;
 
-public class EventDataView : IEventDataView
+public class EventDataView : SymbolReflectionInfoCache.SymbolDataViewBase, IEventDataView
 {
-    internal EventDataView(SymbolReflectionInfoCacheKey cacheKey) => CacheKey = cacheKey;
+    internal EventDataView(SymbolReflectionInfoCacheKey cacheKey) : base(cacheKey)
+    { }
 
     public AccessModifier AccessModifier => SymbolReflectionInfoCache.GetOrCreateEventDataCacheEntry(CacheKey).AccessModifier;
     public IMethodDataView AddMethodDataView { get; }

src/BionicCode.Utilities.Reflection/FieldData.cs

@@ -36,6 +36,7 @@ internal sealed class FieldData : MemberData, IFieldDataInvoker
     private readonly WellKnownFieldDescriptor _descriptor;
     private string? _assemblyName;
     private SymbolComponentInfo? _symbolComponentInfo;
+    private IFieldDataView? _fieldDataView;
 
     internal FieldData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheKey)
         : base(symbolInfoDataCacheKey.FieldDescriptor.FieldName, SymbolKind.MemberField, symbolInfoDataCacheKey)
@@ -50,6 +51,8 @@ internal FieldData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheKey)
         IsExplicitInterfaceImplementation = false; // Fields cannot be explicit interface implementations
         ImplementingTypeHandle = DeclaringTypeHandle;
     }
+    internal IFieldDataView View => _fieldDataView
+        ??= new FieldDataView(SymbolReflectionInfoCacheKey.CreateForField(this));
 
     internal FieldInfo FieldInfo { get; }
 

src/BionicCode.Utilities.Reflection/IMethodDataView.cs

@@ -39,6 +39,7 @@ public interface IMethodDataView : IParameterizedMemberDataView, IMemberDataView
     bool IsReturnValueReadOnly { get; }
     bool IsVoidMethod { get; }
     ITypeDataView ReturnTypeData { get; }
+    IParameterDataView ReturnParameterData { get; }
     bool EqualsBySignature(IMethodDataView other);
     object? Invoke(object? target, params object?[]? args);
     object? Invoke(object? target, ReadOnlySpan<object?> args);

src/BionicCode.Utilities.Reflection/MethodData.cs

@@ -39,6 +39,7 @@ internal sealed partial class MethodData : ParameterizedMemberData, IMethodDataI
     private string? _shortCompactSignature;
     private string? _fullyQualifiedSignature;
     private TypeData? _returnTypeData;
+    private ParameterData? _returnParameterData;
     private bool? _isGenericMethod;
     private bool? _isGenericTypeMethod;
     private MethodData? _genericMethodDefinitionData;
@@ -74,6 +75,7 @@ internal sealed partial class MethodData : ParameterizedMemberData, IMethodDataI
     private RuntimeTypeHandle? _declaringTypeHandle;
     private RuntimeTypeHandle? _implementingTypeHandle;
     private bool? _isExplicitInterfaceImplementation;
+    private IMethodDataView? _methodDataView;
 
     internal MethodData(SymbolReflectionInfoCacheKeyInternal symbolReflectionInfoCacheKey)
         : base(symbolReflectionInfoCacheKey)
@@ -88,6 +90,9 @@ internal MethodData(SymbolReflectionInfoCacheKeyInternal symbolReflectionInfoCac
         _methodSignatureEqualityComparer = new MethodSignatureEqualityComparer();
     }
 
+    internal IMethodDataView View => _methodDataView
+        ??= new MethodDataView(SymbolReflectionInfoCacheKey.CreateForMethod(this));
+
     internal MethodInfo MethodInfo { get; }
 
     protected override MemberInfo GetMemberInfo() => MethodInfo;
@@ -1198,6 +1203,8 @@ internal bool IsAwaitableGenericTask
 
     internal TypeData ReturnTypeData => _returnTypeData ??= SymbolReflectionInfoCache.GetOrCreateEntryInternal(MethodInfo.ReturnType);
 
+    internal ParameterData ReturnParameterData => _returnParameterData ??= SymbolReflectionInfoCache.GetOrCreateEntryInternal(MethodInfo.ReturnParameter);
+
     internal bool IsGenericMethod => _isGenericMethod ??= MethodInfo.IsGenericMethod;
 
     internal bool IsGenericMethodDefinition => _isGenericTypeMethod ??= MethodInfo.IsGenericMethodDefinition;