docs: Builder extension method example

Author: vittorelli

docs/extensions/create-specification-builder.md

@@ -5,4 +5,70 @@ parent: Extensions
 nav_order: 2
 ---
 
-How to create your own specification builder
+
+# How to create your own specification builder
+How to create your own specification builder 
+
+## Example: Configure caching behaviour through specification builder extension method
+
+In order to achieve this:
+
+````csharp
+public class CustomerByNameWithStores : Specification<Customer>
+{
+    public CustomerByNameWithStores(string name)
+    {
+        Query.Where(x => x.Name == name)
+            .EnableCache(nameof(CustomerByNameWithStoresSpec), name)
+                // Can only be called after .EnableCache()
+                .WithTimeToLive(TimeSpan.FromHours(1))
+            .Include(x => x.Stores);
+    }
+}
+````
+
+We can create a simple extension method on the specification builder:
+
+````csharp
+public static class SpecificationBuilderExtensions
+{
+    public static ISpecificationBuilder<T> WithTimeToLive<T>(this ISpecificationBuilder<T> @this, TimeSpan ttl)
+        where T : class
+    {
+        @this.Specification.SetCacheTTL(ttl);
+        return @this;
+    }
+}
+````
+
+This extension method can only be called when chained after `SpecificationBuilderExtensions.EnableCache`. This is because `EnableCache` returns `ICacheSpecificationBuilder<T>` which inherits from `ISpecificationBuilder<T>`.
+
+```csharp
+// TODO: Repository example
+```
+
+Finally, we need to take of some plumbing to implement both `` and ``. The class below uses `ConditionalWeakTable` to do the trick. An other solution is to create a base class that inherits from `Specification<T>`.
+
+````csharp
+public static class SpecificationExtentions
+{
+    private static readonly ConditionalWeakTable<object, CacheOptions> SpecificationCacheOptions = new();
+
+    public static void SetCacheTTL<T>(this ISpecification<T> spec, TimeSpan ttl)
+    {
+        SpecificationCacheOptions.AddOrUpdate(spec, new CacheOptions() { TTL = ttl });
+    }
+
+    public static TimeSpan GetCacheTTL<T>(this ISpecification<T> spec)
+    {
+        var opts = SpecificationCacheOptions.GetOrCreateValue(spec);
+        return opts?.TTL ?? TimeSpan.MaxValue;
+    }
+
+    // ConditionalWeakTable need reference types; TimeSpan is a struct
+    private class CacheOptions
+    {
+        public TimeSpan TTL { get; set; }
+    }
+}
+````

docs/features/caching.md

@@ -23,6 +23,6 @@ public class CustomerByNameWithStoresSpec : Specification<Customer>, ISingleResu
     }
 ```
 
-The `.EnableCache` method takes in two parameters: the name of the specification and the parameters of the specification.
+The `.EnableCache` method takes in two parameters: the name of the specification and the parameters of the specification. It does not include any parameters to control how the cache should behave (e.g. absolute expiration date, expiration tokens, ...). However, one could create an extension method to the specification builder in order to add this information ([example](../extensions/create-specification-builder.md)).
 
 Implementing caching will also require infrastructure such as a CachedRepository, an example of which is given in [the sample](https://github.com/ardalis/Specification/blob/2605202df4d8e40fe388732db6d8f7a3754fcc2b/sample/Ardalis.SampleApp.Infrastructure/Data/CachedCustomerRepository.cs#L13) on GitHub. The `EnableCache` method is used to inform the cache implementation that caching should be used, and to configure the `CacheKey` based on the arguments supplied.