Polly.Caching: HybridCache-based caching strategy (net9.0)

Directory.Packages.props

@@ -11,6 +11,7 @@
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="6.0.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" Version="4.14.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Hybrid" Version="9.8.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="8.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="9.0.8" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="9.0.8" />

Polly.slnx

@@ -37,6 +37,7 @@
     <File Path="eng/analyzers/Test.globalconfig" />
   </Folder>
   <Folder Name="/src/">
+    <Project Path="src/Polly.Caching/Polly.Caching.csproj" />
     <Project Path="src/Polly.Core/Polly.Core.csproj" />
     <Project Path="src/Polly.Extensions/Polly.Extensions.csproj" />
     <Project Path="src/Polly.RateLimiting/Polly.RateLimiting.csproj" />
@@ -46,6 +47,7 @@
   </Folder>
   <Folder Name="/test/">
     <Project Path="test/Polly.AotTest/Polly.AotTest.csproj" />
+    <Project Path="test/Polly.Caching.Tests/Polly.Caching.Tests.csproj" />
     <Project Path="test/Polly.Core.Tests/Polly.Core.Tests.csproj" />
     <Project Path="test/Polly.Extensions.Tests/Polly.Extensions.Tests.csproj" />
     <Project Path="test/Polly.RateLimiting.Tests/Polly.RateLimiting.Tests.csproj" />

build.cake

@@ -183,6 +183,7 @@ Task("__CreateNuGetPackages")
         System.IO.Path.Combine(srcDir, "Polly.RateLimiting", "Polly.RateLimiting.csproj"),
         System.IO.Path.Combine(srcDir, "Polly.Extensions", "Polly.Extensions.csproj"),
         System.IO.Path.Combine(srcDir, "Polly.Testing", "Polly.Testing.csproj"),
+        System.IO.Path.Combine(srcDir, "Polly.Caching", "Polly.Caching.csproj"),
     ];
 
     Information("Building NuGet packages");
@@ -268,12 +269,22 @@ Task("MutationTestsLegacy")
     RunMutationTests(File("./src/Polly/Polly.csproj"), File("./test/Polly.Specs/Polly.Specs.csproj"));
 });
 
+Task("MutationTestsCaching")
+  .IsDependentOn("__Setup")
+  .Does((context) =>
+{
+  RunMutationTests(
+    File("./src/Polly.Caching/Polly.Caching.csproj"),
+    File("./test/Polly.Caching.Tests/Polly.Caching.Tests.csproj"));
+});
+
 Task("MutationTests")
     .IsDependentOn("MutationTestsCore")
     .IsDependentOn("MutationTestsRateLimiting")
     .IsDependentOn("MutationTestsExtensions")
     .IsDependentOn("MutationTestsTesting")
-    .IsDependentOn("MutationTestsLegacy");
+    .IsDependentOn("MutationTestsLegacy")
+    .IsDependentOn("MutationTestsCaching");
 
 ///////////////////////////////////////////////////////////////////////////////
 // EXECUTION

src/Polly.Caching/HybridCacheResiliencePipelineBuilderExtensions.cs

@@ -0,0 +1,41 @@
+using System.Diagnostics.CodeAnalysis;
+using Polly.Caching;
+
+namespace Polly;
+
+/// <summary>
+/// Extensions for integrating HybridCache with typed <see cref="ResiliencePipelineBuilder{TResult}"/>.
+/// </summary>
+/// <remarks>
+/// This caching strategy is designed for use with typed resilience pipelines only.
+/// HybridCache requires concrete types for proper serialization and deserialization.
+/// </remarks>
+public static class HybridCacheResiliencePipelineBuilderExtensions
+{
+    /// <summary>
+    /// Adds a HybridCache-based caching strategy to a typed resilience pipeline.
+    /// </summary>
+    /// <typeparam name="TResult">The result type of the pipeline.</typeparam>
+    /// <param name="builder">The typed pipeline builder.</param>
+    /// <param name="options">The HybridCache strategy options.</param>
+    /// <returns>The same typed builder instance.</returns>
+    /// <remarks>
+    /// This extension method only supports typed pipelines (<see cref="ResiliencePipelineBuilder{TResult}"/>).
+    /// For untyped pipelines, consider using a typed pipeline or a different caching strategy.
+    /// </remarks>
+    [UnconditionalSuppressMessage(
+        "Trimming",
+        "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access otherwise break functionality when trimming application code",
+        Justification = "Options are validated and all members preserved.")]
+    public static ResiliencePipelineBuilder<TResult> AddHybridCache<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] TResult>(
+        this ResiliencePipelineBuilder<TResult> builder,
+        HybridCacheStrategyOptions<TResult> options)
+    {
+        Guard.NotNull(builder);
+        Guard.NotNull(options);
+
+        return builder.AddStrategy(
+            _ => new HybridCacheResilienceStrategy<TResult>(options),
+            options);
+    }
+}

src/Polly.Caching/HybridCacheResilienceStrategy.cs

@@ -0,0 +1,37 @@
+using System.Threading.Tasks;
+using Microsoft.Extensions.Caching.Hybrid;
+
+namespace Polly.Caching;
+
+internal sealed class HybridCacheResilienceStrategy<TResult> : ResilienceStrategy<TResult>
+{
+    private readonly HybridCache _cache;
+    private readonly Func<ResilienceContext, string?> _keyGenerator;
+
+    public HybridCacheResilienceStrategy(HybridCacheStrategyOptions<TResult> options)
+    {
+        Guard.NotNull(options);
+        _cache = options.Cache!;
+        _keyGenerator = options.CacheKeyGenerator ?? (static ctx => ctx.OperationKey);
+    }
+
+    protected override async ValueTask<Outcome<TResult>> ExecuteCore<TState>(
+        Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> callback,
+        ResilienceContext context,
+        TState state)
+    {
+        var key = _keyGenerator(context) ?? string.Empty;
+
+        var result = await _cache.GetOrCreateAsync(
+            key,
+            async (_) =>
+            {
+                var outcome = await callback(context, state).ConfigureAwait(context.ContinueOnCapturedContext);
+                outcome.ThrowIfException();
+                return outcome.Result!;
+            },
+            cancellationToken: context.CancellationToken).ConfigureAwait(context.ContinueOnCapturedContext);
+
+        return Outcome.FromResult(result);
+    }
+}

src/Polly.Caching/HybridCacheStrategyOptions.TResult.cs

