add breaking change for shouldgeneratenewkey (#40284)

Author: gewarren

docs/core/compatibility/9.0.md

@@ -15,6 +15,12 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 >
 > This article is a work in progress. It's not a complete list of breaking changes in .NET 9. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%209%22%20or%20label:9.0.0)%20sort:created-desc).
 
+## ASP.NET Core
+
+| Title                                                                                    | Type of change      | Introduced version |
+|------------------------------------------------------------------------------------------|---------------------|--------------------|
+| [DefaultKeyResolution.ShouldGenerateNewKey has altered meaning](aspnet-core/9.0/key-resolution.md) | Behavioral change | Preview 3  |
+
 ## Core .NET libraries
 
 | Title                                                                                    | Type of change      | Introduced version |

docs/core/compatibility/aspnet-core/9.0/key-resolution.md

@@ -0,0 +1,41 @@
+---
+title: "Breaking change: DefaultKeyResolution.ShouldGenerateNewKey has altered meaning"
+description: Learn about the breaking change in ASP.NET Core 9.0 where DefaultKeyResolution.ShouldGenerateNewKey has a slightly altered meaning.
+ms.date: 04/01/2024
+---
+# DefaultKeyResolution.ShouldGenerateNewKey has altered meaning
+
+`DefaultKeyResolution.ShouldGenerateNewKey` no longer reflects whether the default key is close to its expiration time.
+
+## Version introduced
+
+ASP.NET Core 9.0 Preview 3
+
+## Previous behavior
+
+It was an undocumented, but consistent, feature of the API that `ShouldGenerateNewKey` was `true` if the default key was within two days (an oversimplification) of its expiration time. The amount of lead time was based on the polling interval of `ICacheableKeyRingProvider`, which was not something `IDefaultKeyResolver.ResolveDefaultKeyPolicy` should have depended upon (since, for example, alternative implementations would probably not be aware of these details).
+
+## New behavior
+
+Starting in .NET 9, if `ShouldGenerateNewKey` is `true`, it indicates that either there's no default key or that for some other policy reason (in a specialized implementation of `IDefaultKeyResolver`), a new key should be generated. The `ICacheableKeyRingProvider` makes its own decision about whether the expiration time is close enough to warrant generating a new key.
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change was made for two reasons:
+
+- To change the logic around key generation near expiration time.
+- To make it simpler to implement a custom `IDefaultKeyResolver`.
+
+## Recommended action
+
+If you have an `IDefaultKeyResolver` implementation that tries to replicate the expiry logic, you can remove that logic (however, leaving it is fine as well).
+
+If you were consuming `IDefaultKeyResolver` directly to determine whether expiration was pending, you can check the default key's `ExpirationDate` property directly.
+
+## Affected APIs
+
+- `Microsoft.AspNetCore.DataProtection.KeyManagement.Internal.DefaultKeyResolution.ShouldGenerateNewKey`

docs/core/compatibility/toc.yml

@@ -8,6 +8,10 @@ items:
     items:
     - name: Overview
       href: 9.0.md
+    - name: ASP.NET Core
+      items:
+      - name: DefaultKeyResolution.ShouldGenerateNewKey has altered meaning
+        href: aspnet-core/9.0/key-resolution.md
     - name: Core .NET libraries
       items:
       - name: Creating type of array of System.Void not allowed
@@ -928,6 +932,10 @@ items:
   items:
   - name: ASP.NET Core
     items:
+    - name: .NET 9
+      items:
+      - name: DefaultKeyResolution.ShouldGenerateNewKey has altered meaning
+        href: aspnet-core/9.0/key-resolution.md
     - name: .NET 8
       items:
       - name: ConcurrencyLimiterMiddleware is obsolete