Template parameters and type parameters

Thanks to compile-time parameters, your BuildAspect implementation can pass arguments to the template. There are two kinds of template parameters: standard and type parameters (also known as generic parameters).

Unlike run-time parameters:

• Compile-time parameters must receive a value at compile time from the BuildAspect method.
• Compile-time parameters are not visible in generated code, i.e. they are removed from the parameter list when the template is expanded.

Parameters

Compile-time parameters are especially useful when the same template is used several times by the aspect -- for instance when you introduce a method for each field of a type, and the method needs to know which field it must handle.

To define and use a compile-time parameter in a template method:

1. Add one or more parameters to the template method and annotate them with the CompileTimeAttribute custom attribute. The type of the parameter must not be run-time-only. If the parameter type is compile-time-only (for example, IField), the custom attribute is redundant.

2. In your implementation of the BuildAspect method, when adding the advice by calling a method of the IAdviceFactory interface, pass the parameter values as an anonymous object to the args argument like this: args: new { a = "", b = 3, c = field } where a, b and c are the exact names of the template parameters (the name matching is case sensitive).

Alternative: tags

When you cannot use compile-time parameters (typically because you have a field, property, or event template instead of a method template), you can replace them with tags. For details about tags, see Sharing state with advice. The advantage of compile-time parameters over tags is that template parameters make the code more readable. Tags require cumbersome syntax.

Type parameters

Compile-time type parameters, aka compile-time generic parameters, are generic parameters whose value is specified at compile time by the BuildAspect method. Compile-time type parameters are a type-safe alternative to dynamic typing in templates. With compile-time type parameters, it is more convenient to reference a type from a template since it can be referenced as a type, instead of using a more cumbersome syntax like meta.Cast.

To define and use a compile-time type parameter in a template method follow the similar steps as for a normal compile-time parameter:

1. Add one or more type parameters to the template method and annotate them with the CompileTimeAttribute custom attribute. The type parameter can have arbitrary constraints. The current version of Metalama will ignore them when expanding the template.

2. In your implementation of the BuildAspect method, when adding the advice by calling a method of the IAdviceFactory interface, pass the parameter values as an anonymous object to the args argument like this: args: new { T1 = typeof(int), T2 = field.Type } where T1 and T2 are the exact names of the template parameters (note that the name matching is case sensitive).

Alternative: dynamic typing

The alternative to compile-time type parameters is dynamic typing and using methods like meta.Cast or abstractions like IExpression. For details about generating run-time code, see Generating run-time code.

Example

The following aspect generates, for each field or property Bar, a method named ResetBar, which sets the field or property to its default value.

The Reset template method accepts two compile-time parameters:

• A standard parameter field that contains the field or property to which the template relates.
• A type parameter T that contains the type of the field or property. This type parameter is used to generate the default(T) syntax, where T is replaced by the actual field or property when the template is expanded.

1using Metalama.Framework.Aspects;
2using Metalama.Framework.Code;
3using System.Linq;
4
5namespace Doc.GenerateResetMethods
6{
7    public class GenerateResetMethodsAttribute : TypeAspect
8    {
9        public override void BuildAspect( IAspectBuilder<INamedType> builder )
10        {
11            base.BuildAspect( builder );
12
13            foreach ( var field in builder.Target.FieldsAndProperties.Where( f => !f.IsImplicitlyDeclared && f.Writeability != Writeability.None ) )
14            {
15                builder.Advice.IntroduceMethod(
16                    builder.Target,
17                    nameof(this.Reset),
18                    args: new { field = field, T = field.Type },
19                    buildMethod: m => m.Name = "Reset" + CamelCase( field.Name ) );
20            }
21        }
22
23        private static string CamelCase( string s )
24        {
25            s = s.TrimStart( '_' );
26
27            return s[0].ToString().ToUpperInvariant() + s.Substring( 1 );
28        }
29
30        [Template]
31        public void Reset<[CompileTime] T>( IFieldOrProperty field )
32        {
33            field.Value = default(T);
34        }
35    }
36}

1namespace Doc.GenerateResetMethods
2{
3    [GenerateResetMethods]
4    public class Foo
5    {
6        private int _x;
7
        Warning CS8618: Non-nullable property 'Y' must contain a non-null value when exiting constructor. Consider declaring the property as nullable.

8        public string Y { get; set; }
9
10        public string Z => this.Y;
11    }










12}

1namespace Doc.GenerateResetMethods
2{
3    [GenerateResetMethods]
4    public class Foo
5    {
6        private int _x;
7
8        public string Y { get; set; }
9
10        public string Z => this.Y;
11
12        public void ResetX()
13        {
14            this._x = default(int);
15        }
16
17        public void ResetY()
18        {
19            this.Y = default(string);
20        }
21    }
22}