[API Proposal]: Reconciling base classes and interfaces in Microsoft.Extensions

[terrajobst]

Background and motivation

We keep getting asked to add functionality to features in Microsoft.Extensions, such as:

• Add .Clear() method to MemoryCache #45593
• [MemoryCache] Add possibility to disable linked cache entries #45592

We can't add methods to interfaces, so we're adding more and more APIs to the classes only. We should make a decision on what to do with the interfaces. My proposal is hide and obsolete.

API Proposal

TBD

API Usage

TBD

Risks

No response

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[ghost]

Tagging subscribers to this area: @eerhardt, @maryamariyan
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

We keep getting asked to add functionality to features in Microsoft.Extensions, such as:

• Add .Clear() method to MemoryCache #45593
• [MemoryCache] Add possibility to disable linked cache entries #45592

We can't add methods to interfaces, so we're adding more and more APIs to the classes only. We should make a decision on what to do with the interfaces. My proposal is hide and obsolete.

API Proposal

TBD

API Usage

TBD

Risks

No response

Author:	terrajobst
Assignees:	-
Labels:	api-suggestion, area-Extensions-Primitives
Milestone:	7.0.0

[eerhardt]

cc @davidfowl @Tratcher

[Tratcher]

IMemoryCache is used in many public TagHelper APIs like:
https://github.com/dotnet/aspnetcore/blob/8b30d862de6c9146f466061d51aa3f1414ee2337/src/Mvc/Mvc.TagHelpers/src/DistributedCacheTagHelper.cs#L44-L46

Most other ASP.NET uses seem to be internal.

[eerhardt]

My proposal is hide and obsolete.

I can see 2 high-level approaches to fixing this.

1. Embrace the interfaces and use DIMs

Taking #45593 as a case study, it would mean this change:

namespace Microsoft.Extensions.Caching.Memory
{
    public interface IMemoryCache
    {
+#if NET6_OR_GREATER
+        void Clear() { throw new NotImplementedException(); }
+#endif
    }

    public class MemoryCache : IMemoryCache
    {
+        public void Clear();
    }
}

The advantages:

• Consumers don't need to rewrite their code away from the interfaces.
• We would be dogfooding the DIM feature, which was implemented exactly for this scenario

Disadvantages:

• People consuming the abstraction (IMemoryCache) on older TFMs (i.e. netstandard2.0) wouldn't be able to use the new members
• Risk that we hit issues with DIMs, as we don't have much experience since we haven't used them

2. Deprecate the interfaces and replace with base classes

Again, using #45593 as a case study:

namespace Microsoft.Extensions.Caching.Memory
{
+   [Obsolete("Use MemoryCacheBase instead")]
    public interface IMemoryCache
    {
...
    }

+    public abstract class MemoryCacheBase
+    {
+        public virtual void Clear() { throw new NotImplementedException(); }
+    }

-   public class MemoryCache : IMemoryCache
+   public class MemoryCache : MemoryCacheBase, IMemoryCache
    {
    }

(Note: we wouldn't strictly need to obsolete the interfaces. So we have options 2.a - obsolete interfaces and 2.b - don't obsolete the interfaces.)

The advantages/disadvantages are basically flipped from Option 1 above.

Thoughts

Following Option 2 is what we would traditionally do. It is the "safer" and more traveled road. Do we think Option 1 has enough advantages to try to blaze a new trail here?

cc @davidfowl @Tratcher @halter73

[Tratcher]

Option 2 would cause significant public API breaks up stack and is not DI friendly. Option 1 is much less invasive if you can make it work. If you find Option 1 to be insufficient or problematic after one or more releases, you can still fall back to Option 2.

[eerhardt]

and is not DI friendly.

Can you elaborate? Why is an abstract base class "not DI friendly" vs. an interface?

[Tratcher]

and is not DI friendly.

Can you elaborate? Why is an abstract base class "not DI friendly" vs. an interface?

I'd overlooked MemoryCacheBase, yes that would work for DI.

I still think DIMs are better for being less disruptive to the ecosystem. We've used them successfully in aspnetcore, though we didn't have the netstandard limitation.

[fowl2]

There's also the possibility of:

namespace Microsoft.Extensions.Caching.Memory;

+  public interface IMemoryCache2 : IMemoryCache
+  {
+      void Clear();
+  }

-  public class MemoryCache : IMemoryCache
+  public class MemoryCache : IMemoryCache, IMemoryCache2

With the option to obsolete IMemoryCache. A little inelegant - having to register multiple interfaces in DI, but backwards compatible.