"extern partial" ‒ attach compile time-only attributes to members from external assemblies

[IS4Code]

Introduction

Many custom attributes are used to affect the interpretation of code at compile time, such as:

• [Conditional], affecting whether a call to a method is preserved or omitted depending on compilation symbols.
• [Obsolete], displaying a warning/error when a member is used.
• Nullability-affecting attributes, i.e. [Nullable] and various nullability analysis attributes like [MaybeNull] etc.
• Various attributes to encode C#-specific features (such as extensions: [Extension], params: [ParamArray], indexers: [DefaultMember], tuple elements: [TupleElementNames], etc.).

While all these attributes are also retained in the metadata and readable at runtime, their main use is to affect C# code using the members where they are attached in a way that does not need to read them at runtime. Additionally, various source analyzers and generators can define their own custom attributes that affect how members are interpreted and processed (for example a compile time-only JSON formatter could use attributes to generate code constructing instances from JSON objects).

In all these cases, it may be useful not only for the code that defines such members to use these attributes, but also for the code that uses them. Imagine:

• You could mark any applicable method as [Conditional], preventing it from being called in your code in specific cases. This is what interceptors can already do, but in a much more complicated way.
• You could make any type or member [Obsolete], letting other programmers using the codebase know that it should not be used. This is what source analyzers can already do, but you have to give them the list of obsolete members in some fashion, or use specialized ones for common sets of members.
• You could attach (or augment) nullability information for members in assemblies that don't use them (there are really some that do that, and it is not only .NET Framework). This is not possible at the moment without modifying the assembly.

Why?

The usefulness of filling in nullability annotations is obvious, but it is not immediately clear why do more than that. The reasons are:

• An optimal solution for nullability annotations should be as close as possible to how one would normally express them on members defined in C#. This calls for C# code or something very similar for programmers to write, using the existing language of custom attributes to express nullability, even anticipating that more may be added. At this point, it becomes much greater burden to restrict such code to use only particular attributes than to allow all to be used freely.
• Source analyzers are free to define their own attributes for various situations and contracts, almost paralleling those used for null-state analysis. It makes sense to extend any support to them too, and even better if that automatically works for existing analyzers. This would achieve such a goal.
• There are already C# features that allow for something similar: partial classes and methods, which also make it possible to add attributes to a member defined in another location (albeit for the same assembly). Using this as the base makes it not only easier to explain to people wanting to use it, but also introduces new language that might make it easier to express similar concepts.

Solution: extern partial

namespace System.Threading.Tasks;

extern partial class Task
{
    [Obsolete("Use await!")]
    void Wait();
}

extern partial class Task<T>
{
    [Obsolete("Use await!")]
    T Result { get; }
}

As far as the compiler is concerned, the members are suddenly obsolete (when viewed from the code that specified the extern partial types).

Details

Types

• extern partial could be used at any non-nested type declaration. An extern partial type does not result in any new type in the assembly, instead referring to any externally existing type by the same name (and arity). The types declared above are the usual System.Threading.Tasks.Task(<T>) and not any new type.
• An externally defined type must already exist for extern partial to identify it, otherwise it results in an error (as there would be no type to augment). If there are multiple matching external types, extern alias could be used to resolve them.
• An extern partial type declaration must not have any other modifiers (no explicit visibility, abstract, sealed, or static). It also must not have any generic constraints.
• There may be multiple extern partial declarations for the same type (with the same effect as being merged together). Additionally, there may also be non-extern partial definitions for a type with the same name (with or without partial), but these denote a distinct type (like they do already) and are not affected by the extern partial declaration.
• An extern partial type may be a class, struct, enum, interface, or delegate. record is not allowed ‒ class or struct is enough to match the type (likewise just struct instead of ref struct).

Members

• Members of extern partial types are implicitly extern partial (including nested types). Explicitly adding this modifier (or just partial) is an error.
• Nested types have the same restrictions as top-level types.
• Fields, events, properties, methods, and constructors may be declared. The external type must contain such a member (with the correct name and signature).
• The only modifier allowed on (non-type) members is static, which must match the original member.
• Methods, constructors, and properties' and events' accessors must have no bodies. Fields and properties must not be assigned to any value.
• Generic methods must have no constraints.

Custom attributes

• Custom attributes may be specified on any location within an extern partial type, just like for regular types.
• For all compile time-only intents and purposes, the attribute is treated as if applied in the original assembly.
• For all runtime-only intents and purposes, the attribute is ignored.

