How to generate Dart code for annotations at fields?

Question

I'm writing a code generator for Dart using the build_runner, but my builder is not being called for annotations at fields, although it does work for annotations at classes.

Is it possible to also call the generator for annotations at fields (or at any place for that matter)?

For example, the builder is called for the following file:

import 'package:my_annotation/my_annotation.dart';

part 'example.g.dart';

@MyAnnotation()
class Fruit {
  int number;
}

But not for this one:

import 'package:my_annotation/my_annotation.dart';

part 'example.g.dart';

class Fruit {
  @MyAnnotation()
  int number;
}

Here's the definition of the annotation:

class MyAnnotation {
  const MyAnnotation();
}

And this is how the generator is defined. For now, it just aborts whenever it's called, causing an error message to be printed.

library my_annotation_generator;

import 'package:analyzer/dart/element/element.dart';
import 'package:build/build.dart';
import 'package:my_annotation/my_annotation.dart';
import 'package:source_gen/source_gen.dart';

Builder generateAnnotation(BuilderOptions options) =>
    SharedPartBuilder([MyAnnotationGenerator()], 'my_annotation');

class MyAnnotationGenerator extends GeneratorForAnnotation<MyAnnotation> {
  @override
  generateForAnnotatedElement(Element element, ConstantReader annotation, _) {
    throw CodeGenError('Generating code for annotation is not implemented yet.');
}

Here's the build.yaml configuration:

targets:
  $default:
    builders:
      my_annotation_generator|my_annotation:
        enabled: true

builders:
  my_annotation:
    target: ":my_annotation_generator"
    import: "package:my_annotation/my_annotation.dart"
    builder_factories: ["generateAnnotation"]
    build_extensions: { ".dart": [".my_annotation.g.part"] }
    auto_apply: dependents
    build_to: cache
    applies_builders: ["source_gen|combining_builder"]

Dan R · Answer 1 · 2019-12-10T10:47:47.017

At least from my experience, your file 'example.dart' would need at least one annotation above the class definition to be parsed by GeneratorForAnnotation.

example.dart:

import 'package:my_annotation/my_annotation.dart';

part 'example.g.dart';

@MyAnnotation()
class Fruit {
 @MyFieldAnnotation()
 int number;
}

To access annotations above class fields or class methods you could use a visitor to "visit" each child element and extract the source code information. For example, to get information about the class fields you could override the method visitFieldElement and then access any annotations using the getter: element.metadata.

builder.dart:

import 'dart:async';
import 'package:analyzer/dart/element/element.dart';
import 'package:analyzer/dart/element/visitor.dart';
import 'package:analyzer/dart/element/type.dart';
import 'package:build/src/builder/build_step.dart';
import 'package:source_gen/source_gen.dart';
import 'package:my_annotation/my_annotation.dart';

class MyAnnotationGenerator extends 
GeneratorForAnnotation<MyAnnotation> {
  @override
  FutureOr<String> generateForAnnotatedElement(
      Element element, 
      ConstantReader annotation,   
      BuildStep buildStep,){
    return _generateSource(element);
  }

  String _generateSource(Element element) {
    var visitor = ModelVisitor();
    element.visitChildren(visitor);
    return '''
      // ${visitor.className}
      // ${visitor.fields}
      // ${visitor.metaData}
    ''';
  }
}

class ModelVisitor extends SimpleElementVisitor {
  DartType className;
  Map<String, DartType> fields = {};
  Map<String, dynamic> metaData = {};

  @override
  visitConstructorElement(ConstructorElement element) {
    className = element.type.returnType;
  }

