MemoryCache breaking change

docs/core/compatibility/7.0.md

@@ -47,6 +47,7 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff
 | [Library support for older frameworks](core-libraries/7.0/old-framework-support.md) | ❌ | ❌ | Preview 1 |
 | [Maximum precision for numeric format strings](core-libraries/7.0/max-precision-numeric-format-strings.md) | ❌ | ✔️ | RC 1 |
 | [SerializationFormat.Binary is obsolete](core-libraries/7.0/serializationformat-binary.md) | ❌ | ❌ | Preview 2 |
+| [Tracking linked cache entries](core-libraries/7.0/memorycache-tracking.md) | ❌ | ✔️ | Preview 1 |
 | [Validate CompressionLevel for BrotliStream](core-libraries/7.0/compressionlevel-validation.md) | ❌ | ✔️ | Preview 1 |
 
 ## Cryptography

docs/core/compatibility/core-libraries/7.0/memorycache-tracking.md

@@ -0,0 +1,61 @@
+---
+title: "Breaking change: Tracking linked cache entries"
+description: Learn about the .NET 7 breaking change in .NET where MemoryCache no longer tracks linked cache entries by default.
+ms.date: 10/13/2022
+---
+# Tracking linked cache entries
+
+<xref:System.Runtime.Caching.MemoryCache> tracks linked cache entries so that options are propagated. In the following example, the `expirationToken` added for `child` is also applied to `parent`:
+
+```csharp
+using (var parent = cache.CreateEntry(key))
+{
+    parent.SetValue(obj);
+
+    using (var child = cache.CreateEntry(key1))
+    {
+        child.SetValue(obj);
+        child.AddExpirationToken(expirationToken);
+    }
+}
+```
+
+For performance reasons, .NET 7 no longer tracks linked cache entries by default. However, you can enable tracking using a new option.
+
+## Version introduced
+
+.NET 7 Preview 1
+
+## Previous behavior
+
+Prior to .NET 7, <xref:System.Runtime.Caching.MemoryCache> tracked linked cache entries to allow for options to be propagated. The tracking could not be disabled.
+
+## New behavior
+
+Starting in .NET 7, <xref:System.Runtime.Caching.MemoryCache> does not track linked cache entries, by default. The <xref:Microsoft.Extensions.Caching.Memory.MemoryCacheOptions.TrackLinkedCacheEntries?displayProperty=nameWithType> option was added so you can control whether linked cache entries are tracked or not.
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility).
+
+## Reason for change
+
+This change was introduced to improve performance. Tracking internally uses <xref:System.Threading.AsyncLocal%601>, which is expensive and adds non-trivial overhead.
+
+## Recommended action
+
+If you want <xref:System.Runtime.Caching.MemoryCache> to continue tracking linked cache entries so options can be propagated, set <xref:Microsoft.Extensions.Caching.Memory.MemoryCacheOptions.TrackLinkedCacheEntries?displayProperty=nameWithType> to `true`.
+
+```csharp
+var options = new MemoryCacheOptions
+{
+    TrackLinkedCacheEntries = true
+};
+
+var cache = new MemoryCache(options);
+```
+
+## Affected APIs
+
+- <xref:System.Runtime.Caching.MemoryCache?displayProperty=fullName>
+- <xref:Microsoft.Extensions.Caching.Memory.MemoryCacheOptions?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -75,6 +75,8 @@ items:
           href: core-libraries/7.0/reflection-invoke-exceptions.md
         - name: SerializationFormat.Binary is obsolete
           href: core-libraries/7.0/serializationformat-binary.md
+        - name: Tracking linked cache entries
+          href: core-libraries/7.0/memorycache-tracking.md
         - name: Validate CompressionLevel for BrotliStream
           href: core-libraries/7.0/compressionlevel-validation.md
       - name: Cryptography
@@ -849,6 +851,8 @@ items:
           href: core-libraries/7.0/reflection-invoke-exceptions.md
         - name: SerializationFormat.Binary is obsolete
           href: core-libraries/7.0/serializationformat-binary.md
+        - name: Tracking linked cache entries
+          href: core-libraries/7.0/memorycache-tracking.md
         - name: Validate CompressionLevel for BrotliStream
           href: core-libraries/7.0/compressionlevel-validation.md
       - name: .NET 6