Skip to content
This repository was archived by the owner on Dec 12, 2020. It is now read-only.

Features

Jump to bottom
Amadeusz Sadowski edited this page Jun 15, 2019 · 7 revisions

Content

TODO

Prerequisites

  • An implementation of one of ICodeGenerator/IRichCodeGenerator
    • Any class implementing those interfaces must have a constructor that has single parameter of type Microsoft.CodeAnalysis.AttributeData. Otherwise an error will be raised on consumer build.

Terms

To easier navigate through the convoluted area of multiple levels of builds, runtimes, compilations, code, source and generation, the following expressions are defined:

-CG.R or framework is the CodeGeneration.Roslyn framework in general, including but not limited to the build task, command line tool invoked from it, or the public contract.

  • [Code]Generator is an implementation that performs the actual generation of source code given a compiled project.
  • Consumer is the end-user of the framework and generators
  • [Generator]Provider is the third party that actually provides generator implementation
  • Trigger [Attribute] is the attribute that triggers framework's engine and

ICodeGenerator

This interface offers basic TransformAsync method which will be called by CG.R Engine. Context of the generation location is passed via TransformationContext parameter, and two utility parameters are provided: IProgress will print given diagnostics into MSBuild log, and CancellationToken is provided for cancellation control.

Implementations are the actual generators that will then be used in consumer builds.

CodeGenerationAttributeAttribute

When a custom attribute definition is annotated with [CodeGenerationAttribute], it becomes the trigger attribute.

The type of code generator is read from attribute's CodeGenerationAttributeAttribute constructor parameter. This is either:

  • typeof(x) expression which requires code generator to live in the same assembly as the generator, or
  • a string constant containing fully qualified type name, e.g. CodeGeneration.Roslyn.Tests.Generators.EmptyPartialGenerator, CodeGeneration.Roslyn.Tests.Generators. If you omit the assembly name (after comma), it'll resolve to the same assembly as the one in which the attribute itself was declared.

An example:

using System;
using CodeGeneration.Roslyn;

[CodeGenerationAttribute("CodeGeneration.Roslyn.Tests.Generators.EmptyPartialGenerator, CodeGeneration.Roslyn.Tests.Generators")]
public class EmptyPartialAttribute : Attribute
{
}

The custom attribute can annotate any attribute-allowing syntax node, even a whole assembly (e.g. [assembly: MyGeneration]), there are no constraints on custom attribute's target.

Invocation

The code generator is instantiated for every applicable attribute occurrence and appropriate AttributeData is passed into it. Immediately after that the method TransformAsync is called.

TransformationContext

The context consists of:

  • CSharpSyntaxNode ProcessingNode which is the member that is annotated with a generator-associated attribute
  • CSharpCompilation Compilation which is the compilation model of all original source files.
  • SemanticModel for the whole CSharpCompilation in use
  • string ProjectDirectory - absolute path of the directory where the project file is located
  • IEnumerable<UsingDirectiveSyntax> CompilationUnitUsings contains usings generated by generators that already ran for some node in a document being processed. These usings will be added at the top of the generated source document.
  • IEnumerable<ExternAliasDirectiveSyntax> CompilationUnitExterns similar as above, but for extern directives.

Processing of ICodeGenerator results

TODO

IRichCodeGenerator

TODO

Processing of IRichCodeGenerator results

TODO

Clone this wiki locally