Syntax-specific attributes

Some attributes are special in C# and cannot be used manually. Whether they are usable or not in this context can be decided on a per-case basis.

• Static methods could be turned into extensions by marking their first parameter with this. This has limited usefulness however, since new extension methods may simply be created.
• Methods with an last array parameter could be made params. Probably solvable with extension methods too.
• ValueTuple could be given element names. This has somewhat greater impact than changing method parameter names.
• object could be turned into dynamic. Probably no significant use cases.

Potential extensions

• While this proposal is aimed specifically at attributes, there are other things that may potentially be augmented (with arguable usefulness):
  • Generic constraints ‒ adding more constraints can help enforce rules that would otherwise be too lax (remained for compatibility for example). Adding where T : Delegate or where T : unmanaged to existing APIs (which would otherwise throw at runtime) might be useful.
  • More restrictive visibility ‒ changing public members to private or protected might be useful for hiding members that are too visible.
  • Parameter names and default values ‒ names of existing parameters can be modified for situations where they are explicitly named, or default values could be provided.
• Runtime ‒ while all these changes affect only the compilation, this information could also be obtained at runtime, for example using the existing TypeDescriptor mechanism (which would make them extend to the whole application), or local solutions.

Alternatives

• Extensions ‒ extensions can be viewed as adding new members to existing types, which is similar extern partial types and members which modify members of existing types. A similar syntax could be used for both, moving the extern partial to the member itself (indicating that it is not a new extension member but an existing one):

  extension class Task
  {
      [Obsolete("Use await!")]
      extern partial void Wait();
  }

Examples

Nullability

Assembly A:

#nullable disable
public class C
{
    public string S1 { get; }
    public string S2 { get; }
}

Assembly B, referencing A:

#nullable enable
extern partial class C
{
    string S1 { get; }
    string? S2 { get: }
}

This adds nullability information to the existing members C.S1 and C.S2.

Conditional execution

using System.Diagnostics;

namespace System;

extern partial class Environment
{
    [Conditional("CAN_EXIT")]
    static void Exit(int exitCode);
}

This stops calls to Environment.Exit from taking effect, unless CAN_EXIT is defined.

[TahirAhmadov]

What if the member already has an attribute or has nullability defined?

[IS4Code]

That is a good point to think about. I was thinking about modelling this on the way partial behaves now, but there should definitely be differences ‒ partial declarations must align because they are at the same level, while extern partial could take priority over anything external.

Thankfully attributes already offer a mechanism to help solve this, since they have AllowMultiple. My opinion is that attributes should be only merged and never removed or replaced, so if they have AllowMultiple=false (the default), adding another one should result in an error.

Special handling is required for auto-generated attributes of course, i.e. those resulting from nullability, dynamic, tuples etc. Either they are completely missing, in which case the extern partial declaration could fill them in, or they are already specified, in which case, by the same opinion, they must match.

I must add however that I don't feel particularly strong about either option. Adding missing information could already affect the behaviour of the application in significant ways, so perhaps being able to replace it completely is not that big of a deal.

Another possibility is defaulting to non-replacement, but having a keyword that permits it (let's say replace):

Assembly A:

#nullable enable
public class C
{
    public ValueTuple<int, int> T1 { get; }
    public (int a, int b) T2 { get; }
    public string S1 { get; }
#nullable disable
    public string S2 { get; }
}

Assembly B:

#nullable enable
extern partial class C
{
    (int x, int y) T1 { get; } // fine, just fills in the missing information
    (int x, int y) T2 { get; } // error, changes existing attribute
    replace (int x, int y) T2 { get; } // fine again, replaces the attribute

    string? S1 { get; } // error
    replace string? S1 { get; } // fine
    string? S2 { get; } // fine
}

[colejohnson66]

Nullability would, in theory, need no special work. It’s encoded as [Nullable(…)] and NullableAttribute has AllowMultiple=false.

[TahirAhmadov]

Unfortunately, it may not be as simple. Last time I checked, NRT attributes are emitted on various levels, sometimes on the type, sometimes on the member.

[colejohnson66]

Yes, but those issues would apply to attribute merging for any type, not just NullableAttribute. Unless you mean the annotations themselves being complex? That’s true.
It’s possible the compiler could also special case nullability annotations and just “dedup” them if they’re compatible.