Fix readme for v2.0
Update for new package name. Add DI configuration example. Add credit.
This commit is contained in:
reisenberger
Dylan Reisenberger
Родитель
d1ba9908b4
Коммит
1648086cbb
92
README.md
92
README.md
|
|
@ -1,74 +1,115 @@
|
|||
# Polly.Caching.IDistributedCache
|
||||
# Polly.Caching.Distributed
|
||||
|
||||
This repo contains the `Microsoft.Extensions.Caching.Distributed.IDistributedCache` plugin for the [Polly](https://github.com/App-vNext/Polly) [Cache policy](https://github.com/App-vNext/Polly/wiki/Cache). It targets .NET Standard 1.1.
|
||||
This repo contains the `Microsoft.Extensions.Caching.Distributed.IDistributedCache` provider for the [Polly](https://github.com/App-vNext/Polly) [Cache policy](https://github.com/App-vNext/Polly/wiki/Cache). The current version targets .NET Standard 1.1 and .NET Standard 2.0.
|
||||
|
||||
[](https://badge.fury.io/nu/Polly.Caching.IDistributedCache) [](https://ci.appveyor.com/project/joelhulen/polly-caching-IDistributedCache) [](http://www.pollytalk.org)
|
||||
[](https://badge.fury.io/nu/Polly.Caching.Distributed) [](https://ci.appveyor.com/project/joelhulen/polly-caching-Distributed) [](http://www.pollytalk.org)
|
||||
|
||||
## What is Polly?
|
||||
|
||||
[Polly](https://github.com/App-vNext/Polly) is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, Cache aside and Fallback in a fluent and thread-safe manner. Polly targets .NET 4.0, .NET 4.5 and .NET Standard 1.1.
|
||||
[Polly](https://github.com/App-vNext/Polly) is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, Cache aside and Fallback in a fluent and thread-safe manner. Polly targets .NET Standard 1.1 and .NET Standard 2.0.
|
||||
|
||||
Polly is a member of the [.NET Foundation](https://www.dotnetfoundation.org/about)!
|
||||
Polly is a member of the [.NET Foundation](https://www.dotnetfoundation.org/about).
|
||||
|
||||
**Keep up to date with new feature announcements, tips & tricks, and other news through [www.thepollyproject.org](http://www.thepollyproject.org)**
|
||||
|
||||
|
||||
|
||||
## What is Polly.Caching.IDistributedCache?
|
||||
## What is Polly.Caching.Distributed?
|
||||
|
||||
This project, Polly.Caching.IDistributedCache, allows you to use Polly's `CachePolicy` with [implementations of](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) .Net Standard's [`IDistributedCache`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.caching.distributed.idistributedcache).
|
||||
This project, Polly.Caching.Distributed, allows you to use Polly's `CachePolicy` with [implementations of](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) .Net Standard's [`IDistributedCache`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.caching.distributed.idistributedcache).
|
||||
|
||||
# Installing Polly.Caching.IDistributedCache via NuGet
|
||||
# Installing Polly.Caching.Distributed via NuGet
|
||||
|
||||
Install-Package Polly.Caching.IDistributedCache
|
||||
|
||||
You can install the Strongly Named version via:
|
||||
|
||||
Install-Package Polly.Caching.IDistributedCache-Signed
|
||||
Install-Package Polly.Caching.Distributed
|
||||
|
||||
# Supported targets
|
||||
|
||||
Polly.Caching.IDistributedCache supports .NetStandard 1.1 and above.
|
||||
Polly.Caching.Distributed supports .NET Standard 1.1 and .NET Standard 2.0.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Polly.Caching.IDistributedCache requires:
|
||||
Polly.Caching.IDistributedCache <v2.0 requires:
|
||||
|
||||
+ [Polly](nuget.org/packages/polly) v5.4.0 or above.
|
||||
+ [Microsoft.Extensions.Caching.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Abstractions/) v1.1.2 or above.
|
||||
|
||||
# How to use the Polly.Caching.IDistributedCache plugin
|
||||
Polly.Caching.Distributed >=v2.0 requires:
|
||||
|
||||
+ [Polly](nuget.org/packages/polly) v6.0.1 or above.
|
||||
+ [Microsoft.Extensions.Caching.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Abstractions/) v2.0.2 or above.
|
||||
|
||||
# How to use the Polly.Caching.Distributed plugin
|
||||
|
||||
These notes assume you are familiar with using the .Net Standard `IDistributedCache` implementations. For information, see: https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed . As described on that page, Microsoft provide a Redis implementation and an SQL server implementation for `IDistributedCache`.
|
||||
|
||||
Assuming you have an instance `IDistributedCache distributedCache` in hand (perhaps just configured and instantiated, perhaps provided to local code by Dependency Injection):
|
||||
|
||||
```csharp
|
||||
// Create a Polly cache policy for caching string results, using that `IDistributedCache` instance.
|
||||
var cachePolicy = Policy.Cache<string>(distributedCache.AsSyncCacheProvider<string>, TimeSpan.FromMinutes(5));
|
||||
|
||||
// Create a Polly cache policy for caching byte[] results, using that `IDistributedCache` instance.
|
||||
var cachePolicy = Policy.Cache<byte[]>(distributedCache.AsSyncCacheProvider<byte[]>, TimeSpan.FromMinutes(5));
|
||||
```csharp
|
||||
// Create a Polly cache policy for caching string results, using that IDistributedCache instance.
|
||||
var cachePolicy = Policy.Cache<string>(distributedCache.AsSyncCacheProvider<string>(), TimeSpan.FromMinutes(5));
|
||||
|
||||
// Create a Polly cache policy for caching byte[] results, using that IDistributedCache instance.
|
||||
var cachePolicy = Policy.Cache<byte[]>(distributedCache.AsSyncCacheProvider<byte[]>(), TimeSpan.FromMinutes(5));
|
||||
|
||||
// Or similarly for async executions returning string results:
|
||||
var cachePolicy = Policy.CacheAsync<string>(distributedCache.AsAsyncCacheProvider<string>, TimeSpan.FromMinutes(5));
|
||||
var cachePolicy = Policy.CacheAsync<string>(distributedCache.AsAsyncCacheProvider<string>(), TimeSpan.FromMinutes(5));
|
||||
|
||||
// Or similarly for async executions returning byte[] results:
|
||||
var cachePolicy = Policy.CacheAsync<byte[]>(distributedCache.AsAsyncCacheProvider<byte[]>, TimeSpan.FromMinutes(5));
|
||||
var cachePolicy = Policy.CacheAsync<byte[]>(distributedCache.AsAsyncCacheProvider<byte[]>(), TimeSpan.FromMinutes(5));
|
||||
|
||||
// You can also use ASP.NET Core's DistributedCacheEntryOptions for specifying cache item time-to-live, as shown below.
|
||||
// All time-to-live functionality represented by DistributedCacheEntryOptions is supported.
|
||||
DistributedCacheEntryOptions entryOptions = // ...
|
||||
var cachePolicy = Policy.CacheAsync<byte[]>(distributedCache.AsAsyncCacheProvider<byte[]>, entryOptions.AsTtlStrategy());
|
||||
var cachePolicy = Policy.CacheAsync<byte[]>(distributedCache.AsAsyncCacheProvider<byte[]>(), entryOptions.AsTtlStrategy());
|
||||
|
||||
|
||||
```
|
||||
|
||||
Configuration via DI in ASPNET Core:
|
||||
|
||||
```csharp
|
||||
// In this example we choose to pass a whole PolicyRegistry by dependency injection rather than the individual policy, on the assumption the webapp will probably use multiple policies across the app.
|
||||
|
||||
// For example:
|
||||
public class Startup
|
||||
{
|
||||
public void ConfigureServices(IServiceCollection services)
|
||||
{
|
||||
services.AddDistributedRedisCache(options =>
|
||||
{
|
||||
options.Configuration = "localhost"; // or whatever
|
||||
options.InstanceName = "SampleInstance";
|
||||
});
|
||||
|
||||
services.AddSingleton<Polly.Caching.IAsyncCacheProvider<string>>(serviceProvider => serviceProvider.GetRequiredService<IDistributedCache>().AsAsyncCacheProvider<string>());
|
||||
|
||||
services.AddSingleton<Polly.Registry.IPolicyRegistry<string>, Polly.Registry.PolicyRegistry>((serviceProvider) =>
|
||||
{
|
||||
PolicyRegistry registry = new PolicyRegistry();
|
||||
registry.Add("myCachePolicy", Policy.CacheAsync<string>(serviceProvider.GetRequiredService<IAsyncCacheProvider<string>>(), TimeSpan.FromMinutes(5)));
|
||||
|
||||
return registry;
|
||||
});
|
||||
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
// In a controller, inject the policyRegistry and retrieve the policy:
|
||||
// (magic string "myCachePolicy" hard-coded here only to keep the example simple)
|
||||
public MyController(IPolicyRegistry<string> policyRegistry)
|
||||
{
|
||||
var _cachePolicy = policyRegistry.Get<IAsyncPolicy<HttpResponseMessage>>("myCachePolicy");
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Usage:
|
||||
|
||||
```csharp
|
||||
string productId = // ... from somewhere
|
||||
string productDescription = await cachePolicy.ExecuteAsync(() => getProductDescription(productId),
|
||||
string productDetails = await cachePolicy.ExecuteAsync(() => getProductDetails(productId),
|
||||
new Context(productId) // productId will also be the cache key used in this execution.
|
||||
);
|
||||
```
|
||||
|
|
@ -86,6 +127,7 @@ For details of changes by release see the [change log](CHANGELOG.md).
|
|||
|
||||
* [@seanfarrow](https://github.com/seanfarrow) and [@reisenberger](https://github.com/reisenberger) - Initial caching architecture in the main Polly repo
|
||||
* [@reisenberger](https://github.com/reisenberger) - `IDistributedCache` implementation
|
||||
* [@seanfarrow](https://github.com/seanfarrow) - v2.0 update to Signed packages only to correspond with Polly v6.0.1
|
||||
|
||||
# Instructions for Contributing
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче