[API Proposal]: Add ObsoleteAttribute.BinaryCompatOnly

[jaredpar]

Background and motivation

The .NET Runtime goes to great lengths to have binary compatibility between releases. That dramatically lowers the cost of version to version updates and provides a smooth update experience for customers. It also means that API decisions are forever, once shipped we are stuck with an API.

This is true even as the language and ecosystem evolves and better patterns emerge that we'd like to promote. For example consider the CallerArgumentExpression feature in C#. Given this feature it's possible to have a better default experience for Debug.Assert by defining the method as such:

public static class Debug
{
    public static void Assert(bool condition, [CallerArgumentExpression("condition")] string message = null);
}

This though is a bit of a non-starter. Due to the rules of C# this method will never be bound to because it will always prefer Debug.Assert(string). Changing the overload rules that make this determination is a bit of a non-starter because it would result in sweeping changes across the ecosystem. Where as the desired impact is much smaller: stop using Debug.Assert(string) for languages that support CallerArgumentExpression.

This desire to remove one method from source and replace with a highly compatible alternative has come up several times over the last few releases:

• Several interactions around CallerArgumentExpressionAttribute
• Desire for the CallerIdentityAttribute
• The C# 10 improved lambda overload resolution support revealed several regrettable overloads in ASP.NET that we wished could be replaced by more modern versions.

The proposal is to provide a mechanism by which APIs can be marked as "for binary compatibility only". The member will not be considered for source compilation purposes by languages.

This can be done by extending our existing ObsoleteAttribute to have a new property: BinaryCompatOnly.

Note that this is substantially different than ObsoleteAttribute.IsError. That in no way changes what members a language will bind to. Instead it is only considered after a language has gone through member look up, overload resolution, etc ... At the moment the final decision on a member is made only then does the language look at ObsoleteAttribute and determine a diagnostic should be emitted.

This proposal removes the API at a much lower level. It asks languages to not even consider the member during compilation. For all intents and purposes the member should not be imported from metadata except for what is necessary to ensure a type definition is sound (for example that it implements all interface members).

API Proposal

public sealed class ObsoleteAttribute : Attribute
{
    public ObsoleteAttribute(string? message, bool error, bool binaryCompatOnly)
    {
        Message = message;
        IsError = error;
        BinaryCompatOnly = binaryCompatOnly;
    }

    public bool BinaryCompatOnly { get; set; }
}

API Usage

public static class Debug
{

    [Obsolete(BinaryCompatOnly = true)]
    public static void Assert(bool condition);

    public static void Assert(bool condition, [CallerArgumentExpression("condition")] string message = null);
}

Alternative Designs

Leverage reference assemblies

An alternative design is to change the reference assembly generation tool such that these APIs are just not included. That would have roughly the same impact as this change: on upgrade only the new APIs would be available for compilation hence they would win out.

The downside of this approach is that it's going to be less friendly to languages other than C#, F# and VB. As detailed in CallerIdentityAttribute proposal it's likely that the alternative source methods provided are going to rely on new features. Those features are less likely to be present in other languages and hence is more likely to result in compilation errors on upgrade.

This is not the case with the proposal to add ObsoleteAttribute.BinaryCompateOnly. Languages have to make a change to recognize that attribute. Languages can then weigh the cost of supporting the features most relied on by BinaryCompateOnly and take them as a single feature in a release.

Alternate attribute

It's reasonable to see this as expanding ObsoleteAttribute beyond it's intended scope and instead a new attribute should be considered like BinaryCompateOnlyAttribute

Risks

Method Group Support

The motivating cases around this tend to be about overload resolution. Essentially an existing API is always preferred due to C#, VB, F# overload resolution rules and that is preventing us from adding a new, better API. The [Obsolete(BinaryCompatOnly = true)] in combination with a new overload, which is largely source compatible, will minimize upgrade experience pain to a large degree for method invocations.

// Compiles today, compiles tomorrow just to a diff overload
Debug.Assert(SomeCondition);

This will not fix method group conversions though as they are focused on the signature of the method

// Compiles today, fails tomorrow
// Note: presence of [Conditional] makes this fail today but the general method group problem exists
Action<bool> action = Debug.Assert;

This is likely a minority case compared to method invocation though and may be an acceptable trade off for forward progress in the platform.

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.

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The .NET Runtime goes to great lengths to have binary compatibility between releases. That dramatically lowers the cost of version to version updates and provides a smooth update experience for customers. It also means that API decisions are forever, once shipped we are stuck with an API.

This is true even as the language and ecosystem evolves and better patterns emerge that we'd like to promote. For example consider the CallerArgumentExpression feature in C#. Given this feature it's possible to have a better default experience for Debug.Assert by defining the method as such:

public static class Debug
{
    public static void Assert(bool condition, [CallerArgumentExpression("condition")] string message = null);
}

This though is a bit of a non-starter. Due to the rules of C# this method will never be bound to because it will always prefer Debug.Assert(string). Changing the overload rules that make this determination is a bit of a non-starter because it would result in sweeping changes across the ecosystem. Where as the desired impact is much smaller: stop using Debug.Assert(string) for languages that support CallerArgumentExpression.

This desire to remove one method from source and replace with a highly compatible alternative has come up several times over the last few releases:

• Several interactions around CallerArgumentExpressionAttribute
• Desire for the CallerIdentityAttribute
• The C# 10 improved lambda overload resolution support revealed several regrettable overloads in ASP.NET that we wished could be replaced by more modern versions.

The proposal is to provide a mechanism by which APIs can be marked as "for binary compatibility only". The member will not be considered for source compilation purposes by languages.

