Allow declaring render modes, and emit the corresponding markers into HTML

Author: SteveSandersonMS

AspNetCore.sln

@@ -10754,7 +10754,7 @@ Global
 		{2C022280-340C-43DC-B63D-5A644F0ECBF2} = {5BC5A805-DCA0-41DF-91B8-520B5DAD57DA}
 		{B6081DA9-738E-4088-92DD-7FFA200523C9} = {2C022280-340C-43DC-B63D-5A644F0ECBF2}
 		{BE70E100-E6C4-4686-8592-73E2A04E877F} = {B6081DA9-738E-4088-92DD-7FFA200523C9}
-		{60D51C98-2CC0-40DF-B338-44154EFEE2FF} = {017429CC-C5FB-48B4-9C46-034E29EE2F06}
+		{60D51C98-2CC0-40DF-B338-44154EFEE2FF} = {380430A1-C02F-4943-8A52-FDFA9F7735F0}
 		{6DE916F5-E78F-446C-89CB-9240AED2A2E2} = {60D51C98-2CC0-40DF-B338-44154EFEE2FF}
 		{7546E2DD-2CF4-4240-8045-2533DF539458} = {6DE916F5-E78F-446C-89CB-9240AED2A2E2}
 		{B55A5DE1-5AF3-4B18-AF04-C1735B071DA6} = {017429CC-C5FB-48B4-9C46-034E29EE2F06}

src/Components/Authorization/test/AuthorizeRouteViewTest.cs

@@ -35,8 +35,8 @@ public AuthorizeRouteViewTest()
 
         var services = serviceCollection.BuildServiceProvider();
         _renderer = new TestRenderer(services);
-        var componentFactory = new ComponentFactory(new DefaultComponentActivator());
-        _authorizeRouteViewComponent = (AuthorizeRouteView)componentFactory.InstantiateComponent(services, typeof(AuthorizeRouteView));
+        var componentFactory = new ComponentFactory(new DefaultComponentActivator(), new RenderModeResolver());
+        _authorizeRouteViewComponent = (AuthorizeRouteView)componentFactory.InstantiateComponent(services, typeof(AuthorizeRouteView), null);
         _authorizeRouteViewComponentId = _renderer.AssignRootComponentId(_authorizeRouteViewComponent);
     }
 

src/Components/Components/src/ComponentFactory.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
 using Microsoft.AspNetCore.Components.Reflection;
+using Microsoft.AspNetCore.Components.Rendering;
 using static Microsoft.AspNetCore.Internal.LinkerFlags;
 
 namespace Microsoft.AspNetCore.Components;
@@ -14,46 +15,70 @@ internal sealed class ComponentFactory
     private const BindingFlags _injectablePropertyBindingFlags
         = BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic;
 
-    private static readonly ConcurrentDictionary<Type, Action<IServiceProvider, IComponent>> _cachedInitializers = new();
+    private static readonly ConcurrentDictionary<Type, ComponentTypeInfoCacheEntry> _cachedComponentTypeInfo = new();
 
     private readonly IComponentActivator _componentActivator;
+    private readonly RenderModeResolver _renderModeResolver;
 
-    public ComponentFactory(IComponentActivator componentActivator)
+    public ComponentFactory(IComponentActivator componentActivator, RenderModeResolver renderModeResolver)
     {
         _componentActivator = componentActivator ?? throw new ArgumentNullException(nameof(componentActivator));
+        _renderModeResolver = renderModeResolver ?? throw new ArgumentNullException(nameof(renderModeResolver));
     }
 
-    public static void ClearCache() => _cachedInitializers.Clear();
+    public static void ClearCache() => _cachedComponentTypeInfo.Clear();
 
