Proposal: Custom attributes on local variables

[IS4Code]

Note: This is similar to #1452 and #2478 in allowing attributes in additional contexts, but this is specifically about locals, and these attributes are not meant to be (just) source-only.

Motivation

Some code analyzers may require a way to be able to annotate declarations of local variables to specify further contracts, guards, or other requirements that apply when using them, for example:

[MustAwait] // "await t" or similar must be used before the method ends
Task t = ...;

[Unused] // It needs not be read
object o = ...;

[Unverified] // Must call v.Verify() before using
Verifiable v = ...;

Moreover, being able to use custom attributes in this location could also be helpful for the compiler itself, potential IL rewriting, optimizations during JIT/AOT, and similar (for example a more fine-grained [SkipLocalsInit]). Unless prevented via other mechanisms, these attributes need to be preserved in the generated CIL.

Design

Syntax

The syntax is modified to allow attributes in a local_variable_declaration:

local_variable_declaration
-    : implicitly_typed_local_variable_declaration
-    | explicitly_typed_local_variable_declaration
-    | ref_local_variable_declaration
+    : attributes? implicitly_typed_local_variable_declaration
+    | attributes? explicitly_typed_local_variable_declaration
+    | attributes? ref_local_variable_declaration
    ;

Additionally, "var" becomes a standard attribute_target, to be used only in a local_variable_declaration.

Usage

There are two options as to what attributes are made to be permitted on a local variable:

• Add AttributeTargets.Variable (or recognize (AttributeTargets)32768) to specifically designate attributes meant to be used only on local variables. This has potential issues however with compilations targeting older versions of the runtime, and the meaning of AttributeTargets.All.

