Skip to content

Latest commit

 

History

History
138 lines (86 loc) · 6.54 KB

README.md

File metadata and controls

138 lines (86 loc) · 6.54 KB
Raw

Polly.Caching.Memory

This repo contains the MemoryCache plugin for the Polly Cache policy. The current version targets .NET Standard 1.3 (for .NET Core1.x), .NET Standard 2.0 (for .NET Core 2.x and .NET Framework 4.x), and .NET Standard 2.1 (for .NET Core 3.x).

NuGet version Build status Slack Status

What is Polly?

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 is a member of the .NET Foundation!

Keep up to date with new feature announcements, tips & tricks, and other news through www.thepollyproject.org

Installing Polly.Caching.Memory via NuGet

Install-Package Polly.Caching.Memory

Supported targets

Polly.Caching.Memory >= v3.0.2 supports .NET Standard 1.3, .NET Standard 2.0 and .NET Standard 2.1.

Polly.Caching.Memory >= v2.0 supports .NET Standard 1.3 and .NET Standard 2.0.

Polly.Caching.MemoryCache <v2.0 supports .NET4.0, .NET4.5 and .NetStandard 1.3

Dependency compatibility with Polly

Polly.Caching.Memory >=v3.0.2 requires:

Polly.Caching.Memory >=v3.0 amd <v3.0.2 requires:

Polly.Caching.Memory >=v2.0.1 and <v3 requires:

  • Polly >= v6.1.1 and <v7.

Polly.Caching.Memory v2.0.0 requires:

  • Polly >= v6.0.1 and <=v6.1.0.

Polly.Caching.MemoryCache v1.* requires:

  • Polly >=v5.9.0 and <v6.

How to use the Polly.Caching.Memory plugin

Example: Direct creation of CachePolicy (no DI)

// This approach creates a CachePolicy directly, with its own Microsoft.Extensions.Caching.Memory.MemoryCache instance:
Microsoft.Extensions.Caching.Memory.IMemoryCache memoryCache 
   = new Microsoft.Extensions.Caching.Memory.MemoryCache(new Microsoft.Extensions.Caching.Memory.MemoryCacheOptions());
Polly.Caching.Memory.MemoryCacheProvider memoryCacheProvider 
   = new Polly.Caching.Memory.MemoryCacheProvider(memoryCache);

// Create a Polly cache policy using that Polly.Caching.Memory.MemoryCacheProvider instance.
var cachePolicy = Policy.Cache(memoryCacheProvider, TimeSpan.FromMinutes(5));

Example: Configure CachePolicy via MemoryCacheProvider in StartUp, for DI

// (We pass a whole PolicyRegistry by dependency injection rather than the individual policy, 
// on the assumption the app will probably use multiple policies.)

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMemoryCache();
        services.AddSingleton<Polly.Caching.IAsyncCacheProvider, Polly.Caching.Memory.MemoryCacheProvider>();

        services.AddSingleton<Polly.Registry.IReadOnlyPolicyRegistry<string>, Polly.Registry.PolicyRegistry>((serviceProvider) =>
        {
            PolicyRegistry registry = new PolicyRegistry();
            registry.Add("myCachePolicy", 
                Policy.CacheAsync<HttpResponseMessage>(
                    serviceProvider
                        .GetRequiredService<IAsyncCacheProvider>()
                        .AsyncFor<HttpResponseMessage>(),
                    TimeSpan.FromMinutes(5)));
            return registry;
        });

        // ...
    }
}

// At the point of use, inject the policyRegistry and retrieve the policy:
// (magic string "myCachePolicy" only hard-coded here to keep the example simple) 
public MyController(IReadOnlyPolicyRegistry<string> policyRegistry)
{
    var _cachePolicy = policyRegistry.Get<IAsyncPolicy<HttpResponseMessage>>("myCachePolicy"); 
    // ...
}

For many more configuration options and usage examples of the main Polly CachePolicy, see the main Polly readme and deep doco on the Polly wiki.

Note

Polly.Caching.Memory.MemoryCacheProvider : ISyncCacheProvider, IAsyncCacheProvider is non-generic as the underlying Microsoft.Extensions.Caching.Memory.IMemoryCache is non-generic. However, when defining a generic Polly cache policy Policy.Cache/CacheAsync<TResult>(...), some overloads require a generic ISyncCacheProvider<TResult> or IAsyncCacheProvider<TResult>.

In this case, use the extensions methods MemoryCacheProvider.For<TResult>() or MemoryCacheProvider.AsyncFor<TResult>(), as shown in the ASP.NET Core example above, to obtain a generic ISyncCacheProvider<TResult> or IAsyncCacheProvider<TResult>.

Release notes

For details of changes by release see the change log.

Acknowledgements

Instructions for Contributing

Please check out our Wiki for contributing guidelines. We are following the excellent GitHub Flow process, and would like to make sure you have all of the information needed to be a world-class contributor!

Since Polly is part of the .NET Foundation, we ask our contributors to abide by their Code of Conduct.

Also, we've stood up a Slack channel for easier real-time discussion of ideas and the general direction of Polly as a whole. Be sure to join the conversation today!

License

Licensed under the terms of the New BSD License