@@ -0,0 +1,42 @@
+using System.ComponentModel.DataAnnotations;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Caching.Hybrid;
+
+namespace Polly.Caching;
+
+/// <summary>
+/// Options for the HybridCache-based caching strategy for typed resilience pipelines.
+/// </summary>
+/// <typeparam name="TResult">The result type of the resilience pipeline.</typeparam>
+/// <remarks>
+/// This strategy is designed for use with typed resilience pipelines (<see cref="ResiliencePipelineBuilder{TResult}"/>).
+/// HybridCache requires concrete types for proper serialization and deserialization support.
+/// </remarks>
+[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Members preserved via builder validation.")]
+public class HybridCacheStrategyOptions<TResult> : ResilienceStrategyOptions
+{
+    /// <summary>
+    /// Gets or sets the <see cref="HybridCache"/> instance to use.
+    /// </summary>
+    [Required]
+    public HybridCache? Cache { get; set; }
+
+    /// <summary>
+    /// Gets or sets the time-to-live for cached entries.
+    /// The default is 5 minutes.
+    /// </summary>
+    [Range(typeof(TimeSpan), "00:00:00", "365.00:00:00")]
+    public TimeSpan Ttl { get; set; } = TimeSpan.FromMinutes(5);
+
+    /// <summary>
+    /// Gets or sets a value indicating whether sliding expiration should be used.
+    /// The default is <see langword="false"/>.
+    /// </summary>
+    public bool UseSlidingExpiration { get; set; }
+
+    /// <summary>
+    /// Gets or sets a delegate that generates the cache key from the resilience context.
+    /// If <see langword="null"/>, <see cref="ResilienceContext.OperationKey"/> is used.
+    /// </summary>
+    public Func<ResilienceContext, string?>? CacheKeyGenerator { get; set; }
+}

src/Polly.Caching/Polly.Caching.csproj

@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <AssemblyTitle>Polly.Caching</AssemblyTitle>
+    <RootNamespace>Polly.Caching</RootNamespace>
+    <Nullable>enable</Nullable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <ProjectType>Library</ProjectType>
+    <UsePublicApiAnalyzers>true</UsePublicApiAnalyzers>
+    <!-- TODO: Enable after first NuGet release with a published baseline -->
+    <EnablePackageValidation>false</EnablePackageValidation>
+    <LegacySupport>true</LegacySupport>
+    <MutationScore>100</MutationScore>
+  </PropertyGroup>
+  <PropertyGroup>
+    <Description>Polly.Caching provides caching strategies for Polly.Core.</Description>
+    <PackageTags>Polly Caching HybridCache Resilience Policy</PackageTags>
+  </PropertyGroup>
+  <ItemGroup>
+    <Using Include="Polly.Utils" />
+    <Compile Include="..\Polly.Core\Utils\ExceptionUtilities.cs" Link="utils\ExceptionUtilities.cs" />
+    <Compile Include="..\Polly.Core\Utils\Guard.cs" Link="Utils\Guard.cs" />
+    <InternalsVisibleToProject Include="Polly.Caching.Tests" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" VersionOverride="9.3.0" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\Polly.Core\Polly.Core.csproj" />
+  </ItemGroup>
+</Project>

src/Polly.Caching/PublicAPI.Shipped.txt

@@ -0,0 +1 @@
+#nullable enable

src/Polly.Caching/PublicAPI.Unshipped.txt

@@ -0,0 +1,13 @@
+#nullable enable
+Polly.HybridCacheResiliencePipelineBuilderExtensions
+Polly.Caching.HybridCacheStrategyOptions<TResult>
+Polly.Caching.HybridCacheStrategyOptions<TResult>.HybridCacheStrategyOptions() -> void
+Polly.Caching.HybridCacheStrategyOptions<TResult>.Cache.get -> Microsoft.Extensions.Caching.Hybrid.HybridCache?
+Polly.Caching.HybridCacheStrategyOptions<TResult>.Cache.set -> void
+Polly.Caching.HybridCacheStrategyOptions<TResult>.Ttl.get -> System.TimeSpan
+Polly.Caching.HybridCacheStrategyOptions<TResult>.Ttl.set -> void
+Polly.Caching.HybridCacheStrategyOptions<TResult>.UseSlidingExpiration.get -> bool
+Polly.Caching.HybridCacheStrategyOptions<TResult>.UseSlidingExpiration.set -> void
+Polly.Caching.HybridCacheStrategyOptions<TResult>.CacheKeyGenerator.get -> System.Func<Polly.ResilienceContext!, string?>?
+Polly.Caching.HybridCacheStrategyOptions<TResult>.CacheKeyGenerator.set -> void
+static Polly.HybridCacheResiliencePipelineBuilderExtensions.AddHybridCache<TResult>(this Polly.ResiliencePipelineBuilder<TResult>! builder, Polly.Caching.HybridCacheStrategyOptions<TResult>! options) -> Polly.ResiliencePipelineBuilder<TResult>!

test/Polly.AotTest/Polly.AotTest.csproj

@@ -8,6 +8,7 @@
     <TargetFramework>net9.0</TargetFramework>
   </PropertyGroup>
   <ItemGroup>
+    <ProjectReference Include="..\..\src\Polly.Caching\Polly.Caching.csproj" />
     <ProjectReference Include="..\..\src\Polly.Core\Polly.Core.csproj" />
     <ProjectReference Include="..\..\src\Polly.Extensions\Polly.Extensions.csproj" />
     <ProjectReference Include="..\..\src\Polly.RateLimiting\Polly.RateLimiting.csproj" />