Documentation section: Configuration
ER Diagram Styling, Layout and Descriptions
The Entity Framework Core ER diagram can be styled by table, column, type and relationship. You can also change how it is laid out and how it moves, and show a description for each table and column. This page owns that behaviour; Entity Framework Core ER Diagrams covers enabling the diagram itself.
Everything here is set on AspireC4EfDiagramOptions, in the configure callback of
WithEntityFrameworkDiagram() or in the AspireC4:EntityFramework configuration section:
builder.AddAspireC4() .WithEntityFrameworkDiagram(configure: options => options .WithTableStyle("Order*", style => style.WithAccent("#dc2626", "#f87171").WithBadge("SALES")) .WithTypeStyle("decimal", style => style.WithAccent("#16a34a")) .WithColumnStyle("Email", style => style.WithBadge("PII").WithTooltip("Personal data")) .WithLayout(ErdLayoutDirection.Right, layerSpacing: 160) .WithEdgeStyle(ErdEdgeStyle.SmoothStep) .WithDescriptions() .WithLegend());The interactive viewer applies all of it. Mermaid, d2 and DBML apply what their formats can express, listed in What each renderer applies.
From TypeScript, Go and Python
Section titled “From TypeScript, Go and Python”The same methods are on the options object a polyglot AppHost’s withEntityFrameworkDiagram callback
receives, in each language’s spelling. The style callbacks take an ErdElementStyle or ErdStyleRule
handle, and optional arguments become an options object, an options struct or keyword arguments:
await c4.withEntityFrameworkDiagram({ configure: async (opts) => { await opts .withTableStyle("Order*", async (s) => { await s.withAccent("#dc2626", { dark: "#f87171" }).withBadge("SALES"); }) .withTypeStyle("decimal", async (s) => { await s.withAccent("#16a34a"); }) .withContextPalette(["#2563eb", "#16a34a", "#d97706"]) .withLayout(ErdLayoutDirection.Right, { layerSpacing: 160 }) .withEdgeStyle(ErdEdgeStyle.SmoothStep) .withDescriptions() .withLegend(); },});c4.WithEntityFrameworkDiagram(&aspire.WithEntityFrameworkDiagramOptions{ Configure: func(opts aspire.AspireC4EfDiagramOptions) { opts. WithTableStyle("Order*", func(s aspire.ErdElementStyle) { s.WithAccent("#dc2626", &aspire.WithAccentOptions{Dark: ptr("#f87171")}).WithBadge("SALES") }). WithContextPalette([]string{"#2563eb", "#16a34a", "#d97706"}). WithLayout(aspire.ErdLayoutDirectionRight, &aspire.WithLayoutOptions{LayerSpacing: ptr(160)}). WithDescriptions() },})def er_diagram(opts: AspireC4EfDiagramOptions) -> None: opts.with_table_style("Order*", order_style).with_layout("Right", layer_spacing=160).with_descriptions()
def order_style(s: ErdElementStyle) -> None: s.with_accent("#dc2626", dark="#f87171").with_badge("SALES")Three things are C#-only, because a binding cannot express them:
- the style callbacks
OnTableStyle,OnColumnStyleandOnRelationshipStyle, which run against model types the bindings do not see; - an
ErdStyleRulebuilt up front and passed toWithStyle(ErdStyleRule); use the callback form,withStyle(rule => …); - context colours with a separate dark-theme value.
withContextPalettetakes strings, each used in both themes; it isWithContextPaletteColoursin C#.
Rules and light-and-dark context colours can still be set from any language through configuration, which every AppHost reads; the callbacks cannot, since they are code.
Styling
Section titled “Styling”Style rules
Section titled “Style rules”A rule matches elements by pattern and gives each match a style. Each pattern is optional, and a
pattern you leave unset matches anything. Patterns are case-insensitive: * matches any run of
characters and ? matches one.
| Pattern | Matches |
|---|---|
Context |
the DbContext’s short or full type name |
Table |
the table name, or the entity’s short or full CLR type name |
Column |
the column name |
Type |
the column’s store type with or without its size (decimal and decimal(18,2) both match decimal(18,2)), its domain type (OrderId), its CLR type, or its kind of domain type (enum, union, ValueObject) |
The shortcuts cover the common cases:
options.WithTableStyle("Audit*", s => s.WithLineStyle(ErdLineStyle.Dashed));options.WithColumnStyle("*Id", s => s.WithForeground("#64748b"));options.WithColumnStyle("Email", s => s.WithBadge("PII"), table: "Customers");options.WithTypeStyle("enum", s => s.WithItalic());WithStyle takes any combination of patterns:
// The decimal columns of every order tableoptions.WithStyle(rule => rule.ForTable("Order*").ForType("decimal").WithAccent("#b45309", "#f59e0b"));
// Every table that has a TenantId column, rather than the column itselfoptions.WithStyle(rule => rule.ForColumn("TenantId").ForTables().WithBadge("TENANT"));
// Every relationship with Customers at either endoptions.WithStyle(rule => rule.ForTable("Customers").ForRelationships().WithLineStyle(ErdLineStyle.Dotted));What a rule styles depends on its target:
| Target | Set by | Styles |
|---|---|---|
Auto (the default) |
WithTableStyle, WithColumnStyle, WithTypeStyle |
columns when the rule names a column or a type, otherwise tables |
Table |
ForTables() |
tables; a column or type pattern then selects the tables that have a matching column |
Column |
Target = ErdStyleTarget.Column |
columns |
Relationship |
ForRelationships() |
relationships with a matching table at either end and a matching foreign-key column |
Rules apply in the order you add them. When several rules match one element, a later rule overrides only the properties it sets, so a broad rule followed by a narrow one works as you would expect:
options .WithTableStyle("*", s => s.WithBold()) // every table bold .WithTableStyle("Orders", s => s.WithAccent("#dc2626")); // Orders also red, and still boldWhat a style sets
Section titled “What a style sets”| Property | Fluent method | Table | Column | Relationship |
|---|---|---|---|---|
Accent |
WithAccent(light, dark?) |
header band and border | bar beside the row | line colour |
Background |
WithBackground(light, dark?) |
card body | row | label |
Foreground |
WithForeground(light, dark?) |
header text | column name | label text |
Bold / Italic |
WithBold() / WithItalic() |
header text | column name | label text |
LineStyle |
WithLineStyle(Solid | Dashed | Dotted) |
border | not used | line |
Badge |
WithBadge("PII") |
shown in the header | shown beside the key badges | not used |
Tooltip |
WithTooltip("…") |
added to the header’s tooltip | added to the row’s tooltip | not used |
A table’s accent replaces its context colour on the card. The relationships that start from it, where it is the principal, take the accent too, unless a relationship rule sets their colour. The context container keeps the context’s colour.
Colours for light and dark
Section titled “Colours for light and dark”Every colour has a light value and a dark value. Give one value to use it in both themes, or both to have the viewer switch as its theme changes. Whichever value you leave out falls back to the other:
style.WithAccent("#2563eb"); // both themesstyle.WithAccent("#2563eb", "#60a5fa"); // light, darknew ErdColour(null, "#60a5fa"); // dark given, used for light tooThe interactive viewer accepts any CSS colour: hex (#2563eb, #fff, #2563eb80), a named colour,
or rgb(), hsl(), oklch() and the other colour functions. Mermaid, d2 and DBML have no theme
switch and accept only hex, so they draw in the light value when it is hex. A non-hex colour is
not written to those formats, so prefer hex for a style that should reach every renderer.
Style callbacks
Section titled “Style callbacks”A rule matches by name. A callback can style an element from anything in the model. Callbacks run after the rules for every table, column and relationship. Each one gets the element and the style the rules produced, and changes that style in place:
options // Wide tables stand out, so they are worth a second look .OnTableStyle(ctx => { if (ctx.Table.Columns.Count > 15) { ctx.Style.WithBadge($"{ctx.Table.Columns.Count} cols").WithAccent("#b45309"); } }) // Every foreign key, wherever it is .OnColumnStyle(ctx => { if (ctx.Column.IsForeignKey) { ctx.Style.WithForeground("#2563eb"); } }) // Optional relationships are drawn dashed .OnRelationshipStyle(ctx => { if (!ctx.ForeignKey.IsRequired) { ctx.Style.WithLineStyle(ErdLineStyle.Dashed); } });| Callback | Context | Gives you |
|---|---|---|
OnTableStyle |
ErdTableStyleContext |
Model, DbContext, Table, Style |
OnColumnStyle |
ErdColumnStyleContext |
Model, DbContext, Table, Column, Style |
OnRelationshipStyle |
ErdRelationshipStyleContext |
Model, DbContext, Dependent, Principal, ForeignKey, Style |
Callbacks run every time the diagram is regenerated: on startup, and whenever a contributing project
restarts with a changed model. A style computed from the model therefore follows the model as it
changes, with no restart of the AppHost. A callback can run more than once per regeneration, because
image export renders separately, so keep callbacks free of side effects. An exception from a callback
is rethrown as an InvalidOperationException that names the element it failed on.
Callbacks run in the AppHost, not in the browser. The viewer receives only the result.
Styles from configuration
Section titled “Styles from configuration”Rules are plain data, so they can live in appsettings.json with the rest of the options. Callbacks
can only be set in code.
{ "AspireC4": { "EntityFramework": { "Styles": [ { "Table": "Orders", "Style": { "Accent": { "Light": "#dc2626", "Dark": "#f87171" }, "Bold": true } }, { "Type": "decimal", "Style": { "Badge": "MONEY" } } ], "ContextPalette": [ { "Light": "#0f766e" }, { "Light": "#7c3aed" } ], "LayoutDirection": "Right", "ShowDescriptions": true } }}Context colours
Section titled “Context colours”Each DbContext is drawn in a colour from a palette of six. WithContextPalette replaces the palette,
and the colours are cycled in order:
options.WithContextPalette(new ErdColour("#0f766e", "#2dd4bf"), new ErdColour("#7c3aed", "#a78bfa"));
// One colour per context, used in both themes; the form TypeScript, Go and Python call as withContextPalette.options.WithContextPaletteColours("#0f766e", "#7c3aed");ErdColour.IsValid(value) reports whether a string is a colour these accept, so a value from elsewhere
can be checked before it is used.
Mermaid uses the palette for its per-context fills, deriving each fill from the colour the way the built-in pairs are derived.
Layout
Section titled “Layout”| Property | Fluent method | Default | Applies to |
|---|---|---|---|
LayoutDirection |
WithLayout(direction, …) |
Down |
the viewer, d2 and Mermaid. Down, Right, Up or Left |
NodeSpacing |
WithLayout(…, nodeSpacing:) |
72 |
pixels between neighbouring tables |
LayerSpacing |
WithLayout(…, layerSpacing:) |
120 |
pixels between related tables, along the direction. This gap carries the relationship labels |
ContextSpacing |
WithLayout(…, contextSpacing:) |
88 |
pixels between context containers |
EdgeStyle |
WithEdgeStyle(style) |
Bezier |
the viewer. Bezier, SmoothStep, Step or Straight |
The spacing settings apply to the interactive viewer. d2 and Mermaid lay themselves out and take only
the direction. Negative spacing throws ArgumentOutOfRangeException.
Right suits a wide screen and a long chain of relationships. In a sideways layout a table’s
relationship to itself hangs below its card rather than beside it, because both sides of the card
carry other relationships. The space below the card is reserved, so the arc’s label clears the next
table down.
Animation and interaction
Section titled “Animation and interaction”| Property | Fluent method | Default | What it does |
|---|---|---|---|
EdgeAnimation |
WithAnimation(edges, …) |
Normal |
how fast relationship lines flow toward their many end: Off, Slow, Normal or Fast |
AnimateTransitions |
WithAnimation(…, transitions:) |
true |
tables glide, rather than jump, when the viewer re-arranges them |
HighlightOnHover |
set the property | true |
hovering a table picks out its relationships and the tables they reach, and fades the rest |
| — | WithoutAnimation() |
— | turns off flowing lines and gliding tables together |
A browser that asks for reduced motion stops both animations. The reader can override that in the viewer’s Motion setting. A search outranks the hover highlight: while a search is active, hovering changes nothing.
Viewer defaults
Section titled “Viewer defaults”These set where the viewer starts. The reader can still change each one in the viewer’s settings.
| Property | Fluent method | Default |
|---|---|---|
Theme |
WithViewerDefaults(theme, …) |
Auto (follow the operating system), Light or Dark |
ViewerBackground |
WithViewerDefaults(…, background:) |
Lines, Dots, Cross or None |
TableDisplay |
WithViewerDefaults(…, tables:) |
Columns, or Names for headers only |
ShowLegend |
WithLegend() |
false. A panel explaining the context colours, the key badges and every badge your styles add |
ShowTooltips |
set the property | true. Hovering a column or a table header shows its CLR type, store type, length, nullability, keys, comment, description and any style tooltip |
The viewer remembers a reader’s choices in the browser. Each choice is stored with the default it was made against. If you later change that default in the AppHost, the new default applies again, so a choice made under the old default never hides a new configuration. A choice made against an unchanged default survives reloads as before.
Descriptions
Section titled “Descriptions”Tables and columns can show a description. This is off by default; WithDescriptions() turns it
on.
options.WithDescriptions(); // every sourceoptions.WithDescriptions(ErdDescriptionSources.XmlDocumentation); // only XML documentationA description comes from the first source that has one, in this order:
| Order | Source (ErdDescriptionSources) |
Read from |
|---|---|---|
| 1 | Attributes |
[Description("…")], then [Display(Description = "…")], then [DisplayName("…")], on the entity type or property |
| 2 | XmlDocumentation |
the <summary> of the entity type or property. A positional record property uses the record’s <param> for it |
| 3 | Comments |
the database comment, from [Comment("…")] or HasComment("…") |
An attribute is written for display, so it comes first. A comment is written for the database, so it
is the fallback. References in a summary keep their short name (<see cref="Order"/> reads Order),
and a summary wrapped over several lines reads as one.
/// <summary>An order a customer has placed.</summary>public sealed class Order{ /// <summary>Including tax, in the order's currency.</summary> public decimal Total { get; set; }
[Display(Description = "Where the order is in its lifecycle")] public OrderStatus Status { get; set; }}Each way of reading the model records all three sources. They read XML documentation differently:
| Source | XML documentation |
|---|---|
Analyzer (AspireC4.EntityFrameworkCore) |
read from source, whether or not the project generates a documentation file |
| Metadata reader (the default) | read from the documentation file beside the assembly, so the project needs <GenerateDocumentationFile>true</GenerateDocumentationFile> |
| Build-time dump | the same documentation file |
Attributes and comments need nothing extra. Entity-level ToTable(t => t.HasComment(…)) is visible
only to the build-time dump, and [Comment] on the entity class to all three.
What each renderer shows:
| Renderer | Table description | Column description |
|---|---|---|
| Interactive | a line under the table name | a column on each card, capped in width, with the full text as its tooltip |
| Mermaid | not shown: an entity has no note | added to the attribute’s comment |
| DBML | leads the table’s Note |
added to the column’s note |
| d2 | the table’s tooltip |
not shown: a sql_table row has no room |
In the viewer, the Descriptions setting switches them on and off. It appears only when the model
has descriptions. Descriptions are always sent to the viewer, and ShowDescriptions sets whether they
start shown.
The model keeps the three sources apart, so a renderer or a test can tell where a description came
from: EfTable and EfColumn each carry Description (the attributes), Documentation (the XML
summary) and, for tables, Comment, with a column’s database comment on EfColumn.Comment. The
description shown is chosen from them by DescriptionSources when the diagram is rendered. On the d2
side, D2Table.Style, D2Table.Tooltip and D2Edge.Style carry the resolved style and description
into the d2 output.
What each renderer applies
Section titled “What each renderer applies”| Interactive | Mermaid | d2 | DBML | |
|---|---|---|---|---|
| Table accent | ✓ | stroke, with a washed fill | header band | headercolor |
| Table background, foreground | ✓ | ✓ | background as row fill, foreground as text | — |
| Bold, italic, line style | ✓ | ✓ | ✓ | — |
| Column styles | ✓ | — | — | — |
| Relationship styles | ✓ | — | line colour, dash, bold, italic | — |
| Badges, tooltips | ✓ | — | table tooltip | — |
| Dark-theme colours | ✓ | — (light) | — (light) | — (light) |
| Layout direction | ✓ | direction |
direction |
— |
| Spacing, edge style, animation, viewer defaults | ✓ | — | — | — |
| Descriptions | ✓ | column comment | table tooltip | notes |
An unstyled diagram is unchanged in every format. The text formats are written exactly as they were before styling existed. Exported images re-render when only a style changes, because the export stamp includes the styling.
Options reference
Section titled “Options reference”| Property | Default | Fluent method |
|---|---|---|
Styles |
[] |
WithStyle, WithTableStyle, WithColumnStyle, WithTypeStyle |
TableStyleCallbacks / ColumnStyleCallbacks / RelationshipStyleCallbacks |
[] |
OnTableStyle, OnColumnStyle, OnRelationshipStyle |
ContextPalette |
[] (built-in six) |
WithContextPalette |
LayoutDirection |
Down |
WithLayout |
NodeSpacing / LayerSpacing / ContextSpacing |
72 / 120 / 88 |
WithLayout |
EdgeStyle |
Bezier |
WithEdgeStyle |
EdgeAnimation |
Normal |
WithAnimation, WithoutAnimation |
AnimateTransitions |
true |
WithAnimation, WithoutAnimation |
HighlightOnHover |
true |
— |
Theme / ViewerBackground / TableDisplay |
Auto / Lines / Columns |
WithViewerDefaults |
ShowLegend |
false |
WithLegend |
ShowTooltips |
true |
— |
ShowDescriptions |
false |
WithDescriptions |
DescriptionSources |
All |
WithDescriptions(sources) |