• Recognize some existing attributes as implicitly applying to local variables as well. Specifically, I suggest to allow any attribute matching all of these conditions:

  • It allows AttributeTargets.Parameter ‒ a parameter is a variable, hence what makes sense on local variables should usually make sense on parameters too.
  • It allows at least one of AttributeTargets.Field, AttributeTargets.Property, or AttributeTargets.ReturnValue. This is to show that it applies to other storage locations as well.

  I have checked all types in the runtime that match this condition (but do not specify too many other targets), arriving at this list. Click below to show.

  System.Runtime.InteropServices.MarshalAsAttribute
  System.Runtime.InteropServices.Marshalling.MarshalUsingAttribute
  System.Runtime.CompilerServices.CustomConstantAttribute
  System.Runtime.CompilerServices.DateTimeConstantAttribute
  System.Runtime.CompilerServices.DecimalConstantAttribute
  System.Runtime.CompilerServices.TupleElementNamesAttribute
  System.Reflection.ObfuscationAttribute
  System.Diagnostics.Contracts.PureAttribute
  System.Diagnostics.CodeAnalysis.AllowNullAttribute
  System.Diagnostics.CodeAnalysis.DisallowNullAttribute
  System.Diagnostics.CodeAnalysis.MaybeNullAttribute
  System.Diagnostics.CodeAnalysis.NotNullAttribute
  System.Diagnostics.CodeAnalysis.NotNullIfNotNullAttribute
  System.Diagnostics.CodeAnalysis.UnscopedRefAttribute
  System.Diagnostics.CodeAnalysis.StringSyntaxAttribute
  System.ComponentModel.DataAnnotations.AllowedValuesAttribute
  System.ComponentModel.DataAnnotations.Base64StringAttribute
  System.ComponentModel.DataAnnotations.CreditCardAttribute
  System.ComponentModel.DataAnnotations.CustomValidationAttribute
  System.ComponentModel.DataAnnotations.DataTypeAttribute
  System.ComponentModel.DataAnnotations.DeniedValuesAttribute
  System.ComponentModel.DataAnnotations.DisplayAttribute
  System.ComponentModel.DataAnnotations.EmailAddressAttribute
  System.ComponentModel.DataAnnotations.EnumDataTypeAttribute
  System.ComponentModel.DataAnnotations.FileExtensionsAttribute
  System.ComponentModel.DataAnnotations.LengthAttribute
  System.ComponentModel.DataAnnotations.MaxLengthAttribute
  System.ComponentModel.DataAnnotations.MinLengthAttribute
  System.ComponentModel.DataAnnotations.PhoneAttribute
  System.ComponentModel.DataAnnotations.RangeAttribute
  System.ComponentModel.DataAnnotations.RegularExpressionAttribute
  System.ComponentModel.DataAnnotations.RequiredAttribute
  System.ComponentModel.DataAnnotations.StringLengthAttribute
  System.ComponentModel.DataAnnotations.UrlAttribute
  System.Runtime.CompilerServices.DynamicAttribute
  System.Xml.Serialization.SoapAttributeAttribute
  System.Xml.Serialization.SoapElementAttribute
  System.Xml.Serialization.SoapIgnoreAttribute
  System.Xml.Serialization.XmlAnyAttributeAttribute
  System.Xml.Serialization.XmlAnyElementAttribute
  System.Xml.Serialization.XmlArrayAttribute
  System.Xml.Serialization.XmlArrayItemAttribute
  System.Xml.Serialization.XmlAttributeAttribute
  System.Xml.Serialization.XmlChoiceIdentifierAttribute
  System.Xml.Serialization.XmlElementAttribute
  System.Xml.Serialization.XmlIgnoreAttribute
  System.Xml.Serialization.XmlNamespaceDeclarationsAttribute
  System.Xml.Serialization.XmlTextAttribute
  System.Runtime.InteropServices.ComAliasNameAttribute
  System.Runtime.CompilerServices.IDispatchConstantAttribute
  System.Runtime.CompilerServices.IUnknownConstantAttribute
  System.Runtime.InteropServices.JavaScript.JSMarshalAsAttribute`1[T]
  

  While some of these don't make that big of a sense on local variables, I don't see any harm in allowing them just in case.

Both options are possible to adopt, which would increase compatibility with existing attributes, and allow the creation of new ones specifically restricted to local variables.

Interpretation

Each individually specified attribute applies to all variables declared in the local_variable_declaration, as long as its target is var or unspecified. Moreover:

• If the target is unspecified or field, and the attribute supports AttributeTargets.Field, the attribute applies to all compiler-generated fields corresponding to the variable, for example in a closure object or iterator/asynchronous state.
• If the target is unspecified or param, and the attribute supports AttributeTargets.Parameter, the attribute applies to all compiler-generated parameters corresponding to the variable. I am not sure if this currently happens anywhere, but it might.

This serves to ensure that the attribute survives even if the local variable is not necessarily encoded as a variable in CIL. If that is not the case (a non-existent target is specified, or the attribute's AttributeTargets flags are not compatible with the implied target), an error is produced.

In a context where the declaration of a local variable might be omitted entirely by the compiler (as an optimization) when generating CIL (or it may be merged with an unrelated local variable of the same type), this optimization should be skipped if there was an attribute on it. This means the identity of a variable should be preserved when it has custom attributes (as long as they should be encoded alongside it).

Encoding

As seen above, an attribute on a local variable might eventually turn into one on a field or a parameter ‒ if that is the case, it is encoded the usual way.

An attribute on an actual (CIL) local variable is currently possible to realize in one of two ways:

• As an optional modifier on the variable's type. This is however viable only if the parameterless constructor of the attribute was used, and I am not actually sure if the modifier can be found via reflection, since there is no LocalVariableInfo.GetModifiedLocalType().
• As a new attribute placed on the method that contains the local variable. This attribute is of this form (provided by the runtime or compiler-generated):

  namespace System.Runtime.CompilerServices;
  
  [AttributeUsage(AttributeTargets.Method | AttributeTargets.Constructor, AllowMultiple = true, Inherited = false)]
  sealed class LocalVariableAttributeDeclarationAttribute : Attribute
  {
      public LocalVariableAttributeDeclarationAttribute(int localIndex, Type attributeType, Type[] attributeCtorTypes, byte[] blob);
  }

  localIndex corresponds to LocalVariableIndex.LocalIndex. Unlike in "real" attributes, the constructor must be specified separately, using its declaring Type and the signature, as a Type array of its parameters (including their optional/required modifiers, if any). This should uniquely specify the constructor of the attribute. blob is the same as in metadata, encoding the arguments and assigned properties.

Examples

void Method()
{
    [Attr] // or [var: Attr]
    int a = 1;
}

// Is effectively translated into:

[LocalVariableAttributeDeclaration(0, typeof(Attr), [], [1, 0, 0, 0, 0, 0, 0, 0]]
void Method()

The same happens in case of multiple declared variables:

void Method()
{
    [Attr]
    (int a, int b, int c) = (1, 2, 3);
}

// Is translated into:

[LocalVariableAttributeDeclaration(0, typeof(Attr), [], [1, 0, 0, 0, 0, 0, 0, 0]]
[LocalVariableAttributeDeclaration(1, typeof(Attr), [], [1, 0, 0, 0, 0, 0, 0, 0]]
[LocalVariableAttributeDeclaration(2, typeof(Attr), [], [1, 0, 0, 0, 0, 0, 0, 0]]
void Method()

Conversely,

Func<int> Method()
{
    [Attr] // or [field: Attr], but not [var: ...]
    int a = 1;
    return () => a;
}

// Can be translated into:

Func<int> Method()
{
    var result = new DisplayClass();
    result.a = 1;
    return result.Invoke;
}

class DisplayClass
{
    [Attr]
    public int a;

    public int Invoke() => a;
}

[HaloFour]

See: #1452

[IS4Code]

To clarify, there is no necessity to change the runtime to support them, since there is an existing solution (albeit workaround-y) that works with all .NET targets, similarly to how nullable/ref annotations work.

Yes, C# locals don't map exactly to CIL, but that is even more reason for something like this, to attach attributes to the things they do map to. If that is a field, it gets attached to the field, and you can even specify what you want it to attach to.

Hence this is not just about source-only usage of attributes; these attributes are concrete, real, emitted (albeit through a custom encoding) attributes. You can find them in CIL (encoded as best as possible), you can find them through reflection, the runtime can find them (in some way), and so tools at all levels (not just the source level) may use them.

[HaloFour]

Yes, C# locals don't map exactly to CIL, but that is even more reason for something like this, to attach attributes to the things they do map to. If that is a field, it gets attached to the field, and you can even specify what you want it to attach to.

That doesn't help when the compiler reuses slots for multiple locals based on scoping.

[IS4Code]

That is also mentioned in the proposal (in "Interpretation") ‒ the compiler simply should not perform this optimization when the "identity" of the variable would be endangered in a way that prevents correctly retrieving the attribute.

If that attribute, however, gets "removed" during compilation anyway (e.g. through [Conditional]), the compiler is free to perform the optimization. Thus you can freely express [Mutable] as an attribute with [Conditional("NEVER")], attach it to any variable, and it would just work and not harm any optimization (but you could be able to see it in the build if you wanted to, such as by using [Conditional("DEBUG")] instead).

[HaloFour]

That's fine. We can leave it that I don't think it's worthwhile outside of the source attributes discussion. It's a lot more complicated for a lot less gain. :)

[333fred]

While I am somewhat interested in the idea of attributes on locals, I do not think there is any future where these attributes get reflected in runtime code. Locals as C# calls them do not exist at runtime; they are entirely an implementation detail. Any proposal that attempts to make them visible in IL is, imo, dead on arrival.