This can be done by extending our existing ObsoleteAttribute to have a new property: BinaryCompatOnly.

Note that this is substantially different than ObsoleteAttribute.IsError. That in no way changes what members a language will bind to. Instead it is only considered after a language has gone through member look up, overload resolution, etc ... At the moment the final decision on a member is made only then does the language look at ObsoleteAttribute and determine a diagnostic should be emitted.

This proposal removes the API at a much lower level. It asks languages to not even consider the member during compilation. For all intents and purposes the member should not be imported from metadata except for what is necessary to ensure a type definition is sound (for example that it implements all interface members).

API Proposal

public sealed class ObsoleteAttribute : Attribute
{
    public ObsoleteAttribute(string? message, bool error, bool binaryCompatOnly)
    {
        Message = message;
        IsError = error;
        BinaryCompatOnly = binaryCompatOnly;
    }

    public bool BinaryCompatOnly { get; set; }
}

API Usage

public static class Debug
{

    [Obsolete(BinaryCompatOnly = true)]
    public static void Assert(bool condition);

    public static void Assert(bool condition, [CallerArgumentExpression("condition")] string message = null);
}

Alternative Designs

Leverage reference assemblies

An alternative design is to change the reference assembly generation tool such that these APIs are just not included. That would have roughly the same impact as this change: on upgrade only the new APIs would be available for compilation hence they would win out.

The downside of this approach is that it's going to be less friendly to languages other than C#, F# and VB. As detailed in CallerIdentityAttribute proposal it's likely that the alternative source methods provided are going to rely on new features. Those features are less likely to be present in other languages and hence is more likely to result in compilation errors on upgrade.

This is not the case with the proposal to add ObsoleteAttribute.BinaryCompateOnly. Languages have to make a change to recognize that attribute. Languages can then weigh the cost of supporting the features most relied on by BinaryCompateOnly and take them as a single feature in a release.

Alternate attribute

It's reasonable to see this as expanding ObsoleteAttribute beyond it's intended scope and instead a new attribute should be considered like BinaryCompateOnlyAttribute

Risks

Method Group Support

The motivating cases around this tend to be about overload resolution. Essentially an existing API is always preferred due to C#, VB, F# overload resolution rules and that is preventing us from adding a new, better API. The [Obsolete(BinaryCompatOnly = true)] in combination with a new overload, which is largely source compatible, will minimize upgrade experience pain to a large degree for method invocations.

// Compiles today, compiles tomorrow just to a diff overload
Debug.Assert(SomeCondition);

This will not fix method group conversions though as they are focused on the signature of the method

// Compiles today, fails tomorrow
Action<string> action = Debug.Assert;

This is likely a minority case compared to method invocation though and may be an acceptable trade off for forward progress in the platform.

Author:	jaredpar
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[KalleOlaviNiemitalo]

// Compiles today, fails tomorrow
Action<string> action = Debug.Assert;

I think you mean Action<bool>, but that fails with error CS1618: Cannot create delegate with 'Debug.Assert(bool)' because it or a method it overrides has a Conditional attribute

Because BinaryCompatOnly would affect overload resolution, it would need a C# specification change and should not affect C# language versions that have already been standardized.

[jaredpar]

I think you mean Action, but that fails with error CS1618: Cannot create delegate with 'Debug.Assert(bool)' because it or a method it overrides has a Conditional attribute

Correct that should've been Action<bool> (updated). Forgot that Conditional impacts the method group conversion here. So that specific case is broken today. The general scenario though of method groups not having a viable source alternate remains true though.

Because BinaryCompatOnly would affect overload resolution, it would need a C# specification change and should not affect C# language versions that have already been standardized.

To be clear it impacts more than overload resolution. For all intents and purposes the symbol does not exist. The best way to visualize this is that the language ignores the member entirely when importing from metadata (details are likely to be different but practically this is how it will work). That means it impacts any feature which could resolve to that symbol.

[KalleOlaviNiemitalo]

If metadata were compiled from

public class A {
    public virtual void M() {}
}
public class B : A {
    [Obsolete(BinaryCompatOnly = true)]
    public new void M() {} // not virtual
}

and that were imported to

public class C : B {
    public override void M() {}
}

then, would C.M skip B.M and override A.M, adding a row in the MethodImpl table?

[tannergooding]

Marked as api-ready-for-review. We will end up discussing whether it should modify the existing attribute or be a new attribute in API review.

@jaredpar, is there any pressing need for this from the language for .NET 7/C# 11 or is it just part of the "general backlog"?

[jaredpar]

@tannergooding

is there any pressing need for this from the language for .NET 7/C# 11 or is it just part of the "general backlog"?

Not on our side. This proposal is mostly a reaction to roadblocks I've seen runtime / aspnetcore hit recently trying to evolve to modern C# features. Hence there is no direct priority here and could be done in .NET 7 or 8.

The one possible .NET 7 connection is CallerIdenityAttribute. I do not know if that is critical for .NET 7 or fine for a later version. It is hard to see how that could succeed the way we want without a proposal of this form. @jkotas, @agocke can likely speak best to the timeframe of that feature.

[jaredpar]

@KalleOlaviNiemitalo

then, would C.M skip B.M and override A.M, adding a row in the MethodImpl table?

This is why I was saying "visualize" vs. "this is how we are actually going to do it 😄

There are a number of details we'd need to work out on the language side. My expectation is that we'd import the member and keep it around for checks like duplicate members, duplicate types, exposing BinaryCompatOnly types in source methods, conflicting signatures, etc ... The member just wouldn't be a candidate for name lookup scenarios.