Merge pull request #7 from reisenberger/master

Target Polly v5.4; add RC doco

Author: reisenberger

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Polly.Caching.MemoryCache change log
 
+## 1.0-RC
+
+- Upgrade to Polly v5.4.0
+- Correctly state RC dependency (Polly v5.4.0)
+
 ## 0.2-beta
 
 - Beta implementation

GitVersionConfig.yaml

@@ -1 +1 @@
-next-version: 0.2.0-beta
+next-version: 1.0.0

README.md

@@ -10,7 +10,7 @@ Polly is a member of the [.NET Foundation](https://www.dotnetfoundation.org/abou
 
 **Keep up to date with new feature announcements, tips & tricks, and other news through [www.thepollyproject.org](http://www.thepollyproject.org)**
 
-# Installing via NuGet
+# Installing Polly.Caching.MemoryCache via NuGet
 
     Install-Package Polly.Caching.MemoryCache
 
@@ -24,16 +24,66 @@ Polly.Caching.MemoryCache supports .NET4.0, .NET4.5 and .NetStandard 1.3.
 
 ## Dependencies
 
-[To come]
+Polly.Caching.MemoryCache works with Polly v5.4.0 and above.
 
 # How to use the Polly.Caching.MemoryCache plugin
 
-[To come]
+```csharp
+// (1a): Create a MemoryCacheProvider instance in the .NET Framework, using the Polly.Caching.MemoryCache nuget package.
+// (full namespaces and types only shown here for disambiguation)
+Polly.Caching.MemoryCache.MemoryCacheProvider memoryCacheProvider 
+   = new Polly.Caching.MemoryCache.MemoryCacheProvider(System.Runtime.Caching.MemoryCache.Default);
 
+// Or (1b): Create a MemoryCacheProvider instance in .NET Core / .NET Standard.
+// (full namespaces and types only shown here for disambiguation)
+// NB Only if you want to create your 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.MemoryCache.MemoryCacheProvider memoryCacheProvider 
+   = new Polly.Caching.MemoryCache.MemoryCacheProvider(memoryCache);
 
-## How to use the Polly Cache policy
+// (2) Create a Polly cache policy using that Polly.Caching.MemoryCache.MemoryCacheProvider instance.
+var cachePolicy = Policy.Cache(memoryCacheProvider, TimeSpan.FromMinutes(5));
 
-See the [To be expanded] [Polly readme](https://github.com/App-vNext/Polly/wiki/Cache) or [To be expanded] [deep doco on the Polly wiki](https://github.com/App-vNext/Polly/wiki/Cache).
+
+
+// Or (1c): Configure by dependency injection within ASP.NET Core
+// See https://docs.microsoft.com/en-us/aspnet/core/performance/caching/memory
+// and https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection#registering-your-own-services
+
+// (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.AddMemoryCache();
+        services.AddSingleton<Polly.Registry.IPolicyRegistry<string>, Polly.Registry.PolicyRegistry>();
+        // ...
+    }
+
+    public void Configure(..., IPolicyRegistry<string> policyRegistry, IMemoryCache memoryCache)
+    {
+        Polly.Caching.MemoryCache.MemoryCacheProvider memoryCacheProvider 
+            = new Polly.Caching.MemoryCache.MemoryCacheProvider(memoryCache);
+        var cachePolicy = Policy.Cache(memoryCacheProvider, TimeSpan.FromMinutes(5));
+        policyRegistry.Add("myCachePolicy", cachePolicy);
+        // ...
+    }
+}
+
+// In a controller, inject the policyRegistry and retrieve the policy:
+// (magic string "myCachePolicy" only hard-coded here to keep the example simple!) 
+public MyController(IPolicyRegistry<string> policyRegistry)
+{
+    _cachePolicy = policyRegistry["myCachePolicy"];
+    // ...
+}
+
+```
+
+For many more configuration options and usage examples of the main Polly `CachePolicy`, see the [main Polly readme](https://github.com/App-vNext/Polly/wiki/Cache) and [deep doco on the Polly wiki](https://github.com/App-vNext/Polly/wiki/Cache).
 
 
 # Release notes
@@ -43,6 +93,7 @@ For details of changes by release see the [change log](CHANGELOG.md).
 
 # Acknowledgements
 
+* [@reisenberger](https://github.com/reisenberger) - MemoryCache implementation
 * [@seanfarrow](https://github.com/seanfarrow) and [@reisenberger](https://github.com/reisenberger) - Initial caching architecture in the main Polly repo
 * [@kesmy](https://github.com/kesmy) - original structuring of the build for msbuild15, in the main Polly repo
 

build.cake

@@ -135,7 +135,7 @@ Task("__UpdateDotNetStandardAssemblyVersionNumber")
     // This build Task can be removed when GitVersionTask supports .Net Standard assemblies.
     var assemblySemVer = gitVersionOutput["AssemblySemVer"].ToString();
     Information("Updating NetStandard1.3 AssemblyVersion to {0}", assemblySemVer);
-    var replacedFiles = ReplaceRegexInFiles("./src/Polly.NetStandard13/Properties/AssemblyInfo.cs", "AssemblyVersion[(]\".*\"[)]", "AssemblyVersion(\"" + assemblySemVer +"\")");
+    var replacedFiles = ReplaceRegexInFiles("./src/Polly.Caching.MemoryCache.NetStandard13/Properties/AssemblyInfo.cs", "AssemblyVersion[(]\".*\"[)]", "AssemblyVersion(\"" + assemblySemVer +"\")");
     if (!replacedFiles.Any())
     {
         Information("NetStandard1.3 AssemblyVersion could not be updated.");

src/Polly.Caching.MemoryCache.NetStandard13/Properties/AssemblyInfo.cs

@@ -3,7 +3,7 @@
 using System.Runtime.CompilerServices;
 
 [assembly: AssemblyTitle("Polly.Caching.MemoryCache")]
-[assembly: AssemblyVersion("0.2.0.0")]
+[assembly: AssemblyVersion("1.0.0.0")]
 [assembly: CLSCompliant(false)] // Because Microsoft.Extensions.Caching.Memory.MemoryCache, on which Polly.Caching.MemoryCache.NetStandard13 depends, is not CLSCompliant.
 
 [assembly: InternalsVisibleTo("Polly.Caching.MemoryCache.NetStandard13.Specs")]

src/Polly.Caching.MemoryCache.nuspec

@@ -13,6 +13,11 @@
     <tags>Exception Handling Resilience Transient Fault Policy Cache Aside Cache-aside</tags>
     <copyright>Copyright © 2017, App vNext</copyright>
     <releaseNotes>
+     ## 1.0-RC
+
+     - Upgrade to Polly v5.4.0
+     - Correctly state RC dependency (Polly v5.4.0)
+
      ## 0.2-alpha
 
      - Upgrade to msbuild15 build process
@@ -24,18 +29,18 @@
    </releaseNotes>
     <dependencies>
       <group targetFramework="net45">
-        <dependency id="Polly" version="5.3.1" />
+        <dependency id="Polly" version="5.4.0" />
       </group>
       <group targetFramework="netstandard1.3">
         <dependency id="NETStandard.Library" version="1.6.1" />
-        <dependency id="Polly" version="5.3.1" />
+        <dependency id="Polly" version="5.4.0" />
       </group>
       <group targetFramework="net40">
         <dependency id="Microsoft.Bcl.Async" version="1.0.168" />
         <dependency id="Microsoft.Bcl" version="1.1.10" />
         <dependency id="Microsoft.Bcl.Build" version="1.0.21" />
         <dependency id="Nito.AsyncEx" version="3.0.1" />
-        <dependency id="Polly.Net40Async" version="5.3.1" />
+        <dependency id="Polly.Net40Async" version="5.4.0" />
       </group>
     </dependencies>
   </metadata>