< Summary

Information
Class: AmbientServices.AmbientSharedCache
Assembly: AmbientServices
File(s): /home/runner/work/AmbientServices/AmbientServices/AmbientServices/Helpers/AmbientSharedCache.cs
Tag: 332_35464845198
Line coverage
100%
Covered lines: 21
Uncovered lines: 0
Coverable lines: 21
Total lines: 189
Line coverage: 100%
Branch coverage
100%
Covered branches: 18
Total branches: 18
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.cctor()100%11100%
.ctor(...)100%11100%
.ctor(...)100%22100%
Retrieve<T>(...)100%44100%
Store<T>(...)100%44100%
Remove<T>(...)100%44100%
Clear(...)100%44100%

File(s)

/home/runner/work/AmbientServices/AmbientServices/AmbientServices/Helpers/AmbientSharedCache.cs

#LineLine coverage
 1using AmbientServices.Utilities;
 2using System;
 3using System.Threading;
 4using System.Threading.Tasks;
 5
 6namespace AmbientServices;
 7
 8/// <summary>
 9/// A class that provides caching using either a specified cache or the ambient shared cache (<see cref="IAmbientSharedC
 10/// </summary>
 11/// <remarks>
 12/// <pitch>The front door library code uses for shared caching of serializable values: it namespaces every key with an o
 13/// <pledge>
 14/// Every operation delegates to the explicit cache supplied at construction or, when none was, to whatever <see cref="I
 15/// When neither exists the call quietly succeeds without caching: retrieval reports not-found and stores are discarded.
 16/// Items must be serializable and must not be disposable, exactly as <see cref="IAmbientSharedCache"/> requires and for
 17/// All keys are prefixed with the owner type's name (or the supplied prefix) before reaching the underlying cache, so d
 18/// Clearing clears the entire underlying cache, not merely this owner's entries.
 19/// </pledge>
 20/// <plan>A stateless pass-through: it holds only the optional explicit cache and the computed key prefix, resolves the 
 21/// </remarks>
 22public class AmbientSharedCache
 23{
 224    private static readonly AmbientService<IAmbientSharedCache> _Cache = Ambient.GetService<IAmbientSharedCache>();
 25
 26    private readonly Type _type;
 27    private readonly string _defaultCachePrefix;
 28    private readonly IAmbientSharedCache? _explicitCache;
 29    private readonly string _cacheKeyPrefix;
 30
 31    /// <summary>
 32    /// Creates the AmbientSharedCache using the ambient cache service.
 33    /// </summary>
 34    /// <param name="ownerType">The <see cref="Type"/> for the owner.</param>
 35    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 36    public AmbientSharedCache(Type ownerType, string? cacheKeyPrefix = null)
 237        : this(ownerType, null, cacheKeyPrefix)
 38    {
 239    }
 40    /// <summary>
 41    /// Creates the AmbientSharedCache using the specified cache service.
 42    /// </summary>
 43    /// <param name="ownerType">The <see cref="Type"/> for the owner.</param>
 44    /// <param name="cache">An explicit <see cref="IAmbientSharedCache"/> to use.</param>
 45    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 246    public AmbientSharedCache(Type ownerType, IAmbientSharedCache? cache, string? cacheKeyPrefix = null)
 47    {
 248        _type = ownerType;
 249        _defaultCachePrefix = $"{_type.Name}-";
 250        _explicitCache = cache;
 251        _cacheKeyPrefix = cacheKeyPrefix ?? _defaultCachePrefix;
 252    }
 53    /// <summary>
 54    /// Retrieves the item with the specified key from the cache (if possible).
 55    /// </summary>
 56    /// <typeparam name="T">The type of the cached object.</typeparam>
 57    /// <param name="itemKey">The unique key used when the object was cached.</param>
 58    /// <param name="refresh">An optional <see cref="TimeSpan"/> indicating the length of time to extend the lifespan of
 59    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 60    /// <returns>The cached object, or null if it was not found in the cache.</returns>
 61    public ValueTask<T?> Retrieve<T>(string itemKey, TimeSpan? refresh = null, CancellationToken cancel = default) where
 62    {
 263        IAmbientSharedCache? cache = _explicitCache ?? _Cache.Local;
 264        if (cache == null) return TaskUtilities.ValueTaskFromResult<T?>(null);
 265        return cache.Retrieve<T>(_cacheKeyPrefix + itemKey, refresh, cancel);
 66    }
 67    /// <summary>
 68    /// Stores the specified item in the cache.
 69    /// </summary>
 70    /// <typeparam name="T">The type of the item to be cached.</typeparam>
 71    /// <param name="itemKey">A string that uniquely identifies the item being cached.</param>
 72    /// <param name="item">The item to be cached.</param>
 73    /// <param name="maxCacheDuration">An optional <see cref="TimeSpan"/> indicating the maximum amount of time to keep 
 74    /// <param name="expiration">An optional <see cref="DateTime"/> indicating a fixed time for when the item should exp
 75    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 76    /// <remarks>
 77    /// If both <paramref name="expiration"/> and <paramref name="maxCacheDuration"/> are set, the earlier expiration wi
 78    /// </remarks>
 79    public ValueTask Store<T>(string itemKey, T item, TimeSpan? maxCacheDuration = null, DateTime? expiration = null, Ca
 80    {
 281        IAmbientSharedCache? cache = _explicitCache ?? _Cache.Local;
 282        if (cache == null) return default;
 283        return cache.Store<T>(_cacheKeyPrefix + itemKey, item, maxCacheDuration, expiration, cancel);
 84    }
 85    /// <summary>
 86    /// Removes the specified item from the cache.
 87    /// </summary>
 88    /// <typeparam name="T">The type of the item to be cached.</typeparam>
 89    /// <param name="itemKey">A string that uniquely identifies the item being cached.</param>
 90    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 91    public ValueTask Remove<T>(string itemKey, CancellationToken cancel = default)
 92    {
 293        IAmbientSharedCache? cache = _explicitCache ?? _Cache.Local;
 294        if (cache == null) return default;
 295        return cache.Remove<T>(_cacheKeyPrefix + itemKey, cancel);
 96    }
 97    /// <summary>
 98    /// Flushes everything from the cache.
 99    /// </summary>
 100    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 101    public ValueTask Clear(CancellationToken cancel = default)
 102    {
 2103        IAmbientSharedCache? cache = _explicitCache ?? _Cache.Local;
 2104        if (cache == null) return default;
 2105        return cache.Clear(cancel);
 106    }
 107}
 108
 109/// <summary>
 110/// A generic type-specific shared cache owner class.  The name of the type is prepended to each cache key.
 111/// </summary>
 112/// <typeparam name="TOWNER">The type that owns the log messages.</typeparam>
 113/// <remarks>
 114/// <pitch>The usual way to declare a shared cache: the owner is a type parameter, so the key prefix is derived at compi
 115/// <pledge><see cref="AmbientSharedCache"/></pledge>
 116/// <plan>Passes <c>typeof(TOWNER)</c> to the base class; adds no behavior of its own.</plan>
 117/// </remarks>
 118public class AmbientSharedCache<TOWNER> : AmbientSharedCache
 119{
 120    /// <summary>
 121    /// Creates the AmbientSharedCache using the ambient cache service.
 122    /// </summary>
 123    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 124    public AmbientSharedCache(string? cacheKeyPrefix = null)
 125        : this(null, cacheKeyPrefix)
 126    {
 127    }
 128    /// <summary>
 129    /// Creates the AmbientSharedCache using the specified cache service.
 130    /// </summary>
 131    /// <param name="cache">An explicit <see cref="IAmbientSharedCache"/> to use.</param>
 132    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 133    public AmbientSharedCache(IAmbientSharedCache? cache, string? cacheKeyPrefix = null) : base(typeof(TOWNER), cache, c
 134    {
 135    }
 136}
 137
 138
 139// Remove these obsolete classes in 2026
 140/// <summary>
 141/// A class that provides caching using either a specified cache or the ambient shared cache (<see cref="IAmbientSharedC
 142/// </summary>
 143[Obsolete("Rename all references to AmbientSharedCache before 2026")]
 144public class AmbientCache : AmbientSharedCache
 145{
 146    /// <summary>
 147    /// Creates the AmbientSharedCache using the ambient cache service.
 148    /// </summary>
 149    /// <param name="ownerType">The <see cref="Type"/> for the owner.</param>
 150    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 151    public AmbientCache(Type ownerType, string? cacheKeyPrefix = null)
 152        : this(ownerType, null, cacheKeyPrefix)
 153    {
 154    }
 155    /// <summary>
 156    /// Creates the AmbientSharedCache using the specified cache service.
 157    /// </summary>
 158    /// <param name="ownerType">The <see cref="Type"/> for the owner.</param>
 159    /// <param name="cache">An explicit <see cref="IAmbientSharedCache"/> to use.</param>
 160    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 161    public AmbientCache(Type ownerType, IAmbientSharedCache? cache, string? cacheKeyPrefix = null)
 162        : base (ownerType, cache, cacheKeyPrefix)
 163    {
 164    }
 165}
 166/// <summary>
 167/// A generic type-specific shared cache owner .  The name of the type is prepended to each cache key.
 168/// </summary>
 169/// <typeparam name="TOWNER">The type that owns the log messages.</typeparam>
 170[Obsolete("Rename all references to AmbientSharedCache before 2026")]
 171public class AmbientCache<TOWNER> : AmbientSharedCache
 172{
 173    /// <summary>
 174    /// Creates the AmbientCache using the ambient cache service.
 175    /// </summary>
 176    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 177    public AmbientCache(string? cacheKeyPrefix = null)
 178        : this(null, cacheKeyPrefix)
 179    {
 180    }
 181    /// <summary>
 182    /// Creates the AmbientCache using the specified cache service.
 183    /// </summary>
 184    /// <param name="cache">An explicit <see cref="IAmbientSharedCache"/> to use.</param>
 185    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 186    public AmbientCache(IAmbientSharedCache? cache, string? cacheKeyPrefix = null) : base(typeof(TOWNER), cache, cacheKe
 187    {
 188    }
 189}
Generated by: ReportGenerator 5.5.11.0
09/19/2026 - 19:43:35
GitHub | reportgenerator.io

Methods/Properties

.cctor()
.ctor(System.Type, string)
.ctor(System.Type, AmbientServices.IAmbientSharedCache, string)
Retrieve<T>(string, System.Nullable<System.TimeSpan>, System.Threading.CancellationToken)
Store<T>(string, T, System.Nullable<System.TimeSpan>, System.Nullable<System.DateTime>, System.Threading.CancellationToken)
Remove<T>(string, System.Threading.CancellationToken)
Clear(System.Threading.CancellationToken)