|
| 1 | +# Reading generated code |
| 2 | + |
| 3 | +SourceFlow.Net v3 finds and wires domain types at **compile time**. The `SourceFlow.Generators` source generator ships inside the `SourceFlow.Net` package (ADR-004). It writes ordinary C# that you can read, step through in the debugger and review in pull requests. Nothing in command dispatch, event application or registration uses reflection (GAP-16). |
| 4 | + |
| 5 | +This page shows where the generated files are and what each one contains. |
| 6 | + |
| 7 | +## Where to find the files |
| 8 | + |
| 9 | +Every project in this repository sets `EmitCompilerGeneratedFiles=true` (root `Directory.Build.props`), so generated files land on disk: |
| 10 | + |
| 11 | +```text |
| 12 | +obj/<Configuration>/net10.0/generated/ |
| 13 | + SourceFlow.Generators/SourceFlow.Generators.SourceFlowGenerator/ ← SourceFlow output |
| 14 | + System.Text.Json.SourceGeneration/…/ ← your module's JsonSerializerContext |
| 15 | +``` |
| 16 | + |
| 17 | +In your own application, set the same property in the project file: |
| 18 | + |
| 19 | +```xml |
| 20 | +<PropertyGroup> |
| 21 | + <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> |
| 22 | +</PropertyGroup> |
| 23 | +``` |
| 24 | + |
| 25 | +In Visual Studio and Rider, the files also appear under **Dependencies → Analyzers → SourceFlow.Generators**. *Go to definition* on a generated member opens them too. |
| 26 | + |
| 27 | +Each file is named `<Namespace>.<Type>.<Kind>.g.cs`, for example `Bank.Accounts.BankAccount.Aggregate.g.cs`. Each one starts with `// <auto-generated/>`. Don't edit them: they're rebuilt on every compilation. |
| 28 | + |
| 29 | +## What is generated |
| 30 | + |
| 31 | +| You write | Kind | Generated | |
| 32 | +|-----------|------|-----------| |
| 33 | +| `[StronglyTypedId] partial record struct AccountId(Guid Value)` | `Id` | `New()` (UUIDv7), `Parse`/`TryParse`, `ToString` (`"D"`), `ToStreamSegment()` (`"N"`), formatting, a JSON converter | |
| 34 | +| `[Aggregate("bank-account")] partial record BankAccount : IAggregate<…>` | `Aggregate` | `IAggregateRuntime`: `AggregateName`, `DecidedCommands`, `TargetingCommands`, a `Decide` switch over command types, `TargetOf` (the `[AggregateId]` member), and an `Evolve` switch over the `When` methods | |
| 35 | +| `[Projection("account-summary")] partial class … : IDocumentProjection<TDoc, TKey>` | `Projection` | `HandledEvents`, `TryGetKey`, `FormatKey`, and an `Apply` switch over the `When` methods | |
| 36 | +| `[ProcessManager("money-transfer")] partial record … : IProcessManager<…>` | `ProcessManager` | `HandledMessages`, a `TryCorrelate` switch over `CorrelateBy`, and a `React` switch | |
| 37 | +| `[SourceFlowModule(typeof(MyJsonContext))] partial class MyModule` | `Module` | `Register`: every message type (sorted by name, with its kind), aggregate, projection, process manager and handler in the assembly, plus your JSON context | |
| 38 | + |
| 39 | +### Example: an aggregate |
| 40 | + |
| 41 | +From the Bank sample (`samples/Bank/Bank.Accounts/BankAccount.cs`): |
| 42 | + |
| 43 | +```csharp |
| 44 | +static Decision IAggregateRuntime<BankAccount, AccountId>.Decide(BankAccount state, ICommand command, in DecisionContext context) |
| 45 | +{ |
| 46 | + return command switch |
| 47 | + { |
| 48 | + CloseAccount c => state.Decide(c, context), |
| 49 | + Deposit c => state.Decide(c, context), |
| 50 | + OpenAccount c => state.Decide(c, context), |
| 51 | + Withdraw c => state.Decide(c, context), |
| 52 | + _ => throw new UnhandledMessageException(command.GetType()), |
| 53 | + }; |
| 54 | +} |
| 55 | + |
| 56 | +public BankAccount Evolve(IEvent @event) |
| 57 | +{ |
| 58 | + return @event switch |
| 59 | + { |
| 60 | + AccountClosed e => When(e), |
| 61 | + AccountOpened e => When(e), |
| 62 | + MoneyDeposited e => When(e), |
| 63 | + MoneyWithdrawn e => When(e), |
| 64 | + _ => this, // tolerant evolve: unknown events leave the state unchanged |
| 65 | + }; |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +A few things to notice: |
| 70 | + |
| 71 | +- **Dispatch is a `switch`, not reflection.** A command without a `Decide` isn't in the switch. Analyzer SF0006 warns about it at build time, and startup rejects it. |
| 72 | +- **`Evolve` ignores events it doesn't know.** Analyzer SF0005 warns when your `Decide` produces an event that has no `When`, because that event would never change the state. |
| 73 | +- **Lists are sorted.** Sorting makes the output deterministic, so review diffs stay small. |
| 74 | + |
| 75 | +### Example: process manager correlation |
| 76 | + |
| 77 | +`CorrelateBy` can return the id type itself, or a `string` that is parsed into the id. If the string doesn't parse, the message isn't correlated: |
| 78 | + |
| 79 | +```csharp |
| 80 | +case global::Bank.Transfers.TransferRequested m: id = CorrelateBy(m); return true; |
| 81 | +case global::Text.CaseOpened m: return global::Text.CaseId.TryParse(CorrelateBy(m), out id); |
| 82 | +``` |
| 83 | + |
| 84 | +## Analyzers that guard the generated code |
| 85 | + |
| 86 | +Some diagnostics come from the same package (doc 03 §9): |
| 87 | + |
| 88 | +| Id | Severity | Meaning | |
| 89 | +|----|----------|---------| |
| 90 | +| SF0001 / SF0002 | Error | A message has no `[MessageType]`, or a name and version are declared twice | |
| 91 | +| SF0003 | Error | The command's target id member is missing or ambiguous (use `[AggregateId]`) | |
| 92 | +| SF0004 / SF0007 / SF0009 | Error / Error / Warning | Purity: `When` with side effects, an async `Decide`, or a non-deterministic API in a pure method | |
| 93 | +| SF0005 | Warning | `Decide` produces an event that has no `When` | |
| 94 | +| SF0006 | Warning | A command has no `Decide` or handler | |
| 95 | +| SF0008 | Error | An aggregate or process manager has the wrong shape (it must be a `sealed partial record` with `init` properties) | |
| 96 | +| SF0010 | Error | A message or state type is missing from the module's `JsonSerializerContext`. **Code fix:** *Add `[JsonSerializable(typeof(T))]`* | |
| 97 | +| SF0014 | Error | A command is handled locally and also routed with `routing.Command<T>().To(…)` (ADR-007) | |
| 98 | + |
| 99 | +## Reviewing changes |
| 100 | + |
| 101 | +Generated output is reproducible: the same sources always produce the same files. In this repository, the Bank sample's output is also kept as an approved snapshot (GEN-39). To see what a domain change does to the generated code, build and diff the `obj/…/generated` folder, or let the snapshot test show the change. |
| 102 | + |
| 103 | +The generator is incremental. An edit that doesn't touch a SourceFlow type (`[Aggregate]`, `[Projection]`, `[ProcessManager]`, `[MessageType]`, `[StronglyTypedId]` or a module) produces no new generator work (GEN-38). |
0 commit comments