< Summary

Information
Class: AmbientServices.AmbientLocalCache<TOWNER>
Assembly: AmbientServices
File(s): /home/runner/work/AmbientServices/AmbientServices/AmbientServices/Helpers/AmbientLocalCache.cs
Tag: 332_35464845198
Line coverage
100%
Covered lines: 4
Uncovered lines: 0
Coverable lines: 4
Total lines: 138
Line coverage: 100%
Branch coverage
N/A
Covered branches: 0
Total branches: 0
Branch coverage: N/A
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.ctor(...)100%11100%
.ctor(...)100%11100%

File(s)

/home/runner/work/AmbientServices/AmbientServices/AmbientServices/Helpers/AmbientLocalCache.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 cache.
 10/// </summary>
 11/// <remarks>
 12/// <pitch>The front door library that code uses for local caching: it namespaces every key with an owner prefix so unre
 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 and removal report not-found and stores are
 16/// A discarded store never disposes the item, even one offered with dispose-on-discard: with no cache to take ownership
 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 AmbientLocalCache
 23{
 24    private static readonly AmbientService<IAmbientLocalCache> _Cache = Ambient.GetService<IAmbientLocalCache>();
 25
 26    private readonly IAmbientLocalCache? _explicitCache;
 27    private readonly string _cacheKeyPrefix;
 28
 29    /// <summary>
 30    /// Creates the AmbientLocalCache using the ambient cache service.
 31    /// </summary>
 32    /// <param name="ownerType">The <see cref="Type"/> of the owner.</param>
 33    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 34    public AmbientLocalCache(Type ownerType, string? cacheKeyPrefix = null)
 35        : this(ownerType, null, cacheKeyPrefix)
 36    {
 37    }
 38    /// <summary>
 39    /// Creates the AmbientLocalCache using the specified cache service.
 40    /// </summary>
 41    /// <param name="ownerType">The <see cref="Type"/> of the owner.</param>
 42    /// <param name="cache">An explicit <see cref="IAmbientLocalCache"/> to use.</param>
 43    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 44    public AmbientLocalCache(Type ownerType, IAmbientLocalCache? cache, string? cacheKeyPrefix = null)
 45    {
 46        if (ownerType == null) throw new ArgumentNullException(nameof(ownerType));
 47        _cacheKeyPrefix = ownerType.Name + "-";
 48        _explicitCache = cache;
 49        if (cacheKeyPrefix != null) _cacheKeyPrefix = cacheKeyPrefix;
 50    }
 51    /// <summary>
 52    /// Retrieves the item with the specified key from the cache (if possible).
 53    /// </summary>
 54    /// <typeparam name="T">The type of the cached object.</typeparam>
 55    /// <param name="itemKey">The unique key used when the object was cached.</param>
 56    /// <param name="refresh">An optional <see cref="TimeSpan"/> indicating the length of time to extend the lifespan of
 57    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 58    /// <returns>The cached object, or null if it was not found in the cache.</returns>
 59    public ValueTask<T?> Retrieve<T>(string itemKey, TimeSpan? refresh = null, CancellationToken cancel = default) where
 60    {
 61        IAmbientLocalCache? cache = _explicitCache ?? _Cache.Local;
 62        if (cache == null) return TaskUtilities.ValueTaskFromResult<T?>(null);
 63        return cache.Retrieve<T>(_cacheKeyPrefix + itemKey, refresh, cancel);
 64    }
 65    /// <summary>
 66    /// Stores the specified item in the cache.
 67    /// </summary>
 68    /// <typeparam name="T">The type of the item to be cached.</typeparam>
 69    /// <param name="itemKey">A string that uniquely identifies the item being cached.</param>
 70    /// <param name="item">The item to be cached.</param>
 71    /// <param name="disposeWhenDiscarding">Whether or not to dispose disposable items (<see cref="IDisposable"/> or <se
 72    /// <param name="maxCacheDuration">An optional <see cref="TimeSpan"/> indicating the maximum amount of time to keep 
 73    /// <param name="expiration">An optional <see cref="DateTime"/> indicating a fixed time for when the item should exp
 74    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 75    ///
 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, bool disposeWhenDiscarding = false, TimeSpan? maxCacheDuration = n
 80    {
 81        IAmbientLocalCache? cache = _explicitCache ?? _Cache.Local;
 82        if (cache == null) return default;
 83        return cache.Store<T>(_cacheKeyPrefix + itemKey, item, disposeWhenDiscarding, maxCacheDuration, expiration, canc
 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    /// <returns>The item that was removed, or default if the specified item was not found.</returns>
 92    public async ValueTask<T?> Remove<T>(string itemKey, CancellationToken cancel = default) where T : class
 93    {
 94        IAmbientLocalCache? cache = _explicitCache ?? _Cache.Local;
 95        if (cache == null) return default;
 96        return await cache.Remove<T>(_cacheKeyPrefix + itemKey, cancel);
 97    }
 98    /// <summary>
 99    /// Flushes everything from the cache.
 100    /// </summary>
 101    /// <param name="cancel">The optional <see cref="CancellationToken"/>.</param>
 102    ///
 103    public ValueTask Clear(CancellationToken cancel = default)
 104    {
 105        IAmbientLocalCache? cache = _explicitCache ?? _Cache.Local;
 106        if (cache == null) return default;
 107        return cache.Clear(cancel);
 108    }
 109}
 110/// <summary>
 111/// A class that provides caching using either a specified cache or the ambient cache.  When you need a cache for a non-
 112/// </summary>
 113/// <typeparam name="TOWNER">The type that owns the items to be cached.</typeparam>
 114/// <remarks>
 115/// <pitch>The usual way to declare a cache: the owner is a type parameter, so the key prefix is derived at compile time
 116/// <pledge><see cref="AmbientLocalCache"/></pledge>
 117/// <plan>Passes <c>typeof(TOWNER)</c> to the base class; adds no behavior of its own.</plan>
 118/// </remarks>
 119public class AmbientLocalCache<TOWNER> : AmbientLocalCache
 120{
 121    /// <summary>
 122    /// Creates the AmbientLocalCache using the ambient cache service.
 123    /// </summary>
 124    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 125    public AmbientLocalCache(string? cacheKeyPrefix = null)
 2126        : this(null, cacheKeyPrefix)
 127    {
 2128    }
 129    /// <summary>
 130    /// Creates the AmbientLocalCache using the specified cache service.
 131    /// </summary>
 132    /// <param name="cache">An explicit <see cref="IAmbientLocalCache"/> to use.</param>
 133    /// <param name="cacheKeyPrefix">An optional cache key prefix for all items cached through this class.  Uses the typ
 134    public AmbientLocalCache(IAmbientLocalCache? cache, string? cacheKeyPrefix = null)
 2135        : base (typeof(TOWNER), cache, cacheKeyPrefix)
 136    {
 2137    }
 138}
Generated by: ReportGenerator 5.5.11.0
09/19/2026 - 19:43:35
GitHub | reportgenerator.io

Methods/Properties

.ctor(string)
.ctor(AmbientServices.IAmbientLocalCache, string)