Migrate HybridCache from aspnetcore to extensions (#5391)

this is a direct snapshot from dotnet/aspnetcore, with modifications to:

1. satisfy local repo style rules
2. work with different build setup

Minor global changes:

1. support netstandard2.1 on some legacy shim includes
2. add some additional required packages (for testing)

Author: mgravell

Directory.Build.targets

@@ -22,7 +22,7 @@
     <NoWarn>$(NoWarn);AD0001</NoWarn>
 
     <!-- Experimental warnings are for customers, not for this repo -->
-    <NoWarn>$(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017</NoWarn>
+    <NoWarn>$(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017;EXTEXP0018</NoWarn>
 
     <!-- Obsoletion warnings are for customers, not for this repo -->
     <NoWarn>$(NoWarn);EXTOBS0001;</NoWarn>

docs/list-of-diagnostics.md

@@ -40,6 +40,7 @@ if desired.
 | `EXTEXP0015` | Environmental probes experiments |
 | `EXTEXP0016` | Hosting integration testing experiments |
 | `EXTEXP0017` | Contextual options experiments |
+| `EXTEXP0018` | HybridCache experiments |
 
 # Obsoletions
 
@@ -81,7 +82,7 @@ You may continue using obsolete APIs in your application, but we advise explorin
 | `LOGGEN023` | Tag provider method is inaccessible |
 | `LOGGEN024` | Property provider method has an invalid signature |
 | `LOGGEN025` | Logging method parameters can't have "ref" or "out" modifiers |
-| `LOGGEN026` | Parameters with a custom tag provider are not subject to redaciton |
+| `LOGGEN026` | Parameters with a custom tag provider are not subject to redaction |
 | `LOGGEN027` | Multiple logging methods shouldn't use the same event name |
 | `LOGGEN028` | Logging method parameter's type has a hidden property |
 | `LOGGEN029` | A logging method parameter causes name conflicts |

eng/MSBuild/LegacySupport.props

@@ -7,11 +7,11 @@
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\IsExternalInit\*.cs" LinkBase="LegacySupport\IsExternalInit" />
   </ItemGroup>
 
-  <ItemGroup Condition="'$(InjectTrimAttributesOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netcoreapp3.1')">
+  <ItemGroup Condition="'$(InjectTrimAttributesOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1' or '$(TargetFramework)' == 'netcoreapp3.1')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\TrimAttributes\*.cs" LinkBase="LegacySupport\TrimAttributes" />
   </ItemGroup>
 
-  <ItemGroup Condition="'$(InjectCallerAttributesOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0')">
+  <ItemGroup Condition="'$(InjectCallerAttributesOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\CallerAttributes\*.cs" LinkBase="LegacySupport\CallerAttributes" />
   </ItemGroup>
 
@@ -47,7 +47,7 @@
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\TaskWaitAsync\*.cs" LinkBase="LegacySupport\TaskWaitAsync" />
   </ItemGroup>
 
-  <ItemGroup Condition="'$(InjectExperimentalAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netcoreapp3.1' or '$(TargetFramework)' == 'net6.0' or '$(TargetFramework)' == 'net7.0')">
+  <ItemGroup Condition="'$(InjectExperimentalAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1' or '$(TargetFramework)' == 'netcoreapp3.1' or '$(TargetFramework)' == 'net6.0' or '$(TargetFramework)' == 'net7.0')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\ExperimentalAttribute\*.cs" LinkBase="LegacySupport\ExperimentalAttribute" />
   </ItemGroup>
 

eng/Version.Details.xml

@@ -8,6 +8,10 @@
       <Uri>https://github.com/dotnet/runtime</Uri>
       <Sha>31528d082bd760377b8d818fc839a338cd071b1f</Sha>
     </Dependency>
+    <Dependency Name="Microsoft.Extensions.Caching.Memory" Version="9.0.0-rc.2.24453.5" CoherentParentDependency="Microsoft.AspNetCore.App.Runtime.win-x64">
+      <Uri>https://github.com/dotnet/runtime</Uri>
+      <Sha>418c3b9e2753715fa017ace6b3f1f5ec4d4d6aae</Sha>
+    </Dependency>
     <Dependency Name="Microsoft.Extensions.Configuration.Abstractions" Version="9.0.0-rc.2.24453.5" CoherentParentDependency="Microsoft.AspNetCore.App.Runtime.win-x64">
       <Uri>https://github.com/dotnet/runtime</Uri>
       <Sha>31528d082bd760377b8d818fc839a338cd071b1f</Sha>
@@ -144,6 +148,10 @@
       <Uri>https://github.com/dotnet/aspnetcore</Uri>
       <Sha>fc4f8810d8df45a9f42e02f688041bf592c18138</Sha>
     </Dependency>
+    <Dependency Name="Microsoft.Extensions.Caching.SqlServer" Version="9.0.0-rc.2.24460.5">
+      <Uri>https://github.com/dotnet/aspnetcore</Uri>
+      <Sha>2b865e33f2c7c9484c28a3b62e8ff07966e23434</Sha>
+    </Dependency>
     <Dependency Name="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.0.0-rc.2.24460.5">
       <Uri>https://github.com/dotnet/aspnetcore</Uri>
       <Sha>fc4f8810d8df45a9f42e02f688041bf592c18138</Sha>

eng/Versions.props

@@ -30,6 +30,7 @@
     <!-- Packages from dotnet/runtime -->
     <MicrosoftBclTimeProviderVersion>9.0.0-rc.2.24453.5</MicrosoftBclTimeProviderVersion>
     <MicrosoftExtensionsCachingAbstractionsVersion>9.0.0-rc.2.24453.5</MicrosoftExtensionsCachingAbstractionsVersion>
+    <MicrosoftExtensionsCachingMemoryVersion>9.0.0-rc.2.24453.5</MicrosoftExtensionsCachingMemoryVersion>
     <MicrosoftExtensionsConfigurationAbstractionsVersion>9.0.0-rc.2.24453.5</MicrosoftExtensionsConfigurationAbstractionsVersion>
     <MicrosoftExtensionsConfigurationBinderVersion>9.0.0-rc.2.24453.5</MicrosoftExtensionsConfigurationBinderVersion>
     <MicrosoftExtensionsConfigurationJsonVersion>9.0.0-rc.2.24453.5</MicrosoftExtensionsConfigurationJsonVersion>
@@ -64,6 +65,7 @@
     <MicrosoftAspNetCoreAppRuntimewinx64Version>9.0.0-rc.2.24460.5</MicrosoftAspNetCoreAppRuntimewinx64Version>
     <MicrosoftAspNetCoreMvcTestingVersion>9.0.0-rc.2.24460.5</MicrosoftAspNetCoreMvcTestingVersion>
     <MicrosoftAspNetCoreTestHostVersion>9.0.0-rc.2.24460.5</MicrosoftAspNetCoreTestHostVersion>
+    <MicrosoftExtensionsCachingSqlServerVersion>9.0.0-rc.2.24460.5</MicrosoftExtensionsCachingSqlServerVersion>
     <MicrosoftExtensionsCachingStackExchangeRedisVersion>9.0.0-rc.2.24460.5</MicrosoftExtensionsCachingStackExchangeRedisVersion>
     <MicrosoftExtensionsDiagnosticsHealthChecksVersion>9.0.0-rc.2.24460.5</MicrosoftExtensionsDiagnosticsHealthChecksVersion>
     <MicrosoftExtensionsHttpPollyVersion>9.0.0-rc.2.24460.5</MicrosoftExtensionsHttpPollyVersion>

eng/packages/General.props

@@ -10,6 +10,9 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="$(MicrosoftCodeAnalysisVersion)" />
     <PackageVersion Include="Microsoft.CodeAnalysis" Version="$(MicrosoftCodeAnalysisVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Abstractions" Version="$(MicrosoftExtensionsCachingAbstractionsVersion)" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="$(MicrosoftExtensionsCachingMemoryVersion)" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.SqlServer" Version="$(MicrosoftExtensionsCachingSqlServerVersion)" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="$(MicrosoftExtensionsCachingStackExchangeRedisVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="$(MicrosoftExtensionsConfigurationAbstractionsVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="$(MicrosoftExtensionsConfigurationBinderVersion)" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="$(MicrosoftExtensionsConfigurationJsonVersion)" />

eng/spellchecking_exclusions.dic

@@ -0,0 +1,62 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Caching.Hybrid;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DependencyInjection;
+
+/// <summary>
+/// Configuration extension methods for <see cref="IHybridCacheBuilder"/> / <see cref="HybridCache"/>.
+/// </summary>
+public static class HybridCacheBuilderExtensions
+{
+    /// <summary>
+    /// Serialize values of type <typeparamref name="T"/> with the specified serializer from <paramref name="serializer"/>.
+    /// </summary>
+    /// <typeparam name="T">The type to be serialized.</typeparam>
+    /// <returns>The <see cref="IHybridCacheBuilder"/> instance.</returns>
+    public static IHybridCacheBuilder AddSerializer<T>(this IHybridCacheBuilder builder, IHybridCacheSerializer<T> serializer)
+    {
+        _ = Throw.IfNull(builder).Services.AddSingleton<IHybridCacheSerializer<T>>(serializer);
+        return builder;
+    }
+
+    /// <summary>
+    /// Serialize values of type <typeparamref name="T"/> with the serializer of type <typeparamref name="TImplementation"/>.
+    /// </summary>
+    /// <typeparam name="T">The type to be serialized.</typeparam>
+    /// <typeparam name="TImplementation">The serializer to use for this type.</typeparam>
+    /// <returns>The <see cref="IHybridCacheBuilder"/> instance.</returns>
+    public static IHybridCacheBuilder AddSerializer<T,
+        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TImplementation>(this IHybridCacheBuilder builder)
+        where TImplementation : class, IHybridCacheSerializer<T>
+    {
+        _ = Throw.IfNull(builder).Services.AddSingleton<IHybridCacheSerializer<T>, TImplementation>();
+        return builder;
+    }
+
+    /// <summary>
+    /// Add <paramref name="factory"/> as an additional serializer factory, which can provide serializers for multiple types.
+    /// </summary>
+    /// <returns>The <see cref="IHybridCacheBuilder"/> instance.</returns>
+    public static IHybridCacheBuilder AddSerializerFactory(this IHybridCacheBuilder builder, IHybridCacheSerializerFactory factory)
+    {
+        _ = Throw.IfNull(builder).Services.AddSingleton<IHybridCacheSerializerFactory>(factory);
+        return builder;
+    }
+
+    /// <summary>
+    /// Add a factory of type <typeparamref name="TImplementation"/> as an additional serializer factory, which can provide serializers for multiple types.
+    /// </summary>
+    /// <typeparam name="TImplementation">The type of the serializer factory.</typeparam>
+    /// <returns>The <see cref="IHybridCacheBuilder"/> instance.</returns>
+    public static IHybridCacheBuilder AddSerializerFactory<
+        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TImplementation>(this IHybridCacheBuilder builder)
+        where TImplementation : class, IHybridCacheSerializerFactory
+    {
+        _ = Throw.IfNull(builder).Services.AddSingleton<IHybridCacheSerializerFactory, TImplementation>();
+        return builder;
+    }
+}

src/Libraries/Microsoft.Extensions.Caching.Hybrid/HybridCacheBuilderExtensions.cs

@@ -0,0 +1,44 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.Extensions.Caching.Hybrid;
+
+/// <summary>
+/// Options for configuring the default <see cref="HybridCache"/> implementation.
+/// </summary>
+public class HybridCacheOptions
+{
+    private const int ShiftBytesToMibiBytes = 20;
+
+    /// <summary>
+    /// Gets or sets the default global options to be applied to <see cref="HybridCache"/> operations; if options are
+    /// specified at the individual call level, the non-null values are merged (with the per-call
+    /// options being used in preference to the global options). If no value is specified for a given
+    /// option (globally or per-call), the implementation may choose a reasonable default.
+    /// </summary>
+    public HybridCacheEntryOptions? DefaultEntryOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether compression for this <see cref="HybridCache"/> instance is disabled.
+    /// </summary>
+    public bool DisableCompression { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum size of cache items; attempts to store values over this size will be logged
+    /// and the value will not be stored in cache.
+    /// </summary>
+    /// <remarks>The default value is 1 MiB.</remarks>
+    public long MaximumPayloadBytes { get; set; } = 1 << ShiftBytesToMibiBytes; // 1MiB
+
+    /// <summary>
+    /// Gets or sets the maximum permitted length (in characters) of keys; attempts to use keys over this size will be logged.
+    /// </summary>
+    /// <remark>The default value is 1024 characters.</remark>
+    public int MaximumKeyLength { get; set; } = 1024; // characters
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use "tags" data as dimensions on metric reporting; if enabled, care should be used to ensure that
+    /// tags do not contain data that should not be visible in metrics systems.
+    /// </summary>
+    public bool ReportTagMetrics { get; set; }
+}

src/Libraries/Microsoft.Extensions.Caching.Hybrid/HybridCacheOptions.cs

@@ -0,0 +1,44 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.Extensions.Caching.Hybrid;
+using Microsoft.Extensions.Caching.Hybrid.Internal;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.DependencyInjection;
+
+/// <summary>
+/// Configuration extension methods for <see cref="HybridCache"/>.
+/// </summary>
+public static class HybridCacheServiceExtensions
+{
+    /// <summary>
+    /// Adds support for multi-tier caching services.
+    /// </summary>
+    /// <returns>A builder instance that allows further configuration of the <see cref="HybridCache"/> system.</returns>
+    public static IHybridCacheBuilder AddHybridCache(this IServiceCollection services, Action<HybridCacheOptions> setupAction)
+    {
+        _ = Throw.IfNull(setupAction);
+        _ = AddHybridCache(services);
+        _ = services.Configure(setupAction);
+        return new HybridCacheBuilder(services);
+    }
+
+    /// <summary>
+    /// Adds support for multi-tier caching services.
+    /// </summary>
+    /// <returns>A builder instance that allows further configuration of the <see cref="HybridCache"/> system.</returns>
+    public static IHybridCacheBuilder AddHybridCache(this IServiceCollection services)
+    {
+        _ = Throw.IfNull(services);
+        services.TryAddSingleton(TimeProvider.System);
+        _ = services.AddOptions().AddMemoryCache();
+        services.TryAddSingleton<IHybridCacheSerializerFactory, DefaultJsonSerializerFactory>();
+        services.TryAddSingleton<IHybridCacheSerializer<string>>(InbuiltTypeSerializer.Instance);
+        services.TryAddSingleton<IHybridCacheSerializer<byte[]>>(InbuiltTypeSerializer.Instance);
+        services.TryAddSingleton<HybridCache, DefaultHybridCache>();
+        return new HybridCacheBuilder(services);
+    }
+}