From d47b6553ef94898b9dd624f3fb24571085518559 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 09:51:23 +0300 Subject: [PATCH 01/10] Update cache document and add initial kb document --- docs/en/framework/fundamentals/caching.md | 6 +++--- docs/en/kb/when-to-use-a-distributed-cache-server.md | 8 ++++++++ 2 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 docs/en/kb/when-to-use-a-distributed-cache-server.md diff --git a/docs/en/framework/fundamentals/caching.md b/docs/en/framework/fundamentals/caching.md index 9b29763737..7169d82d5e 100644 --- a/docs/en/framework/fundamentals/caching.md +++ b/docs/en/framework/fundamentals/caching.md @@ -1,12 +1,12 @@ # Distributed Caching -ABP extends the [ASP.NET Core distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). +ABP extends the [ASP.NET Core distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to provide a more comfortable and easy-to-use cache service. -> **Default implementation of the `IDistributedCache` interface is` 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. Also, see the [Redis Cache](./redis-cache.md) document if you want to use Redis as the distributed cache server. +> **Default implementation of the `IDistributedCache` interface is` MemoryDistributedCache` which works in-memory.** Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, consider to use a distributed cache server. See the ***[Why to Use a Distributed Cache Server](../../kb/when-to-use-a-distributed-cache-server.md)*** document for more details. ## Installation -> This package is already installed by default with the [application startup template](../../solution-templates/layered-web-application). So, most of the time, you don't need to install it manually. +> This package is already installed by default in [startup templates](../../solution-templates/index.md). So, most of the time, you don't need to install it manually. [Volo.Abp.Caching](https://www.nuget.org/packages/Volo.Abp.Caching) is the main package of the caching system. You can install it a project using the add-package command of the [ABP CLI](../../cli): diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md new file mode 100644 index 0000000000..9ad97a4f2a --- /dev/null +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -0,0 +1,8 @@ +# Why to Use a Distributed Cache Server + +TODO + + + +See the [Redis Cache](./redis-cache.md) document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. + From fb2e7fda12afa4685de2c43f634fd8a4f1312400 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 13:23:28 +0300 Subject: [PATCH 02/10] Update when-to-use-a-distributed-cache-server.md --- .../when-to-use-a-distributed-cache-server.md | 35 +++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md index 9ad97a4f2a..68bf5189e8 100644 --- a/docs/en/kb/when-to-use-a-distributed-cache-server.md +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -1,8 +1,39 @@ # Why to Use a Distributed Cache Server -TODO +ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). +## Understanding the Default Cache Service +**Default implementation of the cache service works in-memory**. Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, **you should use a real distributed cache server**. -See the [Redis Cache](./redis-cache.md) document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. +Here, a few example cases where you should use a distributed cache server: +* You have a **monolith application**, but you run **multiple instances** of that application concurrently, for example, in a [clustered environment](../deployment/clustered-environment.md) +* You build a **microservice** or any kind of **distributed** system +* You have web **multiple applications** in your solution and they should share the same cache + +The problem is obvious: If each application instance uses its internal in-memory cache, and if two or more applications cache the same data, it is probable that they will cache different copies of the data. In that case, there is no way to **invalidate/refresh** that data in every application's memory when the data changes. + +## What is a Distributed Cache Server + +A **distributed cache server** (e.g. [Redis](../framework/fundamentals/redis-cache.md)) stores cache objects in a separate server application and allows multiple applications/processes share the same cache objects. In that way; + +* All applications/services and all their instances use the same cache store and share the same cached objects. Once an application instance refreshes a cached object, all others use the new object. +* Even if your applications stop and restart, the cached objects are not lost, since they are managed by a separate cache server. + +## How to Use a Distributed Cache Server + +ABP [solution templates](../solution-templates/index.md) come with Redis configured when it is certainly necessary. For example; + +* The [microservice startup template](../solution-templates/microservice/index.md) always comes with [Redis configured](../solution-templates/microservice/distributed-cache.md) and also included as a docker container. + +* The application startup template comes with Redis configured when you select multiple applications, tiered architecture, etc. + +In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In that case, you should manually switch to a distributed cache provider for your application. + +See the *[Redis Cache](../framework/fundamentals/redis-cache.md)* document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. + +## See Also + +* [ABP Distributed Cache](../framework/fundamentals/caching.md) +* [ASP.NET Core Distributed Cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) From 8d96673d6411a267eeea02dcfa99d33ff8244842 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 13:44:30 +0300 Subject: [PATCH 03/10] Update when-to-use-a-distributed-cache-server.md --- docs/en/kb/when-to-use-a-distributed-cache-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md index 68bf5189e8..54158e73b5 100644 --- a/docs/en/kb/when-to-use-a-distributed-cache-server.md +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -27,9 +27,9 @@ ABP [solution templates](../solution-templates/index.md) come with Redis configu * The [microservice startup template](../solution-templates/microservice/index.md) always comes with [Redis configured](../solution-templates/microservice/distributed-cache.md) and also included as a docker container. -* The application startup template comes with Redis configured when you select multiple applications, tiered architecture, etc. +* The application startup template comes with Redis configured when you select multiple applications, tiered architecture, or some other configuration that requires a distributed cache server. -In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In that case, you should manually switch to a distributed cache provider for your application. +In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In that cases, if you need a distributed cache server, you should manually switch to a distributed cache provider for your application. See the *[Redis Cache](../framework/fundamentals/redis-cache.md)* document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. From 89061fa3f00b1b44506727bc3a99d9a7b11bdb1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 14:25:15 +0300 Subject: [PATCH 04/10] Update single-layer-web-application.md --- docs/en/get-started/single-layer-web-application.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/en/get-started/single-layer-web-application.md b/docs/en/get-started/single-layer-web-application.md index 5d936e7966..e87f8b845c 100644 --- a/docs/en/get-started/single-layer-web-application.md +++ b/docs/en/get-started/single-layer-web-application.md @@ -24,11 +24,6 @@ The following tools should be installed on your development machine: * [Node v20.11+](https://nodejs.org/) * [Yarn v1.22+ (not v2)](https://classic.yarnpkg.com/en/docs/install) [2](#f-yarn) or npm v10+ (already installed with Node) {{ end }} -{{ if Tiered == "Yes" }} -* [Redis](https://redis.io/) (as the [distributed cache](../framework/fundamentals/caching.md)). -{{ else }} -* [Redis](https://redis.io/) (as the [distributed cache](../framework/fundamentals/caching.md)) is required if you select the Public website option. -{{ end }} 1 _You can use another editor instead of Visual Studio as long as it supports .NET Core and ASP.NET Core._ [↩](#a-editor) From 68f5bb21ba6283dafafc9adc4378e1841829a218 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 14:25:21 +0300 Subject: [PATCH 05/10] Installing a Redis Server to Your Local Environment --- docs/en/kb/when-to-use-a-distributed-cache-server.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md index 54158e73b5..42ee41c5f8 100644 --- a/docs/en/kb/when-to-use-a-distributed-cache-server.md +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -33,6 +33,16 @@ In other cases, to keep the dependencies minimal, they come with the default (in See the *[Redis Cache](../framework/fundamentals/redis-cache.md)* document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. +### Installing a Redis Server to Your Local Environment + +If you want to use Redis as your distributed cache provider in your development environment, you can simply use the [official Redis docker image](https://hub.docker.com/_/redis). Once you have [Docker](https://www.docker.com/products/docker-desktop/) in your local machine, you can use the following command to run a Redis container and map the default Redis port: + +````bash +docker run -p 6379:6379 --name RedisServer -d redis +```` + +You can check the [official Redis docker image](https://hub.docker.com/_/redis) document for more options. + ## See Also * [ABP Distributed Cache](../framework/fundamentals/caching.md) From f9f0047d729842744d48dee47a3ce3cbb6eb99b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 14:40:31 +0300 Subject: [PATCH 06/10] Remove redis pre-requirement Since new startup templates come with redis as docker container. --- docs/en/get-started/layered-web-application.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/en/get-started/layered-web-application.md b/docs/en/get-started/layered-web-application.md index c680fe797f..44d3780cd3 100644 --- a/docs/en/get-started/layered-web-application.md +++ b/docs/en/get-started/layered-web-application.md @@ -25,11 +25,7 @@ The following tools should be installed on your development machine: * [Node v20.11+](https://nodejs.org/) * [Yarn v1.22+ (not v2)](https://classic.yarnpkg.com/en/docs/install) [2](#f-yarn) or npm v10+ (already installed with Node) {{ end }} -{{ if Tiered == "Yes" }} -* [Redis](https://redis.io/) (as the [distributed cache](../framework/fundamentals/caching.md)). -{{ else }} -* [Redis](https://redis.io/) (as the [distributed cache](../framework/fundamentals/caching.md)) is required if you select the Public website option. -{{ end }} +* [Docker Desktop](https://www.docker.com/products/docker-desktop/) 1 _You can use another editor instead of Visual Studio as long as it supports .NET Core and ASP.NET Core._ [↩](#a-editor) @@ -229,7 +225,7 @@ You can start the following application(s): {{ else }} - `Acme.BookStore.Web` {{ end }} - + Before starting the mobile application, ensure that you configure it for [react-native](../framework/ui/react-native) or [MAUI](../framework/ui/maui). ![mobile-sample](images/abp-studio-mobile-sample.gif) From 97419370f38c45bbd2262c4bf537768189e6c073 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 14:44:46 +0300 Subject: [PATCH 07/10] Update when-to-use-a-distributed-cache-server.md --- docs/en/kb/when-to-use-a-distributed-cache-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md index 42ee41c5f8..c2067a84c6 100644 --- a/docs/en/kb/when-to-use-a-distributed-cache-server.md +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -1,6 +1,6 @@ -# Why to Use a Distributed Cache Server +# When to Use a Distributed Cache Server -ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). +ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). This document explains when do you need to have a separate cache server for your applications. ## Understanding the Default Cache Service From 4cd1e9e7df42adc3e1c53492fb09369906c1359f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 19 Dec 2024 14:48:59 +0300 Subject: [PATCH 08/10] Create index.md --- docs/en/kb/index.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/en/kb/index.md diff --git a/docs/en/kb/index.md b/docs/en/kb/index.md new file mode 100644 index 0000000000..8a497cdeee --- /dev/null +++ b/docs/en/kb/index.md @@ -0,0 +1,6 @@ +# ABP Knowledge Base + +The following documents provide useful information about several topics you might need to know. + +* [How to Fix "Filename too long" Error on Windows](windows-path-too-long-fix.md) +* [When to Use a Distributed Cache Server](when-to-use-a-distributed-cache-server.md) \ No newline at end of file From 7631ac3fc359f9fef629c48ee61029a9c92901c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:33:13 +0300 Subject: [PATCH 09/10] Update when-to-use-a-distributed-cache-server.md --- docs/en/kb/when-to-use-a-distributed-cache-server.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/kb/when-to-use-a-distributed-cache-server.md b/docs/en/kb/when-to-use-a-distributed-cache-server.md index c2067a84c6..a414e5cd78 100644 --- a/docs/en/kb/when-to-use-a-distributed-cache-server.md +++ b/docs/en/kb/when-to-use-a-distributed-cache-server.md @@ -1,12 +1,12 @@ # When to Use a Distributed Cache Server -ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). This document explains when do you need to have a separate cache server for your applications. +ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). This document explains when you need to have a separate cache server for your applications. ## Understanding the Default Cache Service **Default implementation of the cache service works in-memory**. Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, **you should use a real distributed cache server**. -Here, a few example cases where you should use a distributed cache server: +Here are a few example cases where you should use a distributed cache server: * You have a **monolith application**, but you run **multiple instances** of that application concurrently, for example, in a [clustered environment](../deployment/clustered-environment.md) * You build a **microservice** or any kind of **distributed** system @@ -16,7 +16,7 @@ The problem is obvious: If each application instance uses its internal in-memory ## What is a Distributed Cache Server -A **distributed cache server** (e.g. [Redis](../framework/fundamentals/redis-cache.md)) stores cache objects in a separate server application and allows multiple applications/processes share the same cache objects. In that way; +A **distributed cache server** (e.g. [Redis](../framework/fundamentals/redis-cache.md)) stores cache objects in a separate server application and allows multiple applications/processes to share the same cache objects. In that way; * All applications/services and all their instances use the same cache store and share the same cached objects. Once an application instance refreshes a cached object, all others use the new object. * Even if your applications stop and restart, the cached objects are not lost, since they are managed by a separate cache server. @@ -29,7 +29,7 @@ ABP [solution templates](../solution-templates/index.md) come with Redis configu * The application startup template comes with Redis configured when you select multiple applications, tiered architecture, or some other configuration that requires a distributed cache server. -In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In that cases, if you need a distributed cache server, you should manually switch to a distributed cache provider for your application. +In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In those cases, if you need a distributed cache server, you should manually switch to a distributed cache provider for your application. See the *[Redis Cache](../framework/fundamentals/redis-cache.md)* document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. From 75d578ae36de5c31c32abc5b3d1254a212197f9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:36:06 +0300 Subject: [PATCH 10/10] Update caching.md --- docs/en/framework/fundamentals/caching.md | 40 +++++++++++------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/en/framework/fundamentals/caching.md b/docs/en/framework/fundamentals/caching.md index 7169d82d5e..3f8a4f4a19 100644 --- a/docs/en/framework/fundamentals/caching.md +++ b/docs/en/framework/fundamentals/caching.md @@ -2,13 +2,13 @@ ABP extends the [ASP.NET Core distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to provide a more comfortable and easy-to-use cache service. -> **Default implementation of the `IDistributedCache` interface is` MemoryDistributedCache` which works in-memory.** Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, consider to use a distributed cache server. See the ***[Why to Use a Distributed Cache Server](../../kb/when-to-use-a-distributed-cache-server.md)*** document for more details. +> **Default implementation of the `IDistributedCache` interface is` MemoryDistributedCache` which works in-memory.** Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, consider using a distributed cache server. See the ***[Why to Use a Distributed Cache Server](../../kb/when-to-use-a-distributed-cache-server.md)*** document for more details. ## Installation > This package is already installed by default in [startup templates](../../solution-templates/index.md). So, most of the time, you don't need to install it manually. -[Volo.Abp.Caching](https://www.nuget.org/packages/Volo.Abp.Caching) is the main package of the caching system. You can install it a project using the add-package command of the [ABP CLI](../../cli): +[Volo.Abp.Caching](https://www.nuget.org/packages/Volo.Abp.Caching) is the main package of the caching system. You can install it as a project using the add-package command of the [ABP CLI](../../cli): ```bash abp add-package Volo.Abp.Caching @@ -24,10 +24,10 @@ ASP.NET Core defines the `IDistributedCache` interface to get/set the cache valu * 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 keys to distinguish **different types of objects**. * You need to care about the cache items of **different tenants** in a [multi-tenant](../architecture/multi-tenancy) system. -> `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**. +> `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**. See [ASP.NET Core's distributed caching document](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) for more information. @@ -37,12 +37,12 @@ ABP defines the generic `IDistributedCache` interface in the [Volo.A `IDistributedCache` 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 internally **serializes/deserializes** the cached objects. It 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. The 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 (if your application is [multi-tenant](../architecture/multi-tenancy)). 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 server. +* Allows defining a **global cache key prefix** per application so different applications can use their isolated key pools in a shared distributed cache server. * It **can tolerate errors** wherever possible and bypasses the cache. This is useful when you have temporary problems on the cache server. -* It has methods like `GetManyAsync` and `SetManyAsync` which significantly improve the performance on **batch operations**. +* It has methods like `GetManyAsync` and `SetManyAsync` which significantly improve the performance of **batch operations**. **Example: Store Book names and prices in the cache** @@ -167,7 +167,7 @@ namespace MyProject ```` * This sample service uses the `GetOrAddAsync()` method to get a book item from the cache. -* Since cache explicitly implemented as using `Guid` as cache key, `Guid` value passed to `_cache_GetOrAddAsync()` method. +* Since the cache is explicitly implemented as using `Guid` as the cache key, the `Guid` value is passed to the `_cache_GetOrAddAsync()` method. #### Complex Types as the Cache Key @@ -228,29 +228,29 @@ Configure(options => * `HideErrors` (`bool`, default: `true`): Enables/disables hiding the errors on writing/reading values from the cache server. * `KeyPrefix` (`string`, default: `null`): If your cache server is shared by multiple applications, you can set a prefix for the cache keys for your application. In this case, different applications can not overwrite each other's cache items. -* `GlobalCacheEntryOptions` (`DistributedCacheEntryOptions`): Used to set default distributed cache options (like `AbsoluteExpiration` and `SlidingExpiration`) used when you don't specify the options while saving cache items. Default value uses the `SlidingExpiration` as 20 minutes. +* `GlobalCacheEntryOptions` (`DistributedCacheEntryOptions`): Used to set default distributed cache options (like `AbsoluteExpiration` and `SlidingExpiration`) used when you don't specify the options while saving cache items. The default value uses the `SlidingExpiration` as 20 minutes. ## Error Handling -When you design a cache for your objects, you typically try to get the value from cache first. If not found in the cache, you query the object from the **original source**. It may be located in a **database** or may require to perform an HTTP call to a remote server. +When you design a cache for your objects, you typically try to get the value from the cache first. If not found in the cache, you query the object from the **original source**. It may be located in a **database** or may require an HTTP call to a remote server to be performed. -In most cases, you want to **tolerate the cache errors**; If you get error from the cache server you don't want to cancel the operation. Instead, you silently hide (and log) the error and **query from the original source**. This is what the ABP does by default. +In most cases, you want to **tolerate the cache errors**; If you get an error from the cache server, you don't want to cancel the operation. Instead, you silently hide (and log) the error and **query from the original source**. This is what the ABP does by default. ABP's Distributed Cache [handle](./exception-handling.md), log and hide errors by default. There is an option to change this globally (see the options below). -In addition, all of the `IDistributedCache` (and `IDistributedCache`) methods have an optional `hideErrors` parameter, which is `null` by default. The global value is used if this parameter left as `null`, otherwise you can decide to hide or throw the exceptions for individual method calls. +In addition, all of the `IDistributedCache` (and `IDistributedCache`) methods have an optional `hideErrors` parameter, which is `null` by default. The global value is used if this parameter is left as `null`; otherwise, you can decide to hide or throw the exceptions for individual method calls. ## Batch Operations -ABP's distributed cache interfaces provide methods to perform batch methods those improves the performance when you want to batch operation multiple cache items in a single method call. +ABP's distributed cache interfaces provide methods to perform batch operations that improve performance when you want to batch operation multiple cache items in a single method call. * `SetManyAsync` and `SetMany` methods can be used to set multiple values to the cache. * `GetManyAsync` and `GetMany` methods can be used to retrieve multiple values from the cache. * `GetOrAddManyAsync` and `GetOrAddMany` methods can be used to retrieve multiple values and set missing values from the cache -* `RefreshManyAsync` and `RefreshMany` methods can be used to resets the sliding expiration timeout of multiple values from the cache +* `RefreshManyAsync` and `RefreshMany` methods can be used to reset the sliding expiration timeout of multiple values from the cache * `RemoveManyAsync` and `RemoveMany` methods can be used to remove multiple values from the cache -> These are not standard methods of the ASP.NET Core caching. So, some providers may not support them. They are supported by the [ABP Redis Cache integration package](./redis-cache.md). If the provider doesn't support, it fallbacks to `SetAsync` and `GetAsync` ... methods (called once for each item). +> These are not standard methods of the ASP.NET Core caching. So, some providers may not support them. They are supported by the [ABP Redis Cache integration package](./redis-cache.md). If the provider doesn't support it, it falls back to `SetAsync` and `GetAsync` ... methods (called once for each item). ## Caching Entities @@ -266,17 +266,17 @@ It's designed as read-only and automatically invalidates a cached entity if the Distributed cache service provides an interesting feature. Assume that you've updated the price of a book in the database, then set the new price to the cache, so you can use the cached value later. What if you have an exception after setting the cache and you **rollback the transaction** that updates the price of the book? In this case, cache value will be incorrect. -`IDistributedCache<..>` methods gets an optional parameter, named `considerUow`, which is `false` by default. If you set it to `true`, then the changes you made for the cache are not actually applied to the real cache store, but associated with the current [unit of work](../architecture/domain-driven-design/unit-of-work.md). You get the value you set in the same unit of work, but the changes are applied **only if the current unit of work succeed**. +`IDistributedCache<..>` methods gets an optional parameter, named `considerUow`, which is `false` by default. If you set it to `true`, then the changes you made for the cache are not actually applied to the real cache store, but associated with the current [unit of work](../architecture/domain-driven-design/unit-of-work.md). You get the value you set in the same unit of work, but the changes are applied **only if the current unit of work succeeds**. ### IDistributedCacheSerializer -`IDistributedCacheSerializer` service is used to serialize and deserialize the cache items. Default implementation is the `Utf8JsonDistributedCacheSerializer` class that uses `IJsonSerializer` service to convert objects to [JSON](../../json-serialization.md) and vice verse. Then it uses UTC8 encoding to convert the JSON string to a byte array which is accepted by the distributed cache. +`IDistributedCacheSerializer` service is used to serialize and deserialize the cache items. The default implementation is the `Utf8JsonDistributedCacheSerializer` class that uses `IJsonSerializer` service to convert objects to [JSON](../../json-serialization.md) and vice verse. Then it uses UTC8 encoding to convert the JSON string to a byte array which is accepted by the distributed cache. -You can [replace](./dependency-injection.md) this service by your own implementation if you want to implement your own serialization logic. +You can [replace](./dependency-injection.md) this service with your own implementation if you want to implement your own serialization logic. ### IDistributedCacheKeyNormalizer -`IDistributedCacheKeyNormalizer` is implemented by the `DistributedCacheKeyNormalizer` class by default. It adds cache name, application cache prefix and current tenant id to the cache key. If you need a more advanced key normalization, you can [replace](./dependency-injection.md) this service by your own implementation. +`IDistributedCacheKeyNormalizer` is implemented by the `DistributedCacheKeyNormalizer` class by default. It adds the cache name, application cache prefix and current tenant ID to the cache key. If you need a more advanced key normalization, you can [replace](./dependency-injection.md) this service with your own implementation. ## See Also