-    public IComponent InstantiateComponent(IServiceProvider serviceProvider, [DynamicallyAccessedMembers(Component)] Type componentType)
+    private static ComponentTypeInfoCacheEntry GetComponentTypeInfo([DynamicallyAccessedMembers(Component)] Type componentType)
     {
-        var component = _componentActivator.CreateInstance(componentType);
+        // Unfortunately we can't use 'GetOrAdd' here because the DynamicallyAccessedMembers annotation doesn't flow through to the
+        // callback, so it becomes an IL2111 warning. The following is equivalent and thread-safe because it's a ConcurrentDictionary
+        // and it doesn't matter if we build a cache entry more than once.
+        if (!_cachedComponentTypeInfo.TryGetValue(componentType, out var cacheEntry))
+        {
+            cacheEntry = new ComponentTypeInfoCacheEntry(GetRenderModeFromComponentType(componentType), CreatePropertyInjector(componentType));
+            _cachedComponentTypeInfo.TryAdd(componentType, cacheEntry);
+        }
+
+        return cacheEntry;
+    }
+
+    public IComponent InstantiateComponent(IServiceProvider serviceProvider, [DynamicallyAccessedMembers(Component)] Type componentType, IComponentRenderMode? callerSpecifiedRenderMode)
+    {
+        var componentTypeInfo = GetComponentTypeInfo(componentType);
+        var component = callerSpecifiedRenderMode is null && componentTypeInfo.RenderMode is null
+            ? _componentActivator.CreateInstance(componentType)
+            : _renderModeResolver.ResolveComponent(componentType, _componentActivator, componentTypeInfo.RenderMode, callerSpecifiedRenderMode);
+
         if (component is null)
         {
             // The default activator will never do this, but an externally-supplied one might
             throw new InvalidOperationException($"The component activator returned a null value for a component of type {componentType.FullName}.");
         }
 
-        PerformPropertyInjection(serviceProvider, component);
+        if (component.GetType() == componentType)
+        {
+            // Fast, common case: use the cached data we already looked up
+            componentTypeInfo.PerformPropertyInjection(serviceProvider, component);
+        }
+        else
+        {
+            // Uncommon case where the activator/resolver returned a different type. Needs an extra cache lookup.
+            PerformPropertyInjection(serviceProvider, component);
+        }
+
         return component;
     }
 
     private static void PerformPropertyInjection(IServiceProvider serviceProvider, IComponent instance)
     {
-        // This is thread-safe because _cachedInitializers is a ConcurrentDictionary.
-        // We might generate the initializer more than once for a given type, but would
-        // still produce the correct result.
-        var instanceType = instance.GetType();
-        if (!_cachedInitializers.TryGetValue(instanceType, out var initializer))
-        {
-            initializer = CreateInitializer(instanceType);
-            _cachedInitializers.TryAdd(instanceType, initializer);
-        }
-
-        initializer(serviceProvider, instance);
+        var componentTypeInfo = GetComponentTypeInfo(instance.GetType());
+        componentTypeInfo.PerformPropertyInjection(serviceProvider, instance);
     }
 
-    private static Action<IServiceProvider, IComponent> CreateInitializer([DynamicallyAccessedMembers(Component)] Type type)
+    private static IComponentRenderMode? GetRenderModeFromComponentType(Type componentType)
+        => componentType.GetCustomAttribute<RenderModeAttribute>()?.Mode;
+
+    private static Action<IServiceProvider, IComponent> CreatePropertyInjector([DynamicallyAccessedMembers(Component)] Type type)
     {
         // Do all the reflection up front
         List<(string name, Type propertyType, PropertySetter setter)>? injectables = null;
@@ -93,4 +118,9 @@ void Initialize(IServiceProvider serviceProvider, IComponent component)
             }
         }
     }
+
+    // Tracks information about a specific component type that ComponentFactory uses
+    private record class ComponentTypeInfoCacheEntry(
+        IComponentRenderMode? RenderMode,
+        Action<IServiceProvider, IComponent> PerformPropertyInjection);
 }

src/Components/Components/src/IComponentRenderMode.cs

@@ -0,0 +1,11 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Represents a render mode for a component.
+/// </summary>
+public interface IComponentRenderMode
+{
+}

