Source Generators
Atom uses Roslyn source generators and analysers to reduce boilerplate. This page explains what they do and how they affect your build definition.
Packages
| Package | Role |
|---|---|
Invex.Atom.Build.SourceGenerators |
Generates code for [BuildDefinition], [GenerateEntryPoint], [ConfigureHostBuilder], [GenerateSolutionModel], and [GenerateInterfaceMembers]. |
Invex.Atom.Build.Analyzers |
Reports diagnostics for common mistakes (e.g. forgetting partial, missing attributes). |
Both are automatically referenced when you add Invex.Atom.Build.
What Gets Generated
[BuildDefinition]
For a build definition decorated with [BuildDefinition] (either an interface extending
IBuildDefinition or a partial class deriving from BuildDefinition), the generator emits:
TargetDefinitions— a dictionary mapping target names toTargetdelegates, collected from the build definition and all implemented interfaces.ParamDefinitions— a dictionary mapping parameter names toParamDefinitionrecords, collected from[ParamDefinition]/[SecretDefinition]attributes.AccessParam— a method that can read any declared parameter by name.- An implementation of
IConfigureHost: staticConfigureHostBuilderandConfigureHostmethods that register the build's module interfaces in the service collection, call everyConfigureHostBuilderFrom{InterfaceName}/ConfigureHostFrom{InterfaceName}hook of the implemented interfaces, and then call the optionalstatic partial void OnConfigureHostBuilder(IHostApplicationBuilder builder)andstatic partial void OnConfigureHost(IHost host)methods, which you can implement on the build class.AtomHostcalls these without constructing the build definition.
For an interface build such as IBuild, the class is emitted as internal sealed partial class Build in the same
namespace (the interface name without its leading I), so you can add members such as OnConfigureHostBuilder to it
in your own partial class Build.
[GenerateEntryPoint]
Emits a Program class with:
AtomHost.Run<Build>(args);
[ConfigureHostBuilder] / [ConfigureHost]
For interfaces marked with [ConfigureHostBuilder], the generator declares a
protected static partial void ConfigureHostBuilderFrom{InterfaceName}(IHostApplicationBuilder builder) method and
ensures that when a [BuildDefinition] implements the interface, that method is called from the generated
ConfigureHostBuilder during host setup. [ConfigureHost] likewise declares
protected static partial void ConfigureHostFrom{InterfaceName}(IHost host), called from the generated ConfigureHost
when UseAtom runs. The analyzers AT0003 and AT0002 report a missing implementation. The build interface of an
interface build can carry these attributes too.
[GenerateSolutionModel]
Scans the solution file and emits a typed model with project paths.
[GenerateInterfaceMembers]
Generates boilerplate interface members (e.g. forwarding properties) so module authors don't have to write them manually.
Analyser Diagnostics
The analyser package reports warnings and errors such as:
- Build definition class is not
partial [BuildDefinition]is missing on a class that inheritsBuildDefinition- Target properties that don't follow the expected pattern
Debugging Generators
To inspect the generated code:
In your
.csproj, add:<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>Build the project. Generated files appear under
obj/Debug/net*/generated/.
Next steps
- Testing: test build definitions and modules.
- Build Definitions: the attributes from a consumer's point of view.
- BuildDefinitionAttribute
- GenerateEntryPointAttribute
- GenerateSolutionModelAttribute
- GenerateInterfaceMembersAttribute