  @override
  visitFieldElement(FieldElement element) {
    fields[element.name] = element.type;
    metaData[element.name] = element.metadata;
  }
}

Note: In this example, _generateSource returns a commented statement. Without comments you would need to return well-formed dart source code, otherwise, the builder will terminate with an error.

For more information see: Source Generation and Writing Your Own Package (The Boring Flutter Development Show, Ep. 22) https://www.youtube.com/watch?v=mYDFOdl-aWM&t=459s

Great, thank you! Instead of using a `GeneratorForAnnotation`, which can only detect top-level annotations, I finally settled with generating a custom `Generator`, which parses all the fields. You can see it in action here: https://pub.dev/packages/has_is_getters — Marcel, Dec 13 '19 at 22:28
@Marcel, thanks for including a link to your project. Please consider briefly answering your own question here. While examples of code generation can be found on github.com there is still a lack of documentation aimed at those who are getting started with Dart source code generation. — Dan R, Dec 16 '19 at 11:21
Metadata isn't including the field annotations, was that intended, and if not, how do we access the field annotations? — Luke Pighetti, Mar 26 '20 at 02:46
When I tried this, the `metadata` was always empty. I later realized that I was annotating getters and not fields. So if you also face this problem, check that you have annotations over fields. If you have getters, you would need to implement `visitPropertyAccessorElement(PropertyAccessorElement element)` in your visitor. — lyio, Feb 03 '21 at 08:17

score 3 · Accepted Answer · answered Dec 17 '19 at 15:12

The built-in GeneratorForAnnotation uses the LibraryElement's annotatedWith(...) method, which only checks for top-level annotations. To also detect annotations on fields, you'll need to write something custom.

Here's the Generator I wrote for my project:

abstract class GeneratorForAnnotatedField<AnnotationType> extends Generator {
  /// Returns the annotation of type [AnnotationType] of the given [element],
  /// or [null] if it doesn't have any.
  DartObject getAnnotation(Element element) {
    final annotations =
        TypeChecker.fromRuntime(AnnotationType).annotationsOf(element);
    if (annotations.isEmpty) {
      return null;
    }
    if (annotations.length > 1) {
      throw Exception(
          "You tried to add multiple @$AnnotationType() annotations to the "
          "same element (${element.name}), but that's not possible.");
    }
    return annotations.single;
  }

  @override
  String generate(LibraryReader library, BuildStep buildStep) {
    final values = <String>{};

    for (final element in library.allElements) {
      if (element is ClassElement && !element.isEnum) {
        for (final field in element.fields) {
          final annotation = getAnnotation(field);
          if (annotation != null) {
            values.add(generateForAnnotatedField(
              field,
              ConstantReader(annotation),
            ));
          }
        }
      }
    }

    return values.join('\n\n');
  }

  String generateForAnnotatedField(
      FieldElement field, ConstantReader annotation);
}

How are you using this? How do we nest these results inside a result from GeneratorForAnnotation? Consider a class with an annotation which contains fields with annotations — Luke Pighetti, Mar 26 '20 at 02:58

score 0 · Answer 3 · answered Dec 01 '21 at 10:44

I had a very similar issue trying to target specific methods within my annotated classes. Inspired by your answers I slightly modified the class annotation model_visitor to check the method annotation before selecting elements.

class ClassAnnotationModelVisitor extends SimpleElementVisitor<dynamic> {
  String className;

  Map<String, String> methods = <String, String>{};
  Map<String, String> parameters = <String, String>{};

  @override
  dynamic visitConstructorElement(ConstructorElement element) {
    final elementReturnType = element.type.returnType.toString();
    className = elementReturnType.replaceFirst('*', '');
  }

  @override
  dynamic visitMethodElement(MethodElement element) {
    if (methodHasAnnotation(MethodAnnotation, element)) {
      final functionReturnType = element.type.returnType.toString();
      methods[element.name] = functionReturnType.replaceFirst('*', '');
      parameters[element.name] = element.parameters.map((e) => e.name).join(' ,');
    }
  }

  bool methodHasAnnotation(Type annotationType, MethodElement element) {
    final annotations = TypeChecker.fromRuntime(annotationType).annotationsOf(element);
    return !annotations.isEmpty;
  }
}

Then, I can use the basic GeneratorForAnnotation class and generate for class and methodsArray.

How to generate Dart code for annotations at fields?

3 Answers3