CacheBoundary support for Blazor

src/Components/Authorization/src/AuthorizeViewCore.cs

@@ -10,6 +10,7 @@ namespace Microsoft.AspNetCore.Components.Authorization;
 /// <summary>
 /// A base class for components that display differing content depending on the user's authorization status.
 /// </summary>
+[CacheBoundaryPolicy(Disallow = true, VaryBy = CacheBoundaryVaryBy.User)]
 public abstract class AuthorizeViewCore : ComponentBase
 {
     private AuthenticationState? currentAuthenticationState;

src/Components/Components/src/CacheBoundaryPolicyAttribute.cs

@@ -0,0 +1,52 @@
+// 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 how a component interacts with an enclosing CacheBoundary.
+/// When present, the component is treated as a "hole" in the cached output: the
+/// component is instantiated and executes its own lifecycle on every request rather
+/// than being served from the cached HTML. Its parameters are captured at the time the
+/// cache entry is produced and are replayed unchanged on subsequent requests, so values
+/// closed over by the surrounding render remain those of the original render.
+/// Optionally, set <see cref="VaryBy"/> to lift the exclusion when the cache boundary
+/// varies by the specified dimensions, in which case the component is included in
+/// the cached output like any other.
+/// <para>
+/// <see cref="RenderFragment"/> parameters are not supported on hole components, because the
+/// hole re-renders on every request while its parameters are captured once and replayed; a
+/// captured <see cref="RenderFragment"/> would be frozen to the content of the first render.
+/// Encountering a hole with a <see cref="RenderFragment"/> parameter throws an
+/// <see cref="InvalidOperationException"/>. To fix this, remove the <see cref="RenderFragment"/>
+/// parameter or move the component outside the CacheBoundary.
+/// </para>
+/// </summary>
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
+public sealed class CacheBoundaryPolicyAttribute : Attribute
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether encountering this component inside
+    /// a cache boundary is disallowed and should throw an <see cref="InvalidOperationException"/>.
+    /// Use this for components whose parameters (delegates, expressions, or complex
+    /// objects) would not behave correctly if captured once and replayed on later
+    /// requests; for example because they close over per-request state or
+    /// because the rendered output depends on values that change between requests.
+    /// The exception is suppressed when the enclosing CacheBoundary varies by all
+    /// of the dimensions specified by <see cref="VaryBy"/>.
+    /// Defaults to <see langword="false"/>.
+    /// </summary>
+    public bool Disallow { get; set; }
+
+    /// <summary>
+    /// Gets or sets the vary-by dimensions that, when all active on the enclosing
+    /// CacheBoundary, lift the exclusion. When lifted, the component participates
+    /// in the cached output like any other component (its captured parameters and
+    /// child content are stored in the cache entry and replayed on cache hits),
+    /// and the cache key already distinguishes the values of those dimensions so
+    /// the replay is correct. When not lifted, the component is treated as a hole
+    /// (or throws, when <see cref="Disallow"/> is <see langword="true"/>).
+    /// Defaults to <see cref="CacheBoundaryVaryBy.None"/>.
+    /// </summary>
+    public CacheBoundaryVaryBy VaryBy { get; set; }
+}

src/Components/Components/src/CacheBoundaryVaryBy.cs

@@ -0,0 +1,48 @@
+// 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>
+/// Describes which vary-by dimensions are active on an enclosing CacheBoundary.
+/// Used as flags in <see cref="CacheBoundaryPolicyAttribute"/> to express conditional
+/// cache exclusion, and internally to communicate the active dimensions to the renderer.
+/// </summary>
+[Flags]
+public enum CacheBoundaryVaryBy
+{
+    /// <summary>
+    /// No vary-by dimensions.
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    /// Vary by query string parameters.
+    /// </summary>
+    Query = 1 << 0,
+
+    /// <summary>
+    /// Vary by route parameters.
+    /// </summary>
+    Route = 1 << 1,
+
+    /// <summary>
+    /// Vary by HTTP header values.
+    /// </summary>
+    Header = 1 << 2,
+
+    /// <summary>
+    /// Vary by cookie values.
+    /// </summary>
+    Cookie = 1 << 3,
+
+    /// <summary>
+    /// Vary by the authenticated user.
+    /// </summary>
+    User = 1 << 4,
+
+    /// <summary>
+    /// Vary by culture.
+    /// </summary>
+    Culture = 1 << 5,
+}

