From d71e7b8b541f50f12f249047ab6bea05187e4559 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= <hi_kalkan@yahoo.com>
Date: Sun, 13 Oct 2019 11:13:48 +0300
Subject: [PATCH] Added Caching documentation.

---
 docs/en/Caching.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/en/Caching.md b/docs/en/Caching.md
index f7d9c52407..c413a4599c 100644
--- a/docs/en/Caching.md
+++ b/docs/en/Caching.md
@@ -1,3 +1,85 @@
 # Caching
 
+ABP framework extends ASP.NET Core's distributed caching system.
+
+## IDistributedCache Interface
+
+ASP.NET Core defines the `IDistributedCache` interface to get/set cache values. But it has some difficulties:
+
+* It works with **byte arrays** rather than .NET objects. So, you need to **serialize/deserialize** the objects you need to cache.
+* It provides a **single key pool** for all cache items, so;
+  * You need to care about the keys to distinguish **different type of objects**.
+  * You need to care about the cache items of **different tenants** (see [multi-tenancy](Multi-Tenancy.md)).
+
+> `IDistributedCache` is defined in the `Microsoft.Extensions.Caching.Abstractions` package. That means it is not only usable for ASP.NET Core applications, but also available to **any type of applications**.
+
+> Default implementation of the `IDistributedCache` interface is the `MemoryDistributedCache` which works **in-memory**. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to **Redis** or another cache provider.
+
+See [ASP.NET Core's distributed caching document](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) for more information.
+
+## IDistributedCache<TCacheItem> Interface
+
+ABP framework defines the generic `IDistributedCache<TCacheItem>` interface in the [Volo.Abp.Caching](https://www.nuget.org/packages/Volo.Abp.Caching/) package. `TCacheItem` is the type of the object stored in the cache.
+
+`IDistributedCache<TCacheItem>` solves the difficulties explained above;
+
+* It internally **serializes/deserializes** the cached objects. Uses **JSON** serialization by default, but can be overridden by replacing the `IDistributedCacheSerializer` service in the [dependency injection](Dependency-Injection.md) system.
+* It automatically adds a **cache name** prefix to the cache keys based on the object type stored in the cache. Default cache name is the full name of the cache item class (`CacheItem` postfix is removed if your cache item class ends with it). You can use the `CacheName` attribute on the cache item class to set the cache name.
+* It automatically adds the **current tenant id** to the cache key to distinguish cache items for different tenants (only works if your application is [multi-tenant](Multi-Tenancy.md)). Define `IgnoreMultiTenancy` attribute on the cache item class to disable this if you want to share the cached objects among all tenants in a multi-tenant application.
+* Allows to define a **global cache key prefix** per application, so different applications can use their isolated key pools in a shared distributed cache source.
+
+### Usage
+
+An example class to store an item in the cache:
+
+````csharp
+public class BookCacheItem
+{
+    public string Name { get; set; }
+
+    public float Price { get; set; }
+}
+````
+
+You can inject and use the `IDistributedCache<BookCacheItem>` service to get/set `BookCacheItem` objects.
+
+Example usage:
+
+````csharp
+public class BookService : ITransientDependency
+{
+    private readonly IDistributedCache<BookCacheItem> _cache;
+
+    public BookService(IDistributedCache<BookCacheItem> cache)
+    {
+        _cache = cache;
+    }
+
+    public async Task<BookCacheItem> GetAsync(Guid bookId)
+    {
+        return await _cache.GetOrAddAsync(
+            bookId.ToString(), //Cache key
+            async () => await GetBookFromDatabaseAsync(bookId),
+            () => new DistributedCacheEntryOptions
+            {
+                AbsoluteExpiration = DateTimeOffset.Now.AddHours(1)
+            }
+        );
+    }
+
+    private Task<BookCacheItem> GetBookFromDatabaseAsync(Guid bookId)
+    {
+        //TODO: get from database
+    }
+}
+````
+
+* This sample service uses the `GetOrAddAsync()` method to get a book item from the cache.
+* If the book was not found in the cache, it calls the factory method (`GetBookFromDatabaseAsync` in this case) to retrieve the book item from the original source.
+* `GetOrAddAsync` optionally gets a `DistributedCacheEntryOptions` which can be used to set the lifetime of the cached item.
+
+Other methods of the `IDistributedCache<BookCacheItem>` are same as ASP.NET Core's `IDistributedCache` interface, so you can refer [it's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed).
+
+### DistributedCacheOptions
+
 TODO
\ No newline at end of file