A simple and elegant yet powerful HTTP client cache for .NET
C#
Switch branches/tags
Nothing to show
Clone or download
Latest commit 5cee38b Jul 14, 2017

README.md

Cashew

Cashew is a .NET library for caching responses easily with an HttpClient through an API that is simple and elegant yet powerful. There's support out of the box for the awesome CacheManager via the Cashew.Adapters.CacheManager package. Its aim is to focus on the HTTP part of caching and not worrying about how stuff is stored, meaning no half-arsed cache implementations!

Cashew targets .NET 4.5 and .NET Standard 1.1 (.NET Core, Mono, Xamarin.iOS, Xamarin.Android, UWP and more) meaning it can be used on all sorts of devices.

Build Status NuGet

Cashew-logo

Installation

The latest versions of the packages are available on NuGet. To install, run the following command if you want to roll your own cache:

PM> Install-Package Cashew

or the command below if you want to utilise the power of CacheManager

PM> Install-Package Cashew.Adapters.CacheManager

Features

General features

  • Extremely easy to use, all it takes is one line to configure the whole thing!
  • Simple but powerful API that allows customisation
  • ETag support
  • Vary Header support

Cache stores

Type Out of the box?
Dictionary Yes*
System.Runtime.Caching.MemoryCache Yes*
Microsoft.Extensions.Caching.Memory Yes*
Redis Yes*
Memcached Yes*
Couchbase Yes*
Custom No, but it's super easy to implement your own.

*Provided that you use Cashew.Adapters.CacheManager

HTTP Cache-Control Headers

Header Aka
max-age "I don't want cached responses older than this"
s-maxage "I don't want cached responses older than this"
max-stale "Stale responses are OK for this long"
min-fresh "The response has to still be fresh for at least this long"
no-cache "You must validate the cached response with the server
no-store "DO NOT CACHE THIS OR I WILL MAKE YOUR LIFE MISERABLE!"
only-if-cached "I only want a response if it's cached"
must-revalidate "You MUST revalidate stale responses"
proxy-revalidate "You MUST revalidate stale responses"

Customisation

Cashew provides a lot of customisation opportunities for its users. The most important ones are listed below:

Feature Quickstart In-depth
Use any cache store Link Wiki
Decide how cache keys are created Link Wiki
Decide which status codes are cacheable Link Wiki

Usage

For more in-depth information on how to use Cashew, please refer to our wiki.

Configuring HttpClient

//All it takes is one line to configure the whole thing!
var httpClient = new HttpClient(new HttpCachingHandler(cache, new HttpStandardKeyStrategy(cache)));

Use any cache store

//We feel like caching the HTTP responses in an SQL store (for some reason) and have therefore created our own SqlCache
var sqlCache = new SqlCache();

//We pass our newly created sql cache in the constructor and watch the magic happen
var httpCachingHandler = new HttpCachingHandler(sqlCache, keyStrategy);

Decide how cache keys are created

//We have created our own strategy that creates keys out of request URI:s
var uriKeyStrategy = new RequestUriKeyStrategy();

//We pass our newly created key strategy in the constructor and watch the magic happen!
var httpCachingHandler = new HttpCachingHandler(memoryCache, uriKeyStrategy);

Decide how query strings are handled

//The default implementation of ICacheKeyStrategy is HttpStandardKeyStrategy. You can configure it to handle query strings in two ways.

//Using CacheKeySetting.Standard will result in a different cache key each time the query string changes
var queryStringStrategy = new HttpStandardKeyStrategy(cache, CacheKeySetting.Standard);

//Using CacheKeySetting.IgnoreQueryString will result in the same key even if the query string changes.
var uriStrategy = new HttpStandardKeyStrategy(cache, CacheKeySetting.IgnoreQueryString);

Cacheable status codes

//We only want to cache responses with status 200
httpCachingHandler.CacheableStatusCodes = new[] { HttpStatusCode.OK };

Contributing

Please refer to our guidelines on contributing.