src/Components/Components/src/ParameterView.cs

@@ -103,9 +103,9 @@ public TValue GetValueOrDefault<TValue>(string parameterName, TValue defaultValu
     /// Returns a dictionary populated with the contents of the <see cref="ParameterView"/>.
     /// </summary>
     /// <returns>A dictionary populated with the contents of the <see cref="ParameterView"/>.</returns>
-    public IReadOnlyDictionary<string, object> ToDictionary()
+    public IReadOnlyDictionary<string, object?> ToDictionary()
     {
-        var result = new Dictionary<string, object>();
+        var result = new Dictionary<string, object?>();
         foreach (var entry in this)
         {
             result[entry.Name] = entry.Value;

src/Components/Components/src/PublicAPI.Unshipped.txt

@@ -1,4 +1,5 @@
 #nullable enable
+abstract Microsoft.AspNetCore.Components.RenderModeAttribute.Mode.get -> Microsoft.AspNetCore.Components.IComponentRenderMode!
 Microsoft.AspNetCore.Components.CascadingModelBinder
 Microsoft.AspNetCore.Components.CascadingModelBinder.CascadingModelBinder() -> void
 Microsoft.AspNetCore.Components.CascadingModelBinder.ChildContent.get -> Microsoft.AspNetCore.Components.RenderFragment<Microsoft.AspNetCore.Components.ModelBindingContext!>!
@@ -8,14 +9,28 @@ Microsoft.AspNetCore.Components.CascadingModelBinder.IsFixed.set -> void
 Microsoft.AspNetCore.Components.CascadingModelBinder.Name.get -> string!
 Microsoft.AspNetCore.Components.CascadingModelBinder.Name.set -> void
 Microsoft.AspNetCore.Components.ComponentBase.DispatchExceptionAsync(System.Exception! exception) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.Components.IComponentRenderMode
 Microsoft.AspNetCore.Components.Infrastructure.ComponentStatePersistenceManager.PersistStateAsync(Microsoft.AspNetCore.Components.IPersistentComponentStateStore! store, Microsoft.AspNetCore.Components.Dispatcher! dispatcher) -> System.Threading.Tasks.Task!
 Microsoft.AspNetCore.Components.ModelBindingContext
 Microsoft.AspNetCore.Components.ModelBindingContext.BindingContextId.get -> string!
 Microsoft.AspNetCore.Components.ModelBindingContext.Name.get -> string!
+Microsoft.AspNetCore.Components.ParameterView.ToDictionary() -> System.Collections.Generic.IReadOnlyDictionary<string!, object?>!
+*REMOVED*Microsoft.AspNetCore.Components.ParameterView.ToDictionary() -> System.Collections.Generic.IReadOnlyDictionary<string!, object!>!
 Microsoft.AspNetCore.Components.RenderHandle.DispatchExceptionAsync(System.Exception! exception) -> System.Threading.Tasks.Task!
 *REMOVED*Microsoft.AspNetCore.Components.NavigationManager.ToAbsoluteUri(string! relativeUri) -> System.Uri!
 Microsoft.AspNetCore.Components.NavigationManager.ToAbsoluteUri(string? relativeUri) -> System.Uri!
+Microsoft.AspNetCore.Components.Rendering.RenderModeResolver
+Microsoft.AspNetCore.Components.Rendering.RenderModeResolver.RenderModeResolver() -> void
+Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.AddComponentParameter(int sequence, string! name, Microsoft.AspNetCore.Components.IComponentRenderMode! renderMode) -> void
+Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.AddComponentRenderMode(int sequence, Microsoft.AspNetCore.Components.IComponentRenderMode! renderMode) -> void
 Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.SetEventHandlerName(string! eventHandlerName) -> void
+Microsoft.AspNetCore.Components.RenderModeAttribute
+Microsoft.AspNetCore.Components.RenderModeAttribute.RenderModeAttribute() -> void
+Microsoft.AspNetCore.Components.RenderTree.ComponentFrameFlags
+Microsoft.AspNetCore.Components.RenderTree.ComponentFrameFlags.HasCallerSpecifiedRenderMode = 1 -> Microsoft.AspNetCore.Components.RenderTree.ComponentFrameFlags
+Microsoft.AspNetCore.Components.RenderTree.Renderer.InstantiateComponent(System.Type! componentType, Microsoft.AspNetCore.Components.IComponentRenderMode? renderMode) -> Microsoft.AspNetCore.Components.IComponent!
+Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.ComponentFrameFlags.get -> Microsoft.AspNetCore.Components.RenderTree.ComponentFrameFlags
+Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrameType.ComponentRenderMode = 9 -> Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrameType
 Microsoft.AspNetCore.Components.Routing.IScrollToLocationHash
 Microsoft.AspNetCore.Components.Routing.IScrollToLocationHash.RefreshScrollPositionForHash(string! locationAbsolute) -> System.Threading.Tasks.Task!
 Microsoft.AspNetCore.Components.Rendering.ComponentState
@@ -49,8 +64,11 @@ override Microsoft.AspNetCore.Components.EventCallback.GetHashCode() -> int
 override Microsoft.AspNetCore.Components.EventCallback.Equals(object? obj) -> bool
 override Microsoft.AspNetCore.Components.EventCallback<TValue>.GetHashCode() -> int
 override Microsoft.AspNetCore.Components.EventCallback<TValue>.Equals(object? obj) -> bool
+virtual Microsoft.AspNetCore.Components.Rendering.RenderModeResolver.ResolveComponent(System.Type! componentType, Microsoft.AspNetCore.Components.IComponentActivator! componentActivator, Microsoft.AspNetCore.Components.IComponentRenderMode? componentTypeRenderMode, Microsoft.AspNetCore.Components.IComponentRenderMode? callSiteRenderMode) -> Microsoft.AspNetCore.Components.IComponent!
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.AddPendingTask(Microsoft.AspNetCore.Components.Rendering.ComponentState? componentState, System.Threading.Tasks.Task! task) -> void
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.CreateComponentState(int componentId, Microsoft.AspNetCore.Components.IComponent! component, Microsoft.AspNetCore.Components.Rendering.ComponentState? parentComponentState) -> Microsoft.AspNetCore.Components.Rendering.ComponentState!
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.DispatchEventAsync(ulong eventHandlerId, Microsoft.AspNetCore.Components.RenderTree.EventFieldInfo? fieldInfo, System.EventArgs! eventArgs, bool quiesce) -> System.Threading.Tasks.Task!
+virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.RenderModeResolver.get -> Microsoft.AspNetCore.Components.Rendering.RenderModeResolver!
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.ShouldTrackNamedEventHandlers() -> bool
 virtual Microsoft.AspNetCore.Components.RenderTree.Renderer.TrackNamedEventId(ulong eventHandlerId, int componentId, string! eventHandlerName) -> void
+~Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.ComponentRenderMode.get -> Microsoft.AspNetCore.Components.IComponentRenderMode

src/Components/Components/src/RenderModeAttribute.cs

@@ -0,0 +1,20 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// Specifies a fixed rendering mode for a component type.
+///
+/// Where possible, components should not specify any render mode this way, and should
+/// be implemented to work across all render modes. Component authors should only specify
+/// a fixed rendering mode when the component is incapable of running in other modes.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class)]
+public abstract class RenderModeAttribute : Attribute
+{
+    /// <summary>
+    /// Gets the fixed rendering mode for a component type.
+    /// </summary>
+    public abstract IComponentRenderMode Mode { get; }
+}

src/Components/Components/src/RenderTree/ComponentFrameFlags.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Components.RenderTree;
+
+/// <summary>
+/// Types in the Microsoft.AspNetCore.Components.RenderTree namespace are not recommended for use outside
+/// of the Blazor framework. These types will change in future release.
+/// </summary>
+[Flags]
+public enum ComponentFrameFlags : byte
+{
+    /// <summary>
+    /// Indicates that the caller has specified a render mode.
+    /// </summary>
+    HasCallerSpecifiedRenderMode = 1,
+}

src/Components/Components/src/RenderTree/RenderTreeDiffBuilder.cs

@@ -951,16 +951,8 @@ private static void InitializeNewSubtree(ref DiffContext diffContext, int frameI
     private static void InitializeNewComponentFrame(ref DiffContext diffContext, int frameIndex)
     {
         var frames = diffContext.NewTree;
-        ref var frame = ref frames[frameIndex];
-
-        if (frame.ComponentStateField != null)
-        {
-            throw new InvalidOperationException($"Child component already exists during {nameof(InitializeNewComponentFrame)}");
-        }
-
         var parentComponentId = diffContext.ComponentId;
-        diffContext.Renderer.InstantiateChildComponentOnFrame(ref frame, parentComponentId);
-        var childComponentState = frame.ComponentStateField;
+        var childComponentState = diffContext.Renderer.InstantiateChildComponentOnFrame(frames, frameIndex, parentComponentId);
 
         // Set initial parameters
         var initialParametersLifetime = new ParameterViewLifetime(diffContext.BatchBuilder);

src/Components/Components/src/RenderTree/RenderTreeFrame.cs

@@ -136,6 +136,7 @@ public struct RenderTreeFrame
     // RenderTreeFrameType.Component
     // --------------------------------------------------------------------------------
 
+    [FieldOffset(6)] internal ComponentFrameFlags ComponentFrameFlagsField;
     [FieldOffset(8)] internal int ComponentSubtreeLengthField;
     [FieldOffset(12)] internal int ComponentIdField;
     [FieldOffset(16)]
@@ -144,6 +145,12 @@ public struct RenderTreeFrame
     [FieldOffset(24)] internal ComponentState ComponentStateField;
     [FieldOffset(32)] internal object ComponentKeyField;
 
+    /// <summary>
+    /// If the <see cref="FrameType"/> property equals <see cref="RenderTreeFrameType.Component"/>
+    /// gets the <see cref="ComponentFrameFlags"/> for the component frame.
+    /// </summary>
+    public ComponentFrameFlags ComponentFrameFlags => ComponentFrameFlagsField;
+
     /// <summary>
     /// If the <see cref="FrameType"/> property equals <see cref="RenderTreeFrameType.Component"/>
     /// gets the number of frames in the subtree for which this frame is the root.
@@ -250,6 +257,31 @@ public struct RenderTreeFrame
     /// </summary>
     public string MarkupContent => MarkupContentField;
 
+    // --------------------------------------------------------------------------------
+    // RenderTreeFrameType.ComponentRenderMode
+    // --------------------------------------------------------------------------------
+
+    [FieldOffset(16)] internal IComponentRenderMode ComponentRenderModeField;
+
+    /// <summary>
+    /// If the <see cref="FrameType"/> property equals <see cref="RenderTreeFrameType.ComponentRenderMode"/>,
+    /// gets the content of the markup frame. Otherwise, the value is undefined.
+    /// </summary>
+    public IComponentRenderMode ComponentRenderMode
+    {
+        get
+        {
+            // Normally we don't check the frame type matches, and leave it to the caller to be responsible for only evaluating the correct properties.
+            // However the name "ComponentRenderMode" sounds so much like it would be a field on Component frames that we'll explicitly check to avoid mistakes.
+            if (FrameType != RenderTreeFrameType.ComponentRenderMode)
+            {
+                throw new InvalidOperationException($"The {nameof(ComponentRenderMode)} field only exists on frames of type {nameof(RenderTreeFrame.ComponentRenderMode)}.");
+            }
+
+            return ComponentRenderModeField;
+        }
+    }
+
     // Element constructor
     private RenderTreeFrame(int sequence, int elementSubtreeLength, string elementName, object elementKey)
         : this()