src/Components/Components/src/Microsoft.AspNetCore.Components.csproj

@@ -15,6 +15,7 @@
 
   <ItemGroup>
     <Compile Include="$(ComponentsSharedSourceRoot)src\ArrayBuilder.cs" LinkBase="RenderTree" />
+    <Compile Include="$(ComponentsSharedSourceRoot)src\ComponentKeyHelper.cs" LinkBase="Shared" />
     <Compile Include="$(ComponentsSharedSourceRoot)src\JsonSerializerOptionsProvider.cs" />
     <Compile Include="$(ComponentsSharedSourceRoot)src\HotReloadManager.cs" LinkBase="HotReload" />
     <Compile Include="$(ComponentsSharedSourceRoot)src\RootTypeCache.cs" LinkBase="Shared" />

src/Components/Components/src/PersistentState/PersistentStateValueProviderKeyResolver.cs

@@ -126,17 +126,8 @@ private static string ComputeFinalKey(byte[] preKey, ComponentState componentSta
 
     private static ReadOnlySpan<char> ResolveKeySpan(object? key)
     {
-        if (key is IFormattable formattable)
-        {
-            var keyString = formattable.ToString("", CultureInfo.InvariantCulture);
-            return keyString.AsSpan();
-        }
-        else if (key is IConvertible convertible)
-        {
-            var keyString = convertible.ToString(CultureInfo.InvariantCulture);
-            return keyString.AsSpan();
-        }
-        return default;
+        var formatted = ComponentKeyHelper.FormatSerializableKey(key);
+        return formatted.AsSpan();
     }
 
     private static void GrowBuffer(ref byte[]? pool, ref Span<byte> keyBuffer, int? size = null)
@@ -154,7 +145,7 @@ private static void GrowBuffer(ref byte[]? pool, ref Span<byte> keyBuffer, int?
     private static object? GetSerializableKey(ComponentState componentState)
     {
         var componentKey = componentState.GetComponentKey();
-        if (componentKey != null && IsSerializableKey(componentKey))
+        if (componentKey != null && ComponentKeyHelper.IsSerializableKey(componentKey))
         {
             return componentKey;
         }
@@ -195,20 +186,4 @@ private static string GetParentComponentType(ComponentState componentState)
 
     private static byte[] KeyFactory((string parentComponentType, string componentType, string propertyName) parts) =>
         SHA256.HashData(Encoding.UTF8.GetBytes(string.Join(".", parts.parentComponentType, parts.componentType, parts.propertyName)));
-
-    private static bool IsSerializableKey(object key)
-    {
-        if (key == null)
-        {
-            return false;
-        }
-        var keyType = key.GetType();
-        var result = Type.GetTypeCode(keyType) != TypeCode.Object
-            || keyType == typeof(Guid)
-            || keyType == typeof(DateTimeOffset)
-            || keyType == typeof(DateOnly)
-            || keyType == typeof(TimeOnly);
-
-        return result;
-    }
 }

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

@@ -1,4 +1,18 @@
 #nullable enable
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute.CacheBoundaryPolicyAttribute() -> void
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute.Disallow.get -> bool
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute.Disallow.set -> void
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute.VaryBy.get -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryPolicyAttribute.VaryBy.set -> void
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.Cookie = 8 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.Culture = 32 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.Header = 4 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.None = 0 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.Query = 1 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.Route = 2 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
+Microsoft.AspNetCore.Components.CacheBoundaryVaryBy.User = 16 -> Microsoft.AspNetCore.Components.CacheBoundaryVaryBy
 abstract Microsoft.AspNetCore.Components.CascadingParameterSubscription.Dispose() -> void
 abstract Microsoft.AspNetCore.Components.CascadingParameterSubscription.GetCurrentValue() -> object?
 Microsoft.AspNetCore.Components.CascadingParameterSubscription

src/Components/Endpoints/src/CacheBoundary/CacheBoundary.cs

@@ -0,0 +1,151 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.Components.Endpoints;
+using Microsoft.AspNetCore.Components.Rendering;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Caching.Memory;
+
+namespace Microsoft.AspNetCore.Components;
+
+/// <summary>
+/// A component that caches the rendered HTML of its child content during
+/// server-side rendering (SSR). On cache hit, child components are not
+/// instantiated or rendered.
+/// </summary>
+public sealed class CacheBoundary : IComponent, IDisposable
+{
+    private RenderHandle _renderHandle;
+
+    /// <summary>
+    /// Gets or sets the content to be cached.
+    /// </summary>
+    [Parameter]
+    public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>
+    /// Gets or sets an explicit cache key for disambiguation when multiple
+    /// <see cref="CacheBoundary"/> instances share the same component ancestor.
+    /// </summary>
+    [Parameter]
+    public string? CacheKey { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether caching is enabled. Defaults to <c>true</c>.
+    /// </summary>
+    [Parameter]
+    public bool Enabled { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets how long after creation the cache entry should be evicted.
+    /// </summary>
+    [Parameter]
+    public TimeSpan? ExpiresAfter { get; set; }
+
+    /// <summary>
+    /// Gets or sets the absolute <see cref="DateTimeOffset"/> when the cache entry should be evicted.
+    /// </summary>
+    [Parameter]
+    public DateTimeOffset? ExpiresOn { get; set; }
+
+    /// <summary>
+    /// Gets or sets how long after last access the cache entry should be evicted.
+    /// Not supported when the cache boundary store uses <c>HybridCache</c>.
+    /// </summary>
+    [Parameter]
+    public TimeSpan? ExpiresSliding { get; set; }
+
+    /// <summary>
+    /// Gets or sets the <see cref="CacheItemPriority"/> policy for the cache entry.
+    /// Not supported when the cache boundary store uses <c>HybridCache</c>.
+    /// </summary>
+    [Parameter]
+    public CacheItemPriority? Priority { get; set; }
+
+    /// <summary>
+    /// Gets or sets a comma-separated list of query string parameter names to vary the cache by.
+    /// Use <c>"*"</c> to vary by all query string parameters.
+    /// </summary>
+    [Parameter]
+    public string? VaryByQuery { get; set; }
+
+    /// <summary>
+    /// Gets or sets a comma-separated list of route parameter names to vary the cache by.
+    /// </summary>
+    [Parameter]
+    public string? VaryByRoute { get; set; }
+
+    /// <summary>
+    /// Gets or sets a comma-separated list of HTTP header names to vary the cache by.
+    /// </summary>
+    [Parameter]
+    public string? VaryByHeader { get; set; }
+
+    /// <summary>
+    /// Gets or sets a comma-separated list of cookie names to vary the cache by.
+    /// </summary>
+    [Parameter]
+    public string? VaryByCookie { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether to vary the cache by the authenticated user identity.
+    /// </summary>
+    [Parameter]
+    public bool? VaryByUser { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether to vary the cache by the current culture.
+    /// </summary>
+    [Parameter]
+    public bool? VaryByCulture { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom string value to vary the cache by.
+    /// </summary>
+    [Parameter]
+    public string? VaryBy { get; set; }
+
+    [Inject] internal CacheBoundaryService? CacheService { get; set; }
+    [CascadingParameter] internal HttpContext? HttpContext { get; set; }
+    internal Func<string>? TreePositionKeyFactory { get; set; }
+    internal string? TreePositionKey => TreePositionKeyFactory?.Invoke();
+
+    internal bool IsInStreamingContext { get; set; }
+
+    // The per-render coordination state produced by CacheBoundaryService. Null when caching is inactive
+    // for this render; the renderer reads it to drive capture.
+    internal CacheBoundaryRenderState? RenderState { get; private set; }
+
+    /// <inheritdoc/>
+    void IComponent.Attach(RenderHandle renderHandle)
+    {
+        _renderHandle = renderHandle;
+    }
+
+    /// <inheritdoc/>
+    async Task IComponent.SetParametersAsync(ParameterView parameters)
+    {
+        parameters.SetParameterProperties(this);
+
+        RenderState = HttpContext is { } httpContext && CacheService is { } cacheService
+            ? await cacheService.PrepareAsync(this, httpContext)
+            : null;
+
+        _renderHandle.Render(BuildRenderTree);
+    }
+
+    private void BuildRenderTree(RenderTreeBuilder builder)
+    {
+        var content = RenderState?.Content ?? ChildContent;
+        content?.Invoke(builder);
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        if (RenderState is { } state)
+        {
+            CacheBoundaryService.OnBoundaryDisposed(state);
+        }
+    }
+}