diff --git a/.github/skills/erd-viewer/SKILL.md b/.github/skills/erd-viewer/SKILL.md
new file mode 100644
index 0000000..6488790
--- /dev/null
+++ b/.github/skills/erd-viewer/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: erd-viewer
+description: Verifies the generated Entity Framework ER diagram viewer in a real browser. Use this skill when asked to run, drive, screenshot or visually check the ER diagram, the interactive viewer, or the Mermaid preview — or after changing anything under src/src/EntityFrameworkCore/Assets/.
+---
+
+## Verifying the ER diagram viewer
+
+The interactive viewer is the default renderer and it is **all browser**: ELK layout, card measurement,
+edge markers, search, theming and the complex value-object folds only run once a browser has loaded
+`app.js`. A green `just test` says nothing about any of it — the C# suite stops at the model JSON.
+
+Do **not** hand-roll a driver. There is already a Playwright harness.
+
+### The one command
+
+```sh
+just erd-check
+```
+
+That recipe does both halves: `scripts/erd-vendor.mts` populates `artifacts/erd-viewer-check/vendor`,
+then `scripts/erd-viewer-check.mts` assembles the viewer from source, serves it, drives it in Chromium
+and prints one `ok`/`FAIL` line per check. It exits non-zero if any check failed.
+
+It defaults to `src/src/TestAppHost/.aspirec4/erd/schema.gen.json` as its model. Pass another:
+
+```sh
+just erd-check artifacts/some-other-model.json
+just erd-mermaid-check # the Mermaid preview instead
+```
+
+Prerequisite, once per machine:
+
+```sh
+bunx playwright install chromium
+```
+
+### Getting a model to check against
+
+The default model is whatever the sample AppHost last wrote. If it is missing or stale, regenerate it:
+
+```sh
+dotnet run --project src/src/TestAppHost
+```
+
+Wait for `src/src/TestAppHost/.aspirec4/erd/schema.gen.json` to appear, then stop the AppHost. Stopping
+it by killing the process leaves its containers running — `docker ps` and remove them, or they hold
+ports the next run wants. `.aspirec4/` is gitignored.
+
+The suite needs a model with some variety in it, because several checks pick their own target from the
+model: a self-referencing table, a column name no table name contains, a context holding more than one
+table, and at least one flattened complex value object. The `TestAppHost.ComplexData` sample is built to
+supply all four — prefer it over a hand-trimmed model.
+
+### Reading the output
+
+Each line is one assertion with the measurement beside it, which is the point — `120px` tells you what
+the layout did, not merely that it passed. Artefacts land in `artifacts/erd-viewer-check/`:
+`viewer-check.png`, `viewer-check-dark.png`, and the exported `viewer-export.svg` / `.png`.
+
+Two traps that have bitten before:
+
+- **Screen pixels are not layout pixels.** The view is zoomed to fit, so a 56px layout offset is 28
+ screen pixels at scale 0.5. Every geometric assertion divides by the viewport scale first. A check
+ that forgets passes on a small schema and fails the moment the diagram grows.
+- **`fitContexts` pins a container's top to its topmost table.** Dragging that table carries the whole
+ container with it, so its offset within the context never changes. Assertions about dragging or about
+ a remembered arrangement must target a table that is *not* the topmost, or they hold vacuously.
+
+### Adding a check
+
+Add it to `scripts/erd-viewer-check.mts` next to the related section and let it run in the existing
+`for (const reducedMotion of ...)` loop. Use `check(name, ok, detail)` — never `throw` — so one failure
+does not hide the rest, and put the measurement in `detail`.
+
+Derive targets from the model rather than hard-coding a table name, the way the existing column-search
+check does, so the suite survives a change to the sample.
+
+### When a screenshot is the actual question
+
+If the task is "does this *look* right" rather than "does it work", the suite already writes
+`viewer-check.png` and `viewer-check-dark.png` on every run — read those first. Only reach for a bespoke
+Playwright script when you need an interaction the suite does not perform, and then put it in
+`scripts/` and delete it again, or add it to the suite properly.
+
+### Related
+
+- `just erd-vendor` rebuilds the viewer's bundled JavaScript; pass `--embed` to refresh the copies
+ shipped inside the package after a dependency bump.
+- `just erd-svg ` renders an emitted Mermaid `.mmd` to SVG through a one-shot container.
diff --git a/.gitignore b/.gitignore
index 2efc2cc..67df78d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -674,4 +674,14 @@ BenchmarkDotNet.Artifacts/
# AspireC4 generated diagram output (architecture diagram, ER diagram, and the ER viewer's bundled
# JS dependencies). Regenerated on every AppHost run, and the LikeC4 model embeds ephemeral localhost
# ports, so tracking it guarantees a dirty tree after every run.
-**/.aspirec4/
\ No newline at end of file
+#
+# The exported images are the exception, and are tracked deliberately: they are the artefact the
+# export exists to produce, and a diagram that is reviewable in a pull request is worth having in
+# source control. Written only when the diagram actually changes, so they do not churn — and the
+# stamp beside them ignores the ephemeral ports that would otherwise redraw them on every run.
+# Note the trailing /* rather than /: git will not descend into an excluded directory, so the
+# children have to be excluded individually for the re-include below to be reachable.
+**/.aspirec4/*
+!**/.aspirec4/images/
+# The stamp recording what the images were rendered from is a local cache, not documentation.
+**/.aspirec4/images/.aspirec4-*
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index c549ddd..1e1ad44 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,22 @@ just test-e2e-cli # All local CLI runtimes only
just test-e2e-npm # Single CLI runtime (also -pnpm, -yarn, -bun, -deno)
```
+### ER diagram viewer
+
+The interactive viewer under `src/src/EntityFrameworkCore/Assets/viewer/` only runs in a browser, so
+`just test` proves nothing about it. Drive it with Playwright instead — **never hand-roll a driver**:
+
+```sh
+just erd-check # Drive the viewer in Chromium and assert it renders, lays out and searches
+just erd-mermaid-check # The same for the Mermaid preview
+just erd-vendor # Rebuild the viewer's bundled JavaScript (--embed refreshes the shipped copies)
+just erd-svg # Render an emitted Mermaid .mmd to SVG in a one-shot container
+```
+
+`erd-check` defaults to the model at `src/src/TestAppHost/.aspirec4/erd/schema.gen.json`, written by
+`dotnet run --project src/src/TestAppHost`. Requires `bunx playwright install chromium` once. See the
+`erd-viewer` skill in `.github/skills/` before changing the viewer or its checks.
+
### Other
```sh
@@ -312,6 +328,12 @@ gitignored; `skills-lock.json` is the tracked record of what was installed there
own skills are never installed into it - that would leave two copies to drift apart. Read them at
their authored path, `skills//SKILL.md`.
+`.github/skills/` is a third, separate place: skills about working *in* this repository, which would
+be meaningless to a consumer who installed the published set. `release` and `erd-viewer` live there.
+A skill that tells you how to run this repo's own tooling belongs in `.github/skills/`, never in
+`skills/` - `SkillTests` requires everything under `skills/` to carry the `purview-aspirec4` prefix
+because those names land in a directory shared with every skill a developer has installed.
+
```bash
npx skills add purview-dev/aspirec4
```
diff --git a/README.md b/README.md
index 73ad0c3..6ea74f8 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,11 @@ Configure the diagram through `AspireC4DiagramOptions`:
| `HideFromDashboard` | `false` | Hide the LikeC4 sidecar from the Aspire dashboard |
| `DashboardLinkDisplayName` | `"Architecture Diagram"` | Name used for the diagram link when hidden from the dashboard |
| `IncludeAspireDashboardLinks` | `true` | Add Aspire dashboard links to diagram elements |
+| `ExportImages` | `true` | Write every view out as an image whenever the model changes — see [Export the views as images](#export-the-views-as-images) |
+| `ImageFormats` | `{Png}` | `Png` and/or `Jpg`. **No SVG** — `likec4 export` does not offer one |
+| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | Where images are written; relative paths resolve against the AppHost directory. Shared with the ER diagram |
+| `ImageExportTimeoutSeconds` | `300` | How long to wait for one `likec4 export` invocation |
+| `ContainerRuntimeCommand` | `"docker"` | Runtime for the one-shot export container; `podman` where that is what Aspire uses |
## Common options
@@ -97,6 +102,91 @@ builder.AddAspireC4(options => options.WithHMRDisabled());
The LikeC4 sidecar is excluded automatically. Set `WithIncludeAspireC4InternalResource(true)` in the options callback if you want to inspect it.
+### Export the views as images
+
+On by default. Every view is written out as a PNG whenever the generated model changes, so a diagram can
+be attached to a pull request or pasted into a wiki without running the server.
+
+**Both diagrams export into one folder**, `./.aspirec4/images/`, so there is a single place to look:
+
+```text
+apphost/.aspirec4/images/
+ architecture-index.png <- architecture diagram, one file per view
+ architecture-services.png
+ schema.svg <- ER diagram
+ schema.png
+```
+
+The architecture diagram's files carry an `architecture-` prefix, because `likec4 export` names each
+file after its view id and a bare `index.png` says nothing in a shared folder. The ER diagram's row in
+the dashboard carries an **Images** property with the resolved path, and an **Open Diagram Images**
+command that opens the folder — the dashboard cannot navigate to a `file://` path itself, so the
+AppHost opens it for you.
+
+`ImageExportDirectory` is resolved from the **AppHost directory**, not from `OutputDirectory`, which is
+what lets both diagrams land in the same place. Setting it on only one of the two splits them apart.
+
+```csharp
+builder.AddAspireC4(options => options.WithoutImageExport()); // opt out
+builder.AddAspireC4(options => options
+ .WithImageExport(LikeC4ImageFormat.Png, LikeC4ImageFormat.Jpg)
+ .WithImageExportDirectory("docs/diagrams") // relative to the AppHost directory
+);
+```
+
+**There is no SVG option for the architecture diagram.** `likec4 export` renders by screenshotting each
+view in a headless browser and offers only `png` and `jpg`. The ER diagram *does* export SVG, because it
+renders through d2 instead.
+
+That headless browser has two consequences. Export takes tens of seconds and needs a Chromium: container
+mode (the default) gets one from the `ghcr.io/likec4/likec4` image, which already carries it, while
+`WithLocalCLI()` mode needs a Playwright Chromium installed on the host. And it runs in the background,
+so startup is never delayed. A failure is reported and leaves the generated `.c4` file untouched.
+
+#### When export actually runs
+
+Nothing is rendered — and **no container is started** — unless the output would differ:
+
+- **Unchanged model, same session.** The resource state churn that regenerates an identical model
+ exports nothing.
+- **Restart.** A stamp file beside the images records what they were rendered from, so restarting the
+ AppHost over an unchanged model runs nothing. Without it, every restart would re-render, because the
+ in-memory change detection starts empty each time.
+- **Changed formats, or deleted images.** Both re-export: the stamp covers the requested formats, and
+ is only trusted when the files it describes are still there.
+- **Publish.** `aspire publish` generates the model and manifest and exports nothing at all. An export
+ is fire-and-forget, so on publish it would be killed part-way through — and publish is expected to be
+ hermetic, which reaching for a container runtime a build agent may not have would break.
+
+#### Committing the images
+
+The images are the one piece of generated output worth tracking: a diagram that shows up in a pull
+request is documentation, and because export only runs when the diagram changes they do not churn.
+Ignore the generated directory but carve the images out of it:
+
+```gitignore
+# Note the trailing /* rather than /: git will not descend into an excluded directory, so the
+# children have to be excluded individually for the re-include to be reachable.
+**/.aspirec4/*
+!**/.aspirec4/images/
+# The stamp recording what the images were rendered from is a local cache, not documentation.
+**/.aspirec4/images/.aspirec4-*
+```
+
+The two diagrams differ in how well they cache, though both are stable in source control:
+
+- **ER diagram** — fully cached. Derived from your EF model alone, so restarting the AppHost over an
+ unchanged schema renders nothing at all. This is the one that matters most, since it is also the one
+ that can pull a browser image under `WithViewerFidelityExport()`.
+- **Architecture diagram** — re-rendered on each run, but to identical bytes. Its model is a picture of
+ a *running* system: the endpoint ports and the run-state tags settle during startup, so the model the
+ first export sees is not quite the one the last export sees. The stamp already ignores the ephemeral
+ ports; the remaining difference is the run states, and those genuinely change the picture, so they
+ are not normalised away. Measured across restarts the exported PNGs are byte-for-byte the same, so
+ git sees no change — the cost is a background render, not a dirty tree.
+
+Set `ContainerRuntimeCommand` to `podman` where that is the runtime Aspire itself is using.
+
## Upgrading from before 13.6
13.6 changed two things, both breaking:
@@ -252,6 +342,15 @@ aspirec4 # parent row, added only when there is more than one di
| `ViewerServerImageTag` | `null` (`1.29-alpine`) | Pin the `nginx` image tag used to serve the viewer |
| `HideFromDashboard` | `false` | Hide the d2 sidecar from the Aspire dashboard |
| `DashboardLinkDisplayName` | `"ER Diagram"` | Name used for the diagram link |
+| `ExportImages` | `true` | Write the diagram out as an image whenever it changes — see [Exporting the ER diagram as an image](#exporting-the-er-diagram-as-an-image) |
+| `ImageFormats` | `{Svg, Png}` | Formats to export. `WithImageExport(...)` |
+| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | Where images are written; relative paths resolve against the AppHost directory. Shared with the architecture diagram |
+| `D2Command` | `null` | A local `d2` binary to export with; `null` runs the container. Set by `WithLocalD2CLI()` |
+| `ContainerRuntimeCommand` | `"docker"` | Runtime for the one-shot export container; `podman` where that is what Aspire uses |
+| `ExportTimeoutSeconds` | `120` | How long to wait for one d2 invocation before abandoning it |
+| `UseViewerFidelityExport` | `false` | Render images through the viewer in a headless browser so they match its own export. Pulls a ~3.7 GB browser image; `Interactive` only |
+| `ViewerExportImage` | `null` | Override the browser image, including its tag |
+| `ViewerExportTimeoutSeconds` | `600` | How long to wait for a viewer-fidelity export, which may be pulling the image |
### Renderers
@@ -473,6 +572,61 @@ d2 ships as a Go binary. Unlike the LikeC4 sidecar, there is **no npm CLI fallba
`install.sh`, or `go install`) so it is on `PATH`, or pass an explicit path:
`WithLocalD2CLI("/opt/d2/bin/d2")`.
+### Exporting the ER diagram as an image
+
+On by default. `schema.svg` and `schema.png` are written to `./.aspirec4/images/` — the same folder the
+architecture diagram exports to — whenever the diagram changes. The name drops the `.gen` marker, which
+earns its place on a generated source file you hand-edit beside but not on an image.
+
+```csharp
+builder.AddAspireC4()
+ .WithEntityFrameworkDiagram(configure: options => options.WithoutImageExport());
+
+builder.AddAspireC4()
+ .WithEntityFrameworkDiagram(configure: options => options.WithImageExport(ErdImageFormat.Svg));
+```
+
+**Export always renders through d2, whatever `Renderer` is set to.** The interactive renderer is a
+browser application with no headless path, so an image of it could only be produced by driving a
+browser; d2 is the only format that both renders images itself and keeps column-level edges, so routing
+every renderer through it gives one toolchain and one appearance. Two things follow:
+
+- Export needs either the `d2lang/d2` container or a local `d2` binary. `WithLocalD2CLI()` sets
+ `D2Command` for you; set it directly to render locally while leaving the sidecar or viewer alone.
+ Where neither is available, call `WithoutImageExport()`.
+- `schema.gen.d2` is written alongside the diagram even for the other renderers, purely to be rendered.
+ It is byte-identical to what the `D2` renderer writes.
+
+Export runs in the background, so startup is never delayed, and only when it would change something — a
+stamp beside the images means a restart over an unchanged model runs nothing at all, not even a
+container. It is skipped entirely during `aspire publish`. See
+[When export actually runs](#when-export-actually-runs). Failures are logged to the diagram resource
+and leave the diagram itself untouched.
+
+Prefer SVG for a large schema — a raster of the whole thing is unreadable at any sensible size. The
+viewer also has **Save as SVG / PNG** buttons for exporting what is currently on screen.
+
+#### Matching the viewer exactly
+
+The d2 render is a *different diagram*, not a differently-styled one: d2 draws `sql_table` shapes with
+its own theme and layout, while the viewer draws React Flow cards with context colours, key badges,
+complex-type groups and crow's-foot markers. If the exported file must be the one the viewer's own
+**Save as SVG / PNG** control produces, opt into the viewer render:
+
+```csharp
+builder.AddAspireC4()
+ .WithEntityFrameworkDiagram(configure: options => options.WithViewerFidelityExport());
+```
+
+That loads the generated viewer in a headless browser and calls the very function the toolbar button
+calls, so the file is identical. It is **off by default** because the viewer only runs in a browser:
+turning it on pulls `mcr.microsoft.com/playwright` (around 3.7 GB) and makes an export take seconds
+rather than milliseconds. Point `ViewerExportImage` at a mirror or an image you have already cached if
+the default is inconvenient.
+
+It applies only to the `Interactive` renderer — the one that has a viewer. Any other renderer exports
+through d2 regardless, and says so in the log rather than failing.
+
### Overriding the output directory
Prefer the `configure` callback over configuration for `OutputDirectory`. The sidecar's bind mount is
@@ -806,3 +960,5 @@ should review the following changes when upgrading:
- [Homepage](https://purview.dev/projects/aspirec4/)
- [Documentation](https://purview.dev/docs/aspirec4/)
+
+
diff --git a/package.json b/package.json
index 1895230..04b4929 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "aspirec4",
- "version": "13.6.0-preview.2",
+ "version": "13.6.0-preview.3",
"license": "MIT",
"description": "Aspire LikeC4 Visualization - version manifest for CD pipeline",
"author": {
diff --git a/scripts/erd-viewer-check.mts b/scripts/erd-viewer-check.mts
index 39c5ac3..f2c899e 100644
--- a/scripts/erd-viewer-check.mts
+++ b/scripts/erd-viewer-check.mts
@@ -238,9 +238,13 @@ try {
: `${tightest.id} has ${tightest.pad}px`,
);
+ // The gap between stacked tables is where the relationship labels sit, so it has to clear a
+ // label rather than merely separate two borders. Tables no relationship connects are laid
+ // out as separate components and packed, a seam that needs its own spacing: at ELK's default
+ // of 20 those groups all but touch.
check(
"stacked tables stay visually separate",
- spacing.closest.gap >= 40,
+ spacing.closest.gap >= 100,
`${spacing.closest.pair} — ${spacing.closest.gap}px`,
);
@@ -284,6 +288,10 @@ try {
// A table's offset within its context box, which is what a remembered arrangement has to
// preserve — and what a reload must reproduce.
+ //
+ // Divided back out by the viewport scale, so the result is in layout pixels: the view is
+ // zoomed to fit, so a screen-pixel offset shrinks as the schema grows and any threshold
+ // against it would hold only for diagrams small enough to render at 1:1.
const offsetInContext = (target: any, id: string) =>
target.evaluate((wanted: string) => {
const node = document.querySelector(`.react-flow__node-entity[data-id="${wanted}"]`);
@@ -303,13 +311,48 @@ try {
if (!context) return null;
+ const viewport = document.querySelector(".react-flow__viewport")!;
+ const scale = viewport.getBoundingClientRect().width / viewport.offsetWidth;
const box = (context as HTMLElement).getBoundingClientRect();
- return { x: Math.round(n.left - box.left), y: Math.round(n.top - box.top) };
+ return {
+ x: Math.round((n.left - box.left) / scale),
+ y: Math.round((n.top - box.top) / scale),
+ };
}, id);
- const card = page.locator(".react-flow__node-entity").first();
- const draggedId = (await card.getAttribute("data-id"))!;
+ // Deliberately not the topmost table in its container: fitContexts pins a container's top to
+ // whichever table is highest, so dragging that one carries the whole container with it and
+ // its offset never changes — which would leave the reload check below passing whether or not
+ // anything was actually remembered.
+ const draggedId = (await page.evaluate(() => {
+ const cards = [...document.querySelectorAll(".react-flow__node-entity")].map((n) => ({
+ id: n.dataset.id ?? "?",
+ box: n.getBoundingClientRect(),
+ }));
+
+ for (const container of document.querySelectorAll(".react-flow__node-context")) {
+ const rect = container.getBoundingClientRect();
+ const own = cards.filter(
+ (n) =>
+ n.box.left >= rect.left &&
+ n.box.right <= rect.right &&
+ n.box.top >= rect.top &&
+ n.box.bottom <= rect.bottom,
+ );
+
+ if (own.length < 2) continue;
+
+ return own.reduce((lowest, n) => (n.box.top > lowest.box.top ? n : lowest)).id;
+ }
+
+ return null;
+ }))!;
+
+ check("a container holds more than one table to drag", draggedId !== null, draggedId ?? "none found");
+
+ const card = page.locator(`.react-flow__node-entity[data-id="${draggedId}"]`);
+ const origin = await offsetInContext(page, draggedId);
const start = (await card.boundingBox())!;
await page.mouse.move(start.x + 40, start.y + 12);
@@ -320,7 +363,11 @@ try {
const before = await offsetInContext(page, draggedId);
- check("a table can be dragged", (before?.y ?? 0) > 40, `offset ${before?.y ?? "?"}px in its context`);
+ check(
+ "a table can be dragged",
+ origin !== null && before !== null && before.y - origin.y > 40,
+ `offset ${origin?.y ?? "?"}px → ${before?.y ?? "?"}px in its context`,
+ );
check(
"the context box follows the table it holds",
@@ -371,6 +418,168 @@ try {
check("columns mode restores the columns", (await page.locator(".entity .col").count()) > 0);
+ // ── Complex value objects ─────────────────────────────────────────────────────────
+ //
+ // EF flattens a complex value object into one column per member, named {Property}_{Member},
+ // so a card otherwise shows a run of prefixed rows that says nothing about what they are.
+ // They are folded under the property that owns them, which only means anything if the fold
+ // opens, closes, survives a reload, and does not disturb the layout around it.
+
+ const groups = await page.locator(".entity .col.group").count();
+
+ if (groups === 0) {
+ check("the model flattens a complex value object", false, "no group rows — nothing to check");
+ } else {
+ const group = page.locator(".entity .col.group").first();
+ const groupCard = page.locator(".react-flow__node-entity", { has: page.locator(".col.group") }).first();
+ const groupCardId = (await groupCard.getAttribute("data-id"))!;
+
+ check("complex value objects are folded under their property", groups > 0, `${groups} group rows`);
+
+ check(
+ "a folded group starts closed",
+ (await page.locator(".entity .col.member").count()) === 0 &&
+ (await page.locator(".entity .col.group.open").count()) === 0,
+ );
+
+ // The count is what a closed group says about what it is holding: without it the row
+ // claims a value object and gives no reason to open it.
+ const closedLabel = await group.locator(".type").innerText();
+
+ check("a closed group reports how many members it holds", /\(\d+\)$/.test(closedLabel), closedLabel);
+
+ const widthBefore = (await groupCard.boundingBox())!.width;
+ const heightBefore = (await groupCard.boundingBox())!.height;
+
+ await group.locator(".chevron").click();
+ await page.waitForTimeout(350);
+
+ const members = await page.locator(".entity .col.member").count();
+
+ check("the chevron opens one group", members > 0, `${members} member rows`);
+
+ const openLabel = await group.locator(".type").innerText();
+
+ check(
+ "an open group drops the count",
+ !/\(\d+\)$/.test(openLabel) && openLabel.length > 0,
+ openLabel,
+ );
+
+ // A member of an open group is shown as its database type alone: the group row above it
+ // already names the value object, and repeating it on every member crowds out the one
+ // thing those rows exist to say.
+ const repeated = await page
+ .locator(".entity .col.member .type")
+ .evaluateAll((els, name) => els.map((e) => e.textContent ?? "").filter((t) => t.includes(name)), openLabel);
+
+ check(
+ "a member does not repeat its group's value object",
+ repeated.length === 0,
+ repeated.slice(0, 2).join(", ") || `members read as plain types beside ${openLabel}`,
+ );
+
+ // Members are indented so the card still reads as a list of the table's own columns.
+ const indented = await page.evaluate(() => {
+ const member = document.querySelector(".entity .col.member .col-name");
+ const column = document.querySelector(".entity .col:not(.member):not(.group) .col-name");
+ if (!member || !column) return null;
+
+ return Math.round(member.getBoundingClientRect().left - column.getBoundingClientRect().left);
+ });
+
+ check("members are indented beneath their property", (indented ?? 0) > 0, `${indented ?? "?"}px`);
+
+ const opened = (await groupCard.boundingBox())!;
+
+ // The card is measured as though every group were open, so opening one only ever changes
+ // its height. A width that moved would mean the arrangement around it has to shift too.
+ check(
+ "opening a group does not re-widen the card",
+ Math.abs(opened.width - widthBefore) < 2,
+ `${Math.round(widthBefore)}px → ${Math.round(opened.width)}px`,
+ );
+
+ check(
+ "opening a group makes room for the members",
+ opened.height > heightBefore + 2,
+ `${Math.round(heightBefore)}px → ${Math.round(opened.height)}px`,
+ );
+
+ // The open set rides with the saved arrangement, so a reload reopens what the reader left
+ // open rather than folding the card back up under them.
+ await page.reload({ waitUntil: "networkidle" });
+ await page.waitForSelector(".entity", { timeout: 20000 });
+
+ check(
+ "an opened group survives a reload",
+ (await page.locator(".entity .col.member").count()) > 0,
+ `${await page.locator(".entity .col.member").count()} member rows`,
+ );
+
+ // ── Expand all / Collapse all ─────────────────────────────────────────────────
+
+ const COMPLEX = '[aria-label="Complex value objects"]';
+
+ await chooseIn(page, COMPLEX, "Collapse all");
+ await page.waitForTimeout(350);
+
+ check(
+ "Collapse all folds every group",
+ (await page.locator(".entity .col.member").count()) === 0,
+ "no member rows",
+ );
+
+ await chooseIn(page, COMPLEX, "Expand all");
+ await page.waitForTimeout(350);
+
+ const allOpen = await page.locator(".entity .col.group.open").count();
+
+ check("Expand all opens every group", allOpen === groups, `${allOpen} of ${groups} open`);
+
+ await chooseIn(page, COMPLEX, "Collapse all");
+ await page.waitForTimeout(350);
+
+ // ── Search reaches a folded member ────────────────────────────────────────────
+ //
+ // A hit inside a closed group would otherwise be counted and then not shown. The groups
+ // opened this way are held apart from the reader's own, so clearing the search folds
+ // them back rather than leaving the card as the search left it.
+
+ const memberColumn = await page.evaluate((id) => {
+ const card = document.querySelector(`.react-flow__node-entity[data-id="${id}"]`);
+ const name = card?.querySelector(".col.group .col-name")?.textContent ?? "";
+
+ return name ? `${name}_` : "";
+ }, groupCardId);
+
+ if (memberColumn) {
+ // Searching the flattened column's own prefix can only be satisfied by a folded member.
+ await page.fill(".toolbar input", memberColumn);
+ await page.waitForTimeout(400);
+
+ check(
+ "a search match inside a folded group opens it",
+ (await page.locator(".entity .col.member").count()) > 0,
+ `searching "${memberColumn}"`,
+ );
+
+ check(
+ "the revealed member is marked as the hit",
+ (await page.locator(".entity .col.member.hit").count()) > 0,
+ );
+
+ await page.locator(".toolbar input").press("Escape");
+ await page.waitForTimeout(400);
+
+ check(
+ "clearing the search folds it back",
+ (await page.locator(".entity .col.member").count()) === 0,
+ "back to closed",
+ );
+ }
+ }
+
// ── Search ────────────────────────────────────────────────────────────────────────
//
// Search is the only way into a schema too large to read at a glance, so it is checked as
diff --git a/skills/purview-aspirec4-configuration/SKILL.md b/skills/purview-aspirec4-configuration/SKILL.md
index 50e2a8a..3b7a485 100644
--- a/skills/purview-aspirec4-configuration/SKILL.md
+++ b/skills/purview-aspirec4-configuration/SKILL.md
@@ -3,8 +3,8 @@ name: purview-aspirec4-configuration
description: >-
Use when tuning AspireC4DiagramOptions - the view and title settings, output directory and
generated file, the LikeC4 container tag and HMR, icon inference, Aspire metadata injection and
- dashboard links, run-state tags and styles, additional DSL files and image aliases, and the
- security note on embedding the Aspire token.
+ dashboard links, run-state tags and styles, additional DSL files and image aliases, exporting the
+ views as images on startup, and the security note on embedding the Aspire token.
metadata:
product: AspireC4
repository: purview-dev/aspirec4
@@ -124,6 +124,99 @@ puts passwords and secrets.
| `ImageAliases` | `{}` | alias definitions (keys begin with `@`) written to `imageAliases` in the generated config |
| `ConfigFileMetadata` | `{}` | extra metadata for the generated `likec4.config.json` |
+## Image export
+
+Every view is written out as an image whenever the generated model changes — on by default.
+
+| Property | Default | Description |
+| --- | --- | --- |
+| `ExportImages` | `true` | write each view out as an image when the generated model changes |
+| `ImageFormats` | `{Png}` | `Png` and/or `Jpg`. **There is no SVG** — see below |
+| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | where images are written; relative paths resolve against the **AppHost directory** |
+| `ImageExportTimeoutSeconds` | `300` | cap on one `likec4 export` invocation |
+| `ContainerRuntimeCommand` | `"docker"` | the runtime for the one-shot export container; set to `podman` where that is what Aspire uses |
+
+**Both diagrams export into the same folder**, `./.aspirec4/images/`, so there is one place to look
+rather than one per diagram:
+
+```text
+apphost/.aspirec4/images/
+ architecture-index.png <- architecture diagram, one file per view
+ architecture-services.png
+ schema.svg <- ER diagram
+ schema.png
+```
+
+The architecture diagram's files carry an `architecture-` prefix, because `likec4 export` names a file
+after its view id and a bare `index.png` says nothing in a shared folder. The ER diagram row in the
+dashboard carries an **Images** property with the resolved path and an **Open Diagram Images** command
+that opens the folder.
+
+Because the default is resolved from the AppHost directory rather than from `OutputDirectory`, setting
+`ImageExportDirectory` on only one of the two diagrams splits them apart again.
+
+**`likec4 export` has no SVG format.** It renders by screenshotting each view in a headless browser, and
+offers only `png` and `jpg`. For a vector, export the model and render it with another tool. The ER
+diagram *does* export SVG, because it renders through d2 — see `purview-aspirec4-entityframework`.
+
+Two consequences follow from the headless browser:
+
+- Export takes tens of seconds and needs a Chromium. Container mode (the default) gets one from the
+ `ghcr.io/likec4/likec4` image, which already carries it; **`WithLocalCLI()` mode needs a Playwright
+ Chromium installed on the host.**
+- It runs in the background, so startup is never delayed.
+
+Nothing is rendered, and **no container is started**, unless the output would differ:
+
+| Situation | Exports? |
+| --- | --- |
+| Identical model regenerated by state churn | no |
+| AppHost restarted over an unchanged model | no — a stamp file beside the images records what they were rendered from |
+| Model changed, or a format added | yes |
+| Images deleted | yes — the stamp is only trusted when the files it describes still exist |
+| `aspire publish` | **never** |
+
+Publish is skipped outright: an export is fire-and-forget, so it would be killed part-way through when
+publish exits, and publish is expected to be hermetic rather than reaching for a container runtime a
+build agent may not have.
+
+### Committing the images
+
+The images are the one piece of generated output worth tracking — a diagram that shows up in a pull
+request is documentation, and they do not churn because export only runs when the diagram changes.
+Ignore the generated directory but carve them out of it:
+
+```gitignore
+# /* rather than /: git will not descend into an excluded directory, so the children have to be
+# excluded individually for the re-include to be reachable.
+**/.aspirec4/*
+!**/.aspirec4/images/
+# The stamp recording what the images were rendered from is a local cache, not documentation.
+**/.aspirec4/images/.aspirec4-*
+```
+
+Both diagrams are stable in source control, but they cache differently:
+
+- **ER diagram** — fully cached. From the EF model alone, so a restart over an unchanged schema renders
+ nothing.
+- **Architecture diagram** — re-rendered on each run, to identical bytes. Its model is a picture of a
+ *running* system: ports and run-state tags settle during startup, so the first export sees a slightly
+ different model from the last. The stamp ignores the ephemeral ports; the run states are left in
+ because they genuinely change the picture. Measured across restarts the PNGs are byte-for-byte the
+ same, so git sees nothing — the cost is a background render, not a dirty tree.
+
+Failures are best-effort: they are reported and the generated `.c4` model is unaffected.
+
+```csharp
+builder.AddAspireC4(options => options.WithoutImageExport());
+builder.AddAspireC4(options => options
+ .WithImageExport(LikeC4ImageFormat.Png, LikeC4ImageFormat.Jpg)
+ .WithImageExportDirectory("docs/diagrams") // relative to the AppHost directory
+);
+```
+
+`WithImageExport()` with no format turns export off, the same as `WithoutImageExport()`.
+
## The fluent surface
```csharp
@@ -149,6 +242,8 @@ WithImageAliasFolder(string, string)
WithExcludedResourceType() WithoutExcludedResourceType()
WithIncludeAspireC4InternalResource(bool)
WithLegacyLayout() WithLikeC4ProjectFolder(string)
+WithImageExport(params LikeC4ImageFormat[])
+WithImageExportDirectory(string) WithoutImageExport()
```
## Related skills
diff --git a/skills/purview-aspirec4-entityframework/SKILL.md b/skills/purview-aspirec4-entityframework/SKILL.md
index dd0dd92..e241cfa 100644
--- a/skills/purview-aspirec4-entityframework/SKILL.md
+++ b/skills/purview-aspirec4-entityframework/SKILL.md
@@ -5,7 +5,7 @@ description: >-
installing AspireC4.Hosting.EntityFrameworkCore, calling WithEntityFrameworkDiagram, how the model is
discovered (assembly metadata, an analyzer descriptor, or the opt-in build-time dump), filtering and
excluding DbContexts, domain types (value objects and enums) and the DomainTypeDisplay option, the
- renderers, and the dashboard integration.
+ renderers, exporting the diagram as SVG and PNG on startup, and the dashboard integration.
metadata:
product: AspireC4
repository: purview-dev/aspirec4
@@ -143,6 +143,15 @@ Options bind from the **`AspireC4:EntityFramework`** section, applied on top of
| `ViewerServerImageTag` | `null` | pin the viewer `nginx` image tag |
| `HideFromDashboard` | `false` | hide the sidecar and surface it as a link |
| `DashboardLinkDisplayName` | `"ER Diagram"` | the link name when hidden |
+| `ExportImages` | `true` | write the diagram out as an image when it changes |
+| `ImageFormats` | `{Svg, Png}` | `Svg` and/or `Png` |
+| `ImageExportDirectory` | `null` (`./.aspirec4/images/`) | where images are written; relative paths resolve against the **AppHost directory**. Shared with the architecture diagram |
+| `D2Command` | `null` | a local `d2` binary to export with; `null` runs the container |
+| `ContainerRuntimeCommand` | `"docker"` | the runtime for the one-shot export container; `podman` where that is what Aspire uses |
+| `ExportTimeoutSeconds` | `120` | cap on one d2 invocation |
+| `UseViewerFidelityExport` | `false` | render through the viewer in a headless browser so images match its own export. Pulls a ~3.7 GB image; `Interactive` only |
+| `ViewerExportImage` | `null` | override the browser image, including its tag |
+| `ViewerExportTimeoutSeconds` | `600` | cap on one viewer-fidelity export |
The output path follows the architecture diagram: `WithLegacyLayout()` on `AddAspireC4` restores
`./erd/gen/` as well, because there is no separate ER switch. An `OutputDirectory` set on
@@ -167,6 +176,82 @@ builder.AddAspireC4().WithEntityFrameworkDiagram().WithLocalD2CLI();
d2 ships as a Go binary, so it must be on `PATH`; there is no npm fallback. Call `WithLocalD2CLI()`
**after** `WithEntityFrameworkDiagram()`.
+## Image export
+
+On by default, so a schema can go into a pull request or a wiki without opening the viewer. Images are
+written to **`./.aspirec4/images/`** — the same folder the architecture diagram exports to, so there is
+one place to look:
+
+```text
+apphost/.aspirec4/images/
+ schema.svg <- this diagram
+ schema.png
+ architecture-index.png <- architecture diagram
+```
+
+The name drops the `.gen` marker: `schema.gen` produces `schema.svg`, not `schema.gen.svg`. The marker
+earns its place on a generated source file sitting in a directory you also hand-edit, which an image in
+the shared folder never is. The dashboard row carries an **Images** property with the resolved path and
+an **Open Diagram Images** command that opens the folder.
+
+```csharp
+builder.AddAspireC4().WithEntityFrameworkDiagram(configure: options => options.WithoutImageExport());
+builder.AddAspireC4().WithEntityFrameworkDiagram(configure: options =>
+ options.WithImageExport(ErdImageFormat.Svg)
+);
+```
+
+`WithImageExport()` with no format turns export off, the same as `WithoutImageExport()`.
+
+**Export always renders through d2, whatever `Renderer` is set to.** The interactive renderer is a
+browser application with no headless path, so an image of it could only be produced by driving a
+browser; d2 is the only format that both renders images itself and keeps column-level edges. Two
+things follow:
+
+- Export needs either the `d2lang/d2` container or a local `d2` binary (`D2Command`, which
+ `WithLocalD2CLI()` sets for you). Where neither is available, call `WithoutImageExport()`.
+- `{FileName}.d2` is written alongside the diagram even for the other renderers, purely to be
+ rendered. It is identical to what the `D2` renderer writes.
+
+Export runs in the background, so startup is never delayed, and nothing is rendered — **no container is
+started** — unless the output would differ:
+
+| Situation | Exports? |
+| --- | --- |
+| Identical model regenerated | no |
+| AppHost restarted over an unchanged model | no — a stamp file beside the images records what they were rendered from |
+| Model changed, or a format added | yes |
+| Images deleted | yes — the stamp is only trusted when the files it describes still exist |
+| `aspire publish` | **never** |
+
+Publish is skipped outright: an export is fire-and-forget, so it would be killed part-way through when
+publish exits, and publish is expected to be hermetic rather than reaching for a container runtime a
+build agent may not have.
+
+Failures are best-effort: they are logged to the diagram resource and the diagram itself is unaffected.
+
+Prefer SVG for a large schema — a raster of the whole thing is unreadable at any sensible size. The
+viewer also has **Save as SVG / PNG** buttons for exporting what is currently on screen.
+
+### Matching the viewer exactly
+
+The d2 render is a **different diagram**, not a differently-styled one: d2 draws `sql_table` shapes with
+its own theme and layout, the viewer draws React Flow cards with context colours, key badges,
+complex-type groups and crow's-foot markers. To get the file the viewer's own export produces:
+
+```csharp
+builder.AddAspireC4()
+ .WithEntityFrameworkDiagram(configure: options => options.WithViewerFidelityExport());
+```
+
+This loads the generated viewer in a headless browser and calls the same function the toolbar button
+calls, so the output is identical. **Off by default**: it pulls `mcr.microsoft.com/playwright` (around
+3.7 GB) and an export takes seconds rather than milliseconds. `ViewerExportImage` overrides the image
+for a mirror or a cached one.
+
+Applies only to `Interactive`, the renderer that has a viewer. Any other renderer exports through d2
+regardless and logs why.
+
## Using the viewer
The interactive viewer is for reading a schema, not just looking at one.
@@ -191,3 +276,4 @@ The interactive viewer is for reading a schema, not just looking at one.
`purview-aspirec4-quickstart` for installing AspireC4 and running the architecture diagram,
`purview-aspirec4-configuration` for the LikeC4 options reference, and `purview-aspirec4-resources` for
per-resource labels, relationships and grouping.
+
diff --git a/src/src/AspireC4/AspireC4DiagramOptions.cs b/src/src/AspireC4/AspireC4DiagramOptions.cs
index b4320f5..2cdc4be 100644
--- a/src/src/AspireC4/AspireC4DiagramOptions.cs
+++ b/src/src/AspireC4/AspireC4DiagramOptions.cs
@@ -1,5 +1,6 @@
using Aspire.Hosting.AspireC4.LikeC4.Icons;
using Aspire.Hosting.AspireC4.LikeC4.Models;
+using Aspire.Hosting.AspireC4.LikeC4.Runtime;
namespace Aspire.Hosting.AspireC4;
@@ -179,6 +180,79 @@ public sealed class AspireC4DiagramOptions
///
public bool CheckLatestImageVersion { get; set; } = true;
+ ///
+ /// When (default), every LikeC4 view is written out as an image each time the
+ /// generated model changes.
+ ///
+ ///
+ ///
+ /// The images land in , one file per view named after the view's
+ /// id, so a diagram can be attached to a pull request or pasted into a wiki without running the
+ /// server. Export runs in the background, so it never delays startup, and only when it would
+ /// actually change something: the resource state churn that regenerates an identical model exports
+ /// nothing, and a stamp beside the images means a restart runs nothing either — not even a
+ /// container. It is also skipped entirely during a publish, which generates its output and exits.
+ ///
+ ///
+ /// likec4 export screenshots each view in a headless browser, so this takes tens of seconds
+ /// and needs a Chromium. The default container mode gets one from the
+ /// ghcr.io/likec4/likec4 image, which already carries it;
+ /// mode needs a Playwright Chromium installed
+ /// on the host instead. Set to , or use
+ /// , to opt out.
+ ///
+ ///
+ public bool ExportImages { get; set; } = true;
+
+ ///
+ /// The formats written when is set. Defaults to
+ /// .
+ ///
+ ///
+ /// There is no SVG option: likec4 export offers only png and jpg, because it
+ /// renders by screenshotting the view rather than emitting vector output. Emptying this disables
+ /// export as surely as clearing . Populate with
+ /// .
+ ///
+ [System.Diagnostics.CodeAnalysis.SuppressMessage(
+ "Usage",
+ "CA2227:Collection properties should be read only",
+ Justification = "Settable for configuration binding and direct assignment in user code"
+ )]
+ public HashSet ImageFormats { get; set; } = [LikeC4ImageFormat.Png];
+
+ ///
+ /// Where exported images are written. Relative paths are resolved against the AppHost directory;
+ /// (the default) uses ./.aspirec4/images/.
+ ///
+ ///
+ /// The ER diagram writes to the same folder by default, so every image AspireC4 produces is in one
+ /// place rather than buried in whichever generated-output directory produced it. The architecture
+ /// diagram's files are prefixed architecture- to keep the two apart. Setting this on only one
+ /// of the two diagrams splits them again, which is why the default is resolved from the AppHost
+ /// directory rather than from .
+ ///
+ public string? ImageExportDirectory { get; set; }
+
+ ///
+ /// Maximum number of seconds to wait for one likec4 export invocation. Defaults to 300.
+ ///
+ ///
+ /// Much larger than , which caps the formatter: export
+ /// starts a LikeC4 server and a browser before it renders anything, so a cold run takes far longer
+ /// than a format pass. Export runs in the background, so this never caps startup.
+ ///
+ public int ImageExportTimeoutSeconds { get; set; } = 300;
+
+ ///
+ /// The container runtime used to run the one-shot export container. Defaults to docker.
+ ///
+ ///
+ /// Set to podman where that is the runtime Aspire itself is using. Ignored in local CLI mode,
+ /// which runs no container.
+ ///
+ public string ContainerRuntimeCommand { get; set; } = "docker";
+
///
/// Enables automatic icon inference for known resource types and technologies.
/// Defaults to .
diff --git a/src/src/AspireC4/AspireC4ImageExport.cs b/src/src/AspireC4/AspireC4ImageExport.cs
new file mode 100644
index 0000000..ec55027
--- /dev/null
+++ b/src/src/AspireC4/AspireC4ImageExport.cs
@@ -0,0 +1,54 @@
+namespace Aspire.Hosting.AspireC4;
+
+///
+/// The single directory both diagrams export their images to, and how it is resolved.
+///
+///
+///
+/// One folder for the whole integration rather than one per diagram: the images exist to be picked up
+/// and attached to something, which is a poor fit for hunting through two generated-output directories
+/// — and worse for the ER diagram, whose images would otherwise sit among the viewer's own
+/// index.html, app.js and vendor/.
+///
+///
+/// Resolved against the AppHost directory rather than either diagram's OutputDirectory, so the
+/// two cannot drift apart when only one of them is overridden. Shared with the EF Core package through
+/// InternalsVisibleTo.
+///
+///
+static class AspireC4ImageExport
+{
+ /// Where images are written when neither diagram configures a directory.
+ ///
+ /// Beneath the same .aspirec4/ root as everything else AspireC4 generates, so a consumer
+ /// still has exactly one directory to ignore in source control.
+ ///
+ internal const string DefaultDirectory = "./.aspirec4/images/";
+
+ ///
+ /// Prefix applied to the architecture diagram's images.
+ ///
+ ///
+ /// likec4 export names a file after its view id, which in a folder shared with the ER
+ /// diagram's images says nothing about where it came from — and an index view would produce a
+ /// bare index.png. The prefix also keeps the two diagrams from colliding on a common view name.
+ ///
+ internal const string ArchitecturePrefix = "architecture-";
+
+ /// Resolves the configured image directory to an absolute path.
+ ///
+ /// The configured directory, or /blank for .
+ /// A relative path is resolved against .
+ ///
+ /// The AppHost directory.
+ internal static string Resolve(string? configured, string baseDirectory)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(baseDirectory);
+
+ var directory = string.IsNullOrWhiteSpace(configured) ? DefaultDirectory : configured;
+
+ return Path.TrimEndingDirectorySeparator(
+ Path.GetFullPath(Path.IsPathRooted(directory) ? directory : Path.Combine(baseDirectory, directory))
+ );
+ }
+}
diff --git a/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs b/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs
index fa51c96..dc4ecfd 100644
--- a/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs
+++ b/src/src/AspireC4/Extensions/Aspire/Hosting/AspireC4DiagramOptionsExtensions.cs
@@ -2,6 +2,7 @@
using System.Diagnostics.CodeAnalysis;
using Aspire.Hosting.AspireC4.LikeC4.Icons;
using Aspire.Hosting.AspireC4.LikeC4.Models;
+using Aspire.Hosting.AspireC4.LikeC4.Runtime;
namespace Aspire.Hosting;
@@ -554,4 +555,68 @@ bool include
return options;
}
+
+ ///
+ /// Restricts image export to the listed formats, replacing the PNG default.
+ ///
+ ///
+ /// Also sets , so naming a format is enough to turn
+ /// export on. Passing no format turns it off, the same as .
+ ///
+ ///
+ /// The formats to export.
+ /// The same for further configuration.
+ ///
+ [AspireExport]
+ public static AspireC4DiagramOptions WithImageExport(
+ [NotNull] this AspireC4DiagramOptions options,
+ params LikeC4ImageFormat[] formats
+ )
+ {
+ ArgumentNullException.ThrowIfNull(formats);
+
+ options.ImageFormats = [.. formats];
+ options.ExportImages = formats.Length > 0;
+
+ return options;
+ }
+
+ /// Sets the directory exported images are written to.
+ ///
+ ///
+ /// Absolute, or relative to .
+ ///
+ /// The same for further configuration.
+ ///
+ [AspireExport]
+ public static AspireC4DiagramOptions WithImageExportDirectory(
+ [NotNull] this AspireC4DiagramOptions options,
+ string directory
+ )
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(directory);
+
+ options.ImageExportDirectory = directory;
+
+ return options;
+ }
+
+ ///
+ /// Stops the views being exported as images, leaving only the generated .c4 model.
+ ///
+ ///
+ /// Export drives a headless browser; see for what
+ /// that needs. This is how a consumer who cannot, or would rather not, pay for it opts out.
+ ///
+ ///
+ /// The same for further configuration.
+ [AspireExport]
+ public static AspireC4DiagramOptions WithoutImageExport([NotNull] this AspireC4DiagramOptions options)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+
+ options.ExportImages = false;
+
+ return options;
+ }
}
diff --git a/src/src/AspireC4/ImageExportStamp.cs b/src/src/AspireC4/ImageExportStamp.cs
new file mode 100644
index 0000000..d3d718e
--- /dev/null
+++ b/src/src/AspireC4/ImageExportStamp.cs
@@ -0,0 +1,119 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace Aspire.Hosting.AspireC4;
+
+///
+/// Records what the images in a directory were rendered from, so an export that would reproduce them
+/// byte for byte can be skipped before anything is run.
+///
+///
+///
+/// The in-memory "has the diagram changed" check cannot answer this on its own: it starts empty every
+/// time the AppHost does, so the first write of each run always looks like a change and would re-export
+/// images that are already correct on disk. For the viewer-fidelity path that means pulling and
+/// starting a multi-gigabyte browser container to produce files identical to the ones already sitting
+/// there.
+///
+///
+/// Modelled on the viewer's own .aspirec4-vendor stamp. Named per diagram because both diagrams
+/// now export into the same directory, so a single file would have them overwriting each other's.
+///
+///
+static partial class ImageExportStamp
+{
+ /// The stamp file for a diagram, named so it sorts away from the images themselves.
+ internal static string FileName(string diagram) => $".aspirec4-{diagram}-images";
+
+ ///
+ /// Hashes everything that decides what the images look like.
+ ///
+ /// The rendered source — the model or DSL the images are produced from.
+ ///
+ /// Every other input that changes the output: the formats, the file name, the renderer, and whether
+ /// the viewer or d2 is doing the rendering. A change to any of them has to re-export.
+ ///
+ internal static string Compute(string content, params string[] parts)
+ {
+ ArgumentNullException.ThrowIfNull(content);
+ ArgumentNullException.ThrowIfNull(parts);
+
+ var payload = string.Join("\u0000", [Normalise(content), .. parts]);
+
+ return Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(payload)));
+ }
+
+ ///
+ /// Removes the parts of a generated model that differ between runs without changing the picture.
+ ///
+ ///
+ /// The architecture model embeds the endpoint URLs Aspire allocated, and those ports are different
+ /// on every run. Hashing them verbatim would invalidate the stamp every single time, which for this
+ /// diagram means starting a LikeC4 server and a headless browser to redraw something that has not
+ /// changed. The port is replaced rather than the whole URL so that a host or a scheme actually
+ /// changing is still noticed.
+ ///
+ /// This does not make the architecture diagram fully cached across restarts, and is not meant to:
+ /// the run-state tags also settle during startup, and those genuinely change the picture, so
+ /// normalising them away would hide a real difference. The exported images come out byte-identical
+ /// either way; what is left is a background render, not changed output.
+ ///
+ ///
+ internal static string Normalise(string content) => EphemeralPort().Replace(content, ":");
+
+ [GeneratedRegex(@"(?<=://[^/\s""']+):\d{2,5}\b")]
+ private static partial Regex EphemeralPort();
+
+ ///
+ /// Whether already holds exactly these images.
+ ///
+ ///
+ /// Both halves matter. A matching stamp alone would skip the export after someone deleted the
+ /// images; the files existing alone would keep a stale image after the model changed.
+ ///
+ /// The images directory.
+ /// Which diagram's stamp to read.
+ /// The stamp the current inputs produce.
+ /// The files the export would write.
+ /// Cancelled on shutdown.
+ internal static async Task IsCurrentAsync(
+ string directory,
+ string diagram,
+ string stamp,
+ IEnumerable expected,
+ CancellationToken cancellationToken
+ )
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(directory);
+ ArgumentNullException.ThrowIfNull(expected);
+
+ if (!expected.All(File.Exists))
+ {
+ return false;
+ }
+
+ var path = Path.Combine(directory, FileName(diagram));
+
+ if (!File.Exists(path))
+ {
+ return false;
+ }
+
+ var existing = await File.ReadAllTextAsync(path, cancellationToken).ConfigureAwait(false);
+
+ return string.Equals(existing.Trim(), stamp, StringComparison.Ordinal);
+ }
+
+ /// Records the stamp, once the images it describes have actually been written.
+ ///
+ /// Written last for the same reason the vendor stamp is: a run interrupted part-way through leaves
+ /// no stamp, so the next one re-exports rather than trusting a half-written directory.
+ ///
+ internal static Task WriteAsync(
+ string directory,
+ string diagram,
+ string stamp,
+ CancellationToken cancellationToken
+ ) => File.WriteAllTextAsync(Path.Combine(directory, FileName(diagram)), stamp, cancellationToken);
+}
diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs
index 0592bf0..6079e1a 100644
--- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs
+++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.Disposable.cs
@@ -10,5 +10,7 @@ public void Dispose()
_debounceCts?.Dispose();
_debounceCts = null;
}
+
+ _exportGate.Dispose();
}
}
diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs
index f255e19..73f278d 100644
--- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs
+++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.FileGeneration.cs
@@ -55,7 +55,8 @@ async Task WriteC4FileAsync(DistributedApplicationModel appModel, CancellationTo
// is identical to what was last written. This prevents needless git noise when state
// changes bounce resources through transitional states that end up back where they started.
var newRawBody = StripHeader(dsl);
- if (!string.Equals(_lastRawBody, newRawBody, StringComparison.Ordinal))
+ var changed = !string.Equals(_lastRawBody, newRawBody, StringComparison.Ordinal);
+ if (changed)
{
_lastRawBody = newRawBody;
await File.WriteAllTextAsync(outputPath, dsl, cancellationToken);
@@ -93,6 +94,22 @@ async Task WriteC4FileAsync(DistributedApplicationModel appModel, CancellationTo
}
telemetry.LikeC4ModelWritten(outputPath);
+
+ // Gated on the same comparison as the write itself: exporting is expensive enough that it is
+ // worth doing only when there is a new model to render. Fire-and-forget, because the export
+ // starts a LikeC4 server and a browser and must not sit between the application and its startup.
+ // Never on publish, which generates the model and exits — see _isPublishMode.
+ if (ShouldExportImages(changed, opts.ExportImages, _isPublishMode))
+ {
+ // The same base directory the output and serve directories were resolved from, so the images
+ // land beside the ER diagram's rather than wherever this AppHost happens to have been started.
+ var appHostDirectory = Environment.CurrentDirectory;
+
+ _ = Task.Run(
+ () => ExportImagesAsync(outputDir, serveDir, appHostDirectory, newRawBody, cancellationToken),
+ cancellationToken
+ );
+ }
}
///
diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs
new file mode 100644
index 0000000..2911696
--- /dev/null
+++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.ImageExport.cs
@@ -0,0 +1,101 @@
+using Aspire.Hosting.AspireC4.LikeC4.Runtime;
+
+namespace Aspire.Hosting.AspireC4.Lifecycle;
+
+sealed partial class AspireC4LifecycleHook
+{
+ /// Serialises export runs so two invocations never write the same image at once.
+ readonly SemaphoreSlim _exportGate = new(1, 1);
+
+ ///
+ /// Whether this run is a publish rather than a run, in which case nothing is exported.
+ ///
+ ///
+ /// Publish generates the model and the manifest and then exits. An export starts a container and is
+ /// fire-and-forget, so on publish it would either be killed part-way through — leaving a truncated
+ /// image where a good one used to be — or hold the process open well past the work it was asked to
+ /// do. Publish is also expected to be hermetic: reaching for a container runtime that a build agent
+ /// may not have turns a working publish into a failing one.
+ ///
+ volatile bool _isPublishMode;
+
+ ///
+ /// Whether a write that has just happened should be followed by an image export.
+ ///
+ ///
+ /// Extracted so the rule can be asserted directly. Driving it through a publish proves nothing: the
+ /// export is fire-and-forget and publish exits immediately afterwards, so the images are missing at
+ /// the end of a publish whether this returns false or the export simply had not finished — which is
+ /// the very race that makes exporting on publish the wrong thing to do.
+ ///
+ /// Whether the generated model differs from the last one written.
+ /// The configured .
+ /// Whether this run is a publish rather than a run.
+ internal static bool ShouldExportImages(bool changed, bool exportImages, bool isPublishMode) =>
+ changed && exportImages && !isPublishMode;
+
+ ///
+ /// Incremented for every requested export, so a run that is still queued when a newer model arrives
+ /// can stand down rather than render a model that has already been superseded.
+ ///
+ long _exportVersion;
+
+ ///
+ /// Renders the views to images, unless a newer model arrived while this run was waiting its turn.
+ ///
+ ///
+ /// Called fire-and-forget from , which has already established that the
+ /// generated model changed. The resource-state watcher regenerates the model on every state
+ /// transition, so a long export can easily be overtaken; superseded runs stand down rather than
+ /// queueing up behind each other and writing older output last.
+ ///
+ async Task ExportImagesAsync(
+ string outputDirectory,
+ string serveDirectory,
+ string appHostDirectory,
+ string modelBody,
+ CancellationToken cancellationToken
+ )
+ {
+ var version = Interlocked.Increment(ref _exportVersion);
+
+ try
+ {
+ await _exportGate.WaitAsync(cancellationToken);
+ }
+ catch (OperationCanceledException)
+ {
+ // Shutdown.
+ return;
+ }
+
+ try
+ {
+ if (Interlocked.Read(ref _exportVersion) != version)
+ {
+ return;
+ }
+
+ // In container mode the export runs in the LikeC4 image, which already carries the Chromium
+ // and Graphviz binaries it needs; only WithLocalCLI() shifts it onto the host's own CLI.
+ var localCLI = workspaceOptions.Value.LocalCLIRuntime is { } runtime
+ ? AspireC4Builder.BuildLikeC4CLIPrefix(runtime)
+ : ((string Command, string[] Prefix)?)null;
+
+ await LikeC4ImageExporter.ExportAsync(
+ options.Value,
+ outputDirectory,
+ serveDirectory,
+ appHostDirectory,
+ modelBody,
+ localCLI,
+ telemetry,
+ cancellationToken
+ );
+ }
+ finally
+ {
+ _exportGate.Release();
+ }
+ }
+}
diff --git a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs
index 661d9e5..18a9ca4 100644
--- a/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs
+++ b/src/src/AspireC4/Lifecycle/AspireC4LifecycleHook.cs
@@ -73,6 +73,10 @@ public Task SubscribeAsync(
CancellationToken cancellationToken
)
{
+ // Recorded before anything subscribes, because WriteC4FileAsync is reached from the publish path
+ // too and has no other way to tell the two apart.
+ _isPublishMode = executionContext.IsPublishMode;
+
eventing.Subscribe(
async (evt, ct) =>
{
diff --git a/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs b/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs
index 1713aa8..14fa178 100644
--- a/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs
+++ b/src/src/AspireC4/Lifecycle/IAspireC4LifecycleHookTelemetry.cs
@@ -46,4 +46,16 @@ interface IAspireC4LifecycleHookTelemetry
[Debug]
void DiagramOptionsSnapshotApplied(string outputDirectoryName, bool formatGeneratedFile, bool disableHmr);
+
+ [Debug]
+ void ExportingImages(string format, string imageDirectory);
+
+ [Info]
+ void ImagesExported(string format, string imageDirectory);
+
+ [Warning]
+ void FailedToExportImages(string format, string reason);
+
+ [Debug]
+ void ImagesUnchanged(string imageDirectory);
}
diff --git a/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs
new file mode 100644
index 0000000..8c57fd1
--- /dev/null
+++ b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageExporter.cs
@@ -0,0 +1,430 @@
+using System.Diagnostics;
+using Aspire.Hosting.AspireC4.ApplicationModel;
+using Aspire.Hosting.AspireC4.Lifecycle;
+
+namespace Aspire.Hosting.AspireC4.LikeC4.Runtime;
+
+///
+/// Renders the LikeC4 views to image files with likec4 export.
+///
+///
+///
+/// Export drives a headless browser, which is why it runs in the ghcr.io/likec4/likec4 image by
+/// default: that image already carries the Chromium build and the Graphviz binaries LikeC4 lays out
+/// with. In local CLI mode the host's own likec4 is used instead, which needs a Playwright
+/// Chromium installed on the host.
+///
+///
+/// Every view in the project is exported, not only the generated one — a hand-authored project's views
+/// are part of the same model and are laid out by the same pass, so excluding them would mean asking
+/// LikeC4 to do the work and then discarding most of it.
+///
+///
+static class LikeC4ImageExporter
+{
+ /// The directory the images mount is exposed at inside the export container.
+ internal const string ContainerOutputPath = "/out";
+
+ ///
+ /// How long, in seconds, the headless browser is given per view. The CLI's own default of 15 is
+ /// tight for a large generated view on a cold start.
+ ///
+ internal const int PerViewTimeoutSeconds = 60;
+
+ /// The likec4 export format name for a given image format.
+ internal static string FormatName(LikeC4ImageFormat format) => format == LikeC4ImageFormat.Jpg ? "jpg" : "png";
+
+ ///
+ /// The formats to export, in a stable order.
+ ///
+ ///
+ /// is a set, whose enumeration order depends on
+ /// insertion and on whether configuration binding appended to it.
+ ///
+ internal static IReadOnlyList FormatsToExport(AspireC4DiagramOptions options)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+
+ return [.. options.ImageFormats.Distinct().Order()];
+ }
+
+ /// Resolves the directory images are written to, as an absolute path.
+ internal static string ResolveImageDirectory(AspireC4DiagramOptions options, string appHostDirectory)
+ {
+ ArgumentNullException.ThrowIfNull(options);
+
+ return AspireC4ImageExport.Resolve(options.ImageExportDirectory, appHostDirectory);
+ }
+
+ ///
+ /// Builds the command, arguments and working directory for one likec4 export invocation.
+ ///
+ /// The diagram options.
+ /// Where the generated model was written.
+ /// The LikeC4 project root, which is what gets exported.
+ /// Where the images are written.
+ /// The format to export.
+ ///
+ /// The host command and argument prefix when running the local CLI, or to run
+ /// the one-shot container.
+ ///
+ internal static (string Command, IReadOnlyList Arguments, string WorkingDirectory) BuildInvocation(
+ AspireC4DiagramOptions options,
+ string outputDirectory,
+ string serveDirectory,
+ string imageDirectory,
+ LikeC4ImageFormat format,
+ (string Command, string[] Prefix)? localCLI
+ )
+ {
+ ArgumentNullException.ThrowIfNull(options);
+ ArgumentException.ThrowIfNullOrWhiteSpace(outputDirectory);
+ ArgumentException.ThrowIfNullOrWhiteSpace(serveDirectory);
+ ArgumentException.ThrowIfNullOrWhiteSpace(imageDirectory);
+
+ if (localCLI is { } cli)
+ {
+ return (
+ cli.Command,
+ [.. cli.Prefix, .. ExportArguments(FormatName(format), imageDirectory, serveDirectory)],
+ // LikeC4 resolves the relative include paths and image aliases in likec4.config.json
+ // against the process working directory, so this has to match what the server and the
+ // formatter use or those paths climb out of the project.
+ outputDirectory
+ );
+ }
+
+ // The container sees the host tree through a single bind mount, exactly as the server does, so
+ // the config's relative paths resolve to the same files either way.
+ var workspaceRoot = AspireC4LifecycleHook.ComputeCommonAncestor([
+ outputDirectory,
+ serveDirectory,
+ .. options.AdditionalDSLFolders.Select(Path.GetFullPath),
+ .. options.ImageAliases.Values.Select(Path.GetFullPath),
+ ]);
+
+ var containerServePath = ToContainerPath(workspaceRoot, serveDirectory);
+ var tag = options.ContainerImageTag ?? LikeC4ServerResource.DefaultTag;
+
+ return (
+ options.ContainerRuntimeCommand,
+ [
+ "run",
+ "--rm",
+ // Read-only, like the server's mount: nothing in the source tree should be written by an
+ // export. The images land on their own writable mount instead.
+ //
+ // --mount rather than -v: a Windows host path already contains a colon, so
+ // "C:\…\likec4:/data:ro" leaves the runtime guessing where the drive letter ends and the
+ // mode begins, and it guesses wrong. --mount parses key=value and cannot be ambiguous.
+ "--mount",
+ $"type=bind,source={workspaceRoot},target={LikeC4ServerResource.WorkspacePath},readonly",
+ "--mount",
+ $"type=bind,source={imageDirectory},target={ContainerOutputPath}",
+ "--workdir",
+ ToContainerPath(workspaceRoot, outputDirectory),
+ LikeC4ServerResource.GetImageReference(tag),
+ .. ExportArguments(FormatName(format), ContainerOutputPath, containerServePath),
+ ],
+ workspaceRoot
+ );
+ }
+
+ static IReadOnlyList ExportArguments(string format, string imageDirectory, string serveDirectory) =>
+ [
+ "export",
+ format,
+ "-o",
+ imageDirectory,
+ // Without this the output mirrors the source tree, so an image's path depends on where the
+ // .c4 file happened to live rather than on the view it came from.
+ "--flat",
+ // One view that fails to render should not discard the ones that succeeded.
+ "-i",
+ "-t",
+ PerViewTimeoutSeconds.ToString(System.Globalization.CultureInfo.InvariantCulture),
+ serveDirectory,
+ ];
+
+ /// Maps a host path beneath the workspace root onto its path inside the container.
+ static string ToContainerPath(string workspaceRoot, string path)
+ {
+ var relative = Path.GetRelativePath(workspaceRoot, path).Replace('\\', '/');
+
+ return relative is "." or ""
+ ? LikeC4ServerResource.WorkspacePath
+ : $"{LikeC4ServerResource.WorkspacePath}/{relative}";
+ }
+
+ /// Renders every configured format, returning how many invocations succeeded.
+ ///
+ /// Best-effort throughout, like the formatter: a failed export leaves the generated model untouched,
+ /// so the only correct response is to report it and carry on.
+ ///
+ /// The diagram options.
+ /// Where the generated model was written.
+ /// The LikeC4 project root, which is what gets exported.
+ /// The AppHost directory the images directory is resolved against.
+ ///
+ /// The generated model, with its timestamp header stripped, recorded so an unchanged model renders
+ /// nothing on the next run.
+ ///
+ /// The host CLI to run, or for the container.
+ /// Where export progress and failures are reported.
+ /// Cancelled on shutdown.
+ public static async Task ExportAsync(
+ AspireC4DiagramOptions options,
+ string outputDirectory,
+ string serveDirectory,
+ string appHostDirectory,
+ string modelBody,
+ (string Command, string[] Prefix)? localCLI,
+ IAspireC4LifecycleHookTelemetry telemetry,
+ CancellationToken cancellationToken
+ )
+ {
+ ArgumentNullException.ThrowIfNull(options);
+ ArgumentNullException.ThrowIfNull(telemetry);
+
+ var formats = FormatsToExport(options);
+
+ if (formats.Count == 0)
+ {
+ return 0;
+ }
+
+ var imageDirectory = ResolveImageDirectory(options, appHostDirectory);
+
+ // Checked before anything is run. The AppHost's own change detection resets every time it
+ // restarts, so without this a restart re-renders views that are already correct on disk — and
+ // an export starts a LikeC4 server and a headless browser to do it.
+ var stamp = ImageExportStamp.Compute(modelBody, string.Join(",", formats.Select(FormatName)));
+
+ if (
+ await ImageExportStamp
+ .IsCurrentAsync(imageDirectory, StampName, stamp, ExistingImages(imageDirectory), cancellationToken)
+ .ConfigureAwait(false)
+ )
+ {
+ telemetry.ImagesUnchanged(imageDirectory);
+
+ return 0;
+ }
+
+ // Created here rather than left to the container runtime: a missing bind-mount source is created
+ // by the daemon as root, which a later host-side write could not then touch.
+ Directory.CreateDirectory(imageDirectory);
+
+ var exported = 0;
+
+ foreach (var format in formats)
+ {
+ var name = FormatName(format);
+
+ // Exported into a staging directory and moved in afterwards, because the CLI names each file
+ // after its view id with no say in the matter. In a folder shared with the ER diagram a bare
+ // "index.png" says nothing about which diagram it came from, and could collide outright.
+ var staging = Path.Combine(Path.GetTempPath(), $"aspirec4-export-{Guid.NewGuid():N}");
+
+ Directory.CreateDirectory(staging);
+
+ try
+ {
+ var (command, arguments, workingDirectory) = BuildInvocation(
+ options,
+ outputDirectory,
+ serveDirectory,
+ staging,
+ format,
+ localCLI
+ );
+
+ telemetry.ExportingImages(name, imageDirectory);
+
+ if (
+ await RunAsync(command, arguments, workingDirectory, options, name, telemetry, cancellationToken)
+ .ConfigureAwait(false)
+ )
+ {
+ exported++;
+
+ MoveWithPrefix(staging, imageDirectory);
+
+ telemetry.ImagesExported(name, imageDirectory);
+ }
+ }
+ finally
+ {
+ TryDelete(staging);
+ }
+ }
+
+ // Only once every requested format landed: a partial export must not be mistaken for a current
+ // one, or the formats that failed would never be retried.
+ if (exported == formats.Count)
+ {
+ await ImageExportStamp
+ .WriteAsync(imageDirectory, StampName, stamp, cancellationToken)
+ .ConfigureAwait(false);
+ }
+
+ return exported;
+ }
+
+ /// Distinguishes this diagram's stamp from the ER diagram's in the shared folder.
+ internal const string StampName = "architecture";
+
+ ///
+ /// The images this diagram has already written, which the stamp alone cannot stand in for.
+ ///
+ ///
+ /// The view names are only known once the CLI has run, so unlike the ER diagram there is no list of
+ /// expected files to check against — the test is whether this diagram left anything behind at all.
+ /// Deleting one view's image and keeping the rest is therefore not noticed; deleting the folder is.
+ ///
+ static string[] ExistingImages(string imageDirectory)
+ {
+ var missing = Path.Combine(imageDirectory, "(none)");
+
+ if (!Directory.Exists(imageDirectory))
+ {
+ return [missing];
+ }
+
+ var existing = Directory
+ .EnumerateFiles(imageDirectory, $"{AspireC4ImageExport.ArchitecturePrefix}*")
+ .Take(1)
+ .ToArray();
+
+ return existing.Length == 0 ? [missing] : existing;
+ }
+
+ /// Moves every staged image into the shared folder under its prefixed name.
+ ///
+ /// Overwrites, so a view that has been re-exported replaces its previous image rather than
+ /// accumulating. A view removed from the model leaves its last image behind, which is the lesser
+ /// evil: emptying the folder would also delete the ER diagram's images sitting beside them.
+ ///
+ static void MoveWithPrefix(string staging, string imageDirectory)
+ {
+ foreach (var file in Directory.EnumerateFiles(staging))
+ {
+ var destination = Path.Combine(
+ imageDirectory,
+ AspireC4ImageExport.ArchitecturePrefix + Path.GetFileName(file)
+ );
+
+ File.Move(file, destination, overwrite: true);
+ }
+ }
+
+ [System.Diagnostics.CodeAnalysis.SuppressMessage(
+ "Design",
+ "CA1031:Do not catch general exception types",
+ Justification = "Cleaning up a temporary directory must never fail an export that otherwise succeeded"
+ )]
+ static void TryDelete(string directory)
+ {
+ try
+ {
+ if (Directory.Exists(directory))
+ {
+ Directory.Delete(directory, recursive: true);
+ }
+ }
+ catch
+ {
+ // A leftover temp directory is harmless.
+ }
+ }
+
+ [System.Diagnostics.CodeAnalysis.SuppressMessage(
+ "Design",
+ "CA1031:Do not catch general exception types",
+ Justification = "Image export is best-effort; failures are reported via telemetry and never block startup"
+ )]
+ static async Task RunAsync(
+ string command,
+ IReadOnlyList arguments,
+ string workingDirectory,
+ AspireC4DiagramOptions options,
+ string format,
+ IAspireC4LifecycleHookTelemetry telemetry,
+ CancellationToken cancellationToken
+ )
+ {
+ try
+ {
+ ProcessStartInfo startInfo = new()
+ {
+ FileName = command,
+ RedirectStandardOutput = true,
+ RedirectStandardError = true,
+ UseShellExecute = false,
+ CreateNoWindow = true,
+ WorkingDirectory = workingDirectory,
+ };
+
+ foreach (var argument in arguments)
+ {
+ startInfo.ArgumentList.Add(argument);
+ }
+
+ using var process = Process.Start(startInfo);
+
+ if (process is null)
+ {
+ telemetry.FailedToExportImages(format, "the process could not be started");
+
+ return false;
+ }
+
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+ cts.CancelAfter(TimeSpan.FromSeconds(options.ImageExportTimeoutSeconds));
+
+ // Drained before waiting: likec4 export is verbose, and a full pipe would deadlock the wait.
+ var error = await process.StandardError.ReadToEndAsync(cts.Token).ConfigureAwait(false);
+
+ try
+ {
+ await process.WaitForExitAsync(cts.Token).ConfigureAwait(false);
+ }
+ catch (OperationCanceledException)
+ {
+ try
+ {
+ process.Kill(entireProcessTree: true);
+ }
+ catch
+ {
+ // Best-effort kill.
+ }
+
+ throw;
+ }
+
+ if (process.ExitCode == 0)
+ {
+ return true;
+ }
+
+ telemetry.FailedToExportImages(
+ format,
+ string.IsNullOrWhiteSpace(error) ? $"it exited with code {process.ExitCode}" : error.Trim()
+ );
+
+ return false;
+ }
+ catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+ {
+ // Shutdown.
+ return false;
+ }
+ catch (Exception ex)
+ {
+ telemetry.FailedToExportImages(format, ex.Message);
+
+ return false;
+ }
+ }
+}
diff --git a/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs
new file mode 100644
index 0000000..7e0d95e
--- /dev/null
+++ b/src/src/AspireC4/LikeC4/Runtime/LikeC4ImageFormat.cs
@@ -0,0 +1,21 @@
+namespace Aspire.Hosting.AspireC4.LikeC4.Runtime;
+
+///
+/// The image formats the architecture diagram is exported to on startup.
+///
+///
+/// There is deliberately no SVG member: the LikeC4 CLI renders its views by screenshotting them in a
+/// headless browser, and likec4 export offers only png and jpg as image formats.
+/// For a vector of the architecture, export the model instead and render it with another tool.
+///
+public enum LikeC4ImageFormat
+{
+ /// Portable network graphic. The default, and the better of the two for a diagram.
+ Png,
+
+ ///
+ /// JPEG. Smaller than a PNG of the same view, at the cost of compression artefacts around the text
+ /// and borders a diagram is almost entirely made of.
+ ///
+ Jpg,
+}
diff --git a/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs b/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs
index 11365d9..c0aaed2 100644
--- a/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs
+++ b/src/src/EntityFrameworkCore.Analyzers/Analysis/EfModelAnalyser.cs
@@ -29,7 +29,7 @@ public static Result Analyse(INamedTypeSymbol context, SemanticModel semanticMod
// Entity -> the name the table takes before attributes and fluent config are applied.
Dictionary entities = [with(SymbolEqualityComparer.Default)];
- foreach (var property in context.GetMembers().OfType())
+ foreach (var property in Properties(context))
{
if (
property.Type is INamedTypeSymbol { IsGenericType: true } set
@@ -60,6 +60,34 @@ public static Result Analyse(INamedTypeSymbol context, SemanticModel semanticMod
return new Result(context.Name, context.ToDisplayString(), fluent.DefaultSchema, tables, diagnostics);
}
+ /// Every property a type exposes, including the ones it inherits.
+ ///
+ /// A base entity carrying the key, timestamps and audit columns — and a base context declaring the
+ /// DbSet properties — are both ordinary shapes, but Roslyn's GetMembers returns only
+ /// what a type declares itself. Without walking the chain those properties are invisible, and with
+ /// them go the keys, columns and navigations among them. A derived property hides a base one of the
+ /// same name, which is how the compiler resolves it too.
+ ///
+ static List Properties(INamedTypeSymbol type)
+ {
+ List properties = [];
+ HashSet declared = [with(StringComparer.Ordinal)];
+
+ // Stops at object, ValueType and Enum: a special type declares no mapped property of its own.
+ for (var current = type; current is { SpecialType: SpecialType.None }; current = current.BaseType)
+ {
+ foreach (var property in current.GetMembers().OfType())
+ {
+ if (declared.Add(property.Name))
+ {
+ properties.Add(property);
+ }
+ }
+ }
+
+ return properties;
+ }
+
static FluentConfiguration ReadFluentConfiguration(
INamedTypeSymbol context,
SemanticModel semanticModel,
@@ -113,7 +141,7 @@ static void AddReachableEntities(Dictionary entities)
while (queue.Count > 0)
{
- foreach (var property in queue.Dequeue().GetMembers().OfType())
+ foreach (var property in Properties(queue.Dequeue()))
{
var target = GetNavigationTarget(property.Type);
@@ -148,7 +176,7 @@ static TableShape BuildTable(
var uniqueFromIndexes = ReadUniqueIndexProperties(entity);
List navigations = [];
- foreach (var property in entity.GetMembers().OfType())
+ foreach (var property in Properties(entity))
{
if (
property.DeclaredAccessibility != Accessibility.Public
@@ -264,7 +292,7 @@ static void AddComplexColumns(TableShape table, string prefix, ITypeSymbol compl
return;
}
- foreach (var member in named.GetMembers().OfType())
+ foreach (var member in Properties(named))
{
if (
member.DeclaredAccessibility != Accessibility.Public
@@ -354,11 +382,7 @@ static void ApplyPrimaryKeys(INamedTypeSymbol entity, TableShape table, EntityCo
else
{
keyProperties.AddRange(
- entity
- .GetMembers()
- .OfType()
- .Where(p => HasAttribute(p, EfTypes.Attributes.Key))
- .Select(p => p.Name)
+ Properties(entity).Where(p => HasAttribute(p, EfTypes.Attributes.Key)).Select(p => p.Name)
);
}
@@ -414,7 +438,8 @@ Dictionary entities
var column =
(explicitName is null ? null : table.Columns.FirstOrDefault(c => c.PropertyName == explicitName))
?? table.Columns.FirstOrDefault(c => c.PropertyName == navigation.Name + "Id")
- ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id");
+ ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id")
+ ?? SharedPrimaryKeyColumn(table, target);
if (column is null)
{
@@ -423,14 +448,16 @@ Dictionary entities
column.IsForeignKey = true;
+ // A foreign key that is also the whole key, or is uniquely indexed, can only match one
+ // principal row — that is what makes a relationship one-to-one rather than one-to-many.
+ var isUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique;
+
ForeignKeyShape foreignKey = new()
{
PrincipalEntity = target.ToDisplayString(),
NavigationName = navigation.Name,
- PrincipalNavigationName = PrincipalNavigation(target, dependent),
- // A foreign key that is also the whole key, or is uniquely indexed, can only match one
- // principal row — that is what makes a relationship one-to-one rather than one-to-many.
- IsUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique,
+ PrincipalNavigationName = PrincipalNavigation(target, dependent, isUnique),
+ IsUnique = isUnique,
IsRequired = !column.IsNullable,
};
@@ -439,12 +466,92 @@ Dictionary entities
}
}
+ ///
+ /// The dependent's own primary key, when that key doubles as the foreign key to the principal.
+ ///
+ ///
+ /// A shared-primary-key one-to-one — RepositoryState.Id being the Asset it describes —
+ /// declares no <Navigation>Id property, so the usual column lookup finds nothing and the
+ /// relationship disappears entirely. What identifies it is the dependent having borrowed the
+ /// principal's identity: the principal's key type is its own identifier, and the dependent is keyed by
+ /// that same type. A primitive key is deliberately not enough, because every entity keyed by
+ /// Guid or int would then match every other one.
+ ///
+ static ColumnShape? SharedPrimaryKeyColumn(TableShape table, INamedTypeSymbol principal)
+ {
+ var keyColumns = table.Columns.Where(c => c.IsPrimaryKey).ToList();
+
+ if (keyColumns.Count != 1 || PrimaryKeyType(principal) is not { } principalKeyType)
+ {
+ return null;
+ }
+
+ return
+ StoreTypeMap.ValueObjectType(principalKeyType) is not null
+ && IsOwnIdentifier(principal.Name, principalKeyType.Name)
+ && keyColumns[0].ClrTypeName == principalKeyType.ToDisplayString()
+ ? keyColumns[0]
+ : null;
+ }
+
+ ///
+ /// Whether a key type is the entity's own identifier, judged by name: AssetId belongs to
+ /// Asset — or AssetEntity — and so marks that entity as the owner of the identity
+ /// rather than a borrower of someone else's.
+ ///
+ static bool IsOwnIdentifier(string entityName, string keyTypeName)
+ {
+ const string idSuffix = "Id";
+ const string entitySuffix = "Entity";
+
+ if (!keyTypeName.EndsWith(idSuffix, StringComparison.Ordinal))
+ {
+ return false;
+ }
+
+ var stem = keyTypeName.Substring(0, keyTypeName.Length - idSuffix.Length);
+ var owner = entityName.EndsWith(entitySuffix, StringComparison.Ordinal)
+ ? entityName.Substring(0, entityName.Length - entitySuffix.Length)
+ : entityName;
+
+ return stem.Length > 0 && string.Equals(stem, owner, StringComparison.Ordinal);
+ }
+
+ /// The type of an entity's single primary key property, following the same conventions as
+ /// ; for a composite or unrecognised key.
+ static ITypeSymbol? PrimaryKeyType(INamedTypeSymbol entity)
+ {
+ var properties = Properties(entity);
+ var keyed = properties.Where(p => HasAttribute(p, EfTypes.Attributes.Key)).ToList();
+
+ if (keyed.Count > 0)
+ {
+ return keyed.Count == 1 ? keyed[0].Type : null;
+ }
+
+ return properties
+ .FirstOrDefault(p =>
+ string.Equals(p.Name, "Id", StringComparison.OrdinalIgnoreCase)
+ || string.Equals(p.Name, entity.Name + "Id", StringComparison.OrdinalIgnoreCase)
+ )
+ ?.Type;
+ }
+
///
/// The principal-side navigation: a collection on the principal whose element is the dependent.
///
- static string? PrincipalNavigation(INamedTypeSymbol principal, INamedTypeSymbol dependent)
+ /// The entity the foreign key points at.
+ /// The entity the foreign key lives on.
+ ///
+ /// Whether the foreign key is unique. A one-to-one has no collection to find, so its inverse is a
+ /// reference to the dependent — which is only safe to read as the inverse when the key says the
+ /// relationship is one-to-one, otherwise any two entities that point at each other would pair up.
+ ///
+ static string? PrincipalNavigation(INamedTypeSymbol principal, INamedTypeSymbol dependent, bool isUnique)
{
- foreach (var property in principal.GetMembers().OfType())
+ var properties = Properties(principal);
+
+ foreach (var property in properties)
{
if (
IsCollection(property.Type)
@@ -456,7 +563,11 @@ Dictionary entities
}
}
- return null;
+ return isUnique
+ ? properties
+ .FirstOrDefault(p => SymbolEqualityComparer.Default.Equals(StoreTypeMap.Unwrap(p.Type), dependent))
+ ?.Name
+ : null;
}
///
@@ -544,10 +655,43 @@ static HashSet ReadUniqueIndexProperties(INamedTypeSymbol entity)
return null;
}
+ // A framework type is never an entity in someone's model. Any class this analyser does not
+ // recognise as a scalar would otherwise be taken for a navigation and gain a table of its own,
+ // named after the framework type — so a single unmapped type turns into a phantom entity, and
+ // the walk then follows its properties into more of them.
+ if (IsFrameworkType(named))
+ {
+ return null;
+ }
+
// A class that maps to a column (string, byte[], ...) is not a navigation.
return named.SpecialType == SpecialType.None && !StoreTypeMap.IsScalar(named) ? Normalise(named) : null;
}
+ ///
+ /// Whether a type belongs to the framework rather than to the model being analysed.
+ ///
+ ///
+ /// Matched on the namespace root, so a user type is only ever caught by this if it was declared
+ /// directly in System or Microsoft — which EF would not map as an entity either.
+ ///
+ static bool IsFrameworkType(INamedTypeSymbol type)
+ {
+ var root = type.ContainingNamespace;
+
+ if (root is null || root.IsGlobalNamespace)
+ {
+ return false;
+ }
+
+ while (root.ContainingNamespace is { IsGlobalNamespace: false } parent)
+ {
+ root = parent;
+ }
+
+ return root.Name is "System" or "Microsoft";
+ }
+
///
/// Strips the nullable annotation from a navigation's target type.
///
diff --git a/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs b/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs
index 71bc627..2dbdf3d 100644
--- a/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs
+++ b/src/src/EntityFrameworkCore.Analyzers/AspireC4EfModelGenerator.cs
@@ -83,8 +83,19 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
);
}
+ /// Whether a type is a DbContext the diagram should show.
+ ///
+ /// An abstract or open-generic context — the DbContextBase<T> a real context derives from
+ /// — is never instantiated and owns no tables of its own, so describing it adds an empty node to the
+ /// diagram beside the context that actually has the model, and reports it as having no entity types.
+ ///
static bool DerivesFromDbContext(INamedTypeSymbol symbol)
{
+ if (symbol.IsAbstract || symbol.IsUnboundGenericType || symbol.TypeParameters.Length > 0)
+ {
+ return false;
+ }
+
for (var current = symbol.BaseType; current is not null; current = current.BaseType)
{
if (current.ToDisplayString() == EfTypes.DbContext)
diff --git a/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs b/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs
index 6a98c8f..9be5d74 100644
--- a/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs
+++ b/src/src/EntityFrameworkCore.Analyzers/Helpers/StoreTypeMap.cs
@@ -57,6 +57,15 @@ public static string Resolve(ITypeSymbol type)
"System.TimeSpan" => "time",
"System.DateOnly" => "date",
"System.TimeOnly" => "time",
+ // A JSON document is a column, not a table. Without these it resolves to Unknown, and an
+ // unknown class is taken for a navigation — which is how a property such as
+ // `JsonDocument Payload` used to invent an entity named after the framework type.
+ "System.Text.Json.JsonDocument"
+ or "System.Text.Json.JsonElement"
+ or "System.Text.Json.Nodes.JsonNode"
+ or "System.Text.Json.Nodes.JsonObject"
+ or "System.Text.Json.Nodes.JsonArray"
+ or "System.Text.Json.Nodes.JsonValue" => "json",
_ => Unknown,
};
}
diff --git a/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs b/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs
index 2f75da0..0a12cd7 100644
--- a/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs
+++ b/src/src/EntityFrameworkCore/AspireC4EfDiagramOptions.cs
@@ -124,6 +124,115 @@ internal static bool IsDefaultOutputDirectory(string? outputDirectory) =>
/// Pin the d2lang/d2 image tag. uses the package default.
public string? ContainerImageTag { get; set; }
+ ///
+ /// Whether the diagram is also written out as an image each time it changes. On by default.
+ ///
+ ///
+ ///
+ /// The images are written beside the diagram as {FileName}.svg and {FileName}.png, so a
+ /// schema can be attached to a pull request or pasted into a wiki without opening the viewer. Export
+ /// runs in the background, so it never delays startup, and only when it would actually change
+ /// something: a stamp beside the images records what they were rendered from, so a restart that
+ /// produces the same model runs nothing at all — not even a container. It is also skipped entirely
+ /// during a publish, which generates its output and exits.
+ ///
+ ///
+ /// Rendering always goes through d2, whatever is in use: the interactive
+ /// renderer is a browser application with no headless path, so an image of it could only be produced
+ /// by driving a browser. That means export needs either the d2lang/d2 container or a local
+ /// d2 binary (), and that the {FileName}.d2 source is written
+ /// alongside the diagram even for the other renderers. Set to , or use
+ /// , where neither is available.
+ ///
+ ///
+ public bool ExportImages { get; set; } = true;
+
+ ///
+ /// The formats written when is set. Defaults to both SVG and PNG.
+ ///
+ ///
+ /// Emptying this disables export as surely as clearing . Populate with
+ /// .
+ ///
+ [System.Diagnostics.CodeAnalysis.SuppressMessage(
+ "Usage",
+ "CA2227:Collection properties should be read only",
+ Justification = "Settable for configuration binding and direct assignment in user code"
+ )]
+ public HashSet ImageFormats { get; set; } = [ErdImageFormat.Svg, ErdImageFormat.Png];
+
+ ///
+ /// Where exported images are written. Relative paths are resolved against the AppHost directory;
+ /// (the default) uses ./.aspirec4/images/.
+ ///
+ ///
+ /// The architecture diagram writes to the same folder by default, so every image AspireC4 produces is
+ /// in one place. It matters most here: the interactive renderer writes its own index.html,
+ /// app.js and vendor/ into , and an image among those is
+ /// easy to miss.
+ ///
+ public string? ImageExportDirectory { get; set; }
+
+ ///
+ /// A local d2 executable to render exported images with. (the default)
+ /// runs the d2lang/d2 container instead.
+ ///
+ ///
+ /// Set by , which also replaces the
+ /// sidecar. Set it here to render images locally while leaving the sidecar — or the renderer's own
+ /// viewer — as it is.
+ ///
+ public string? D2Command { get; set; }
+
+ ///
+ /// The container runtime used to run the one-shot export container. Defaults to docker.
+ ///
+ /// Set to podman where that is the runtime Aspire itself is using.
+ public string ContainerRuntimeCommand { get; set; } = "docker";
+
+ /// Seconds to wait for an image export before abandoning it. Defaults to 120.
+ public int ExportTimeoutSeconds { get; set; } = 120;
+
+ ///
+ /// Whether exported images are produced by the interactive viewer itself rather than by d2. Off by
+ /// default.
+ ///
+ ///
+ ///
+ /// The d2 export is a different diagram, not a differently-styled one: d2 draws sql_table
+ /// shapes with its own theme and layout, while the viewer draws React Flow cards with context
+ /// colours, key badges, complex-type groups and crow's-foot markers. Setting this makes the exported
+ /// file identical to the one the viewer's own Save as SVG / PNG control produces.
+ ///
+ ///
+ /// The cost is a browser: the viewer only runs in one, so this pulls the Playwright image — around
+ /// 3.7 GB — and an export takes seconds rather than milliseconds. That is why it is opt-in.
+ /// Applies only to , the renderer that has a viewer; every other
+ /// renderer exports through d2 whatever this is set to.
+ ///
+ ///
+ ///
+ public bool UseViewerFidelityExport { get; set; }
+
+ ///
+ /// Overrides the image used for the viewer-fidelity export, including its tag.
+ /// uses the pinned Playwright image.
+ ///
+ ///
+ /// The image has to supply both node and a chromium Playwright can drive. Pointing this at
+ /// something else is how a consumer uses a mirror, or an image they have already cached.
+ ///
+ public string? ViewerExportImage { get; set; }
+
+ ///
+ /// Seconds to wait for a viewer-fidelity export. Defaults to 600.
+ ///
+ ///
+ /// Far longer than because the first run may be pulling the
+ /// browser image. Export runs in the background, so this never caps startup.
+ ///
+ public int ViewerExportTimeoutSeconds { get; set; } = 600;
+
///
/// Whether the file-based renderers serve their viewer over HTTP so the dashboard can link to it.
///
@@ -179,6 +288,54 @@ public AspireC4EfDiagramOptions WithProjectOptInOnly()
return this;
}
+ /// Restricts image export to the listed formats, replacing the SVG and PNG default.
+ ///
+ /// Also sets , so naming a format is enough to turn export on. Passing no
+ /// format turns it off, the same as .
+ ///
+ /// The formats to export.
+ /// This options instance, for chaining.
+ public AspireC4EfDiagramOptions WithImageExport(params ErdImageFormat[] formats)
+ {
+ ArgumentNullException.ThrowIfNull(formats);
+
+ ImageFormats = [.. formats];
+ ExportImages = formats.Length > 0;
+
+ return this;
+ }
+
+ ///
+ /// Exports images by rendering the interactive viewer in a headless browser, so the file matches
+ /// the viewer's own Save as SVG / PNG output exactly.
+ ///
+ ///
+ /// Pulls a browser image of around 3.7 GB and makes each export take seconds rather than
+ /// milliseconds; see . Only affects
+ /// .
+ ///
+ /// Whether to render through the viewer.
+ /// This options instance, for chaining.
+ public AspireC4EfDiagramOptions WithViewerFidelityExport(bool use = true)
+ {
+ UseViewerFidelityExport = use;
+
+ return this;
+ }
+
+ /// Stops the diagram being exported as an image, leaving only the generated diagram.
+ ///
+ /// This is how a consumer with no container runtime and no local d2 opts out; see
+ /// for why export needs one of the two.
+ ///
+ /// This options instance, for chaining.
+ public AspireC4EfDiagramOptions WithoutImageExport()
+ {
+ ExportImages = false;
+
+ return this;
+ }
+
/// Sets how a column shows its domain type next to the database type.
/// The display mode.
/// This options instance, for chaining.
diff --git a/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs b/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs
new file mode 100644
index 0000000..f73e1af
--- /dev/null
+++ b/src/src/EntityFrameworkCore/Assets/export/viewer-export.mjs
@@ -0,0 +1,245 @@
+// Renders the generated interactive ER viewer in a real browser and saves the image it produces.
+//
+// The viewer is a React Flow application, so the only way to get an image that matches what a reader
+// sees is to let the viewer produce it: this calls the very function the toolbar's Save as SVG/PNG
+// control calls. A d2 render, or a screenshot of the window, is a different picture.
+//
+// Driven over the Chrome DevTools Protocol using nothing but Node's own APIs. The Playwright image
+// ships the browsers but not the `playwright` package, and installing one at export time would mean a
+// network fetch on a path that is meant to be hermetic.
+//
+// Invoked as: node viewer-export.mjs
+// with the viewer mounted read-only at /data and the destination at /out.
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join, normalize } from "node:path";
+
+const VIEWER = "/data";
+const OUTPUT = "/out";
+const BROWSERS = "/ms-playwright";
+
+const formats = (process.argv[2] ?? "svg").split(",").filter(Boolean);
+const baseName = process.argv[3] ?? "schema";
+
+const TYPES = {
+ ".html": "text/html; charset=utf-8",
+ ".js": "text/javascript; charset=utf-8",
+ ".mjs": "text/javascript; charset=utf-8",
+ ".json": "application/json; charset=utf-8",
+ ".css": "text/css; charset=utf-8",
+ ".svg": "image/svg+xml",
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Locates the chromium the image shipped, whatever revision it happens to be. */
+async function findChrome() {
+ for (const entry of await readdir(BROWSERS)) {
+ if (entry.startsWith("chromium-")) {
+ return join(BROWSERS, entry, "chrome-linux", "chrome");
+ }
+ }
+
+ throw new Error(`No chromium found under ${BROWSERS}.`);
+}
+
+/**
+ * Serves the viewer over HTTP.
+ *
+ * Not opened from file://, because the viewer fetches its model JSON and that fetch is blocked under
+ * the file:// origin. The server is local to this container, so nothing is exposed anywhere.
+ */
+async function serveViewer() {
+ const server = createServer(async (request, response) => {
+ try {
+ const url = new URL(request.url ?? "/", "http://127.0.0.1");
+ const relative =
+ url.pathname === "/" ? "index.html" : decodeURIComponent(url.pathname).replace(/^\/+/, "");
+ const path = join(VIEWER, normalize(relative));
+
+ // normalize() collapses any "..", so a path that still escapes the root was trying to.
+ if (!path.startsWith(VIEWER)) {
+ response.writeHead(403).end();
+
+ return;
+ }
+
+ const body = await readFile(path);
+
+ response.writeHead(200, { "content-type": TYPES[extname(path)] ?? "application/octet-stream" }).end(body);
+ } catch {
+ response.writeHead(404).end();
+ }
+ });
+
+ await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+
+ return server;
+}
+
+/** Waits for the browser to publish its DevTools endpoint, then returns the page's socket URL. */
+async function connect(port) {
+ for (let attempt = 0; attempt < 100; attempt++) {
+ try {
+ const targets = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+ const page = targets.find((t) => t.type === "page");
+
+ if (page?.webSocketDebuggerUrl) {
+ return page.webSocketDebuggerUrl;
+ }
+ } catch {
+ // The browser is still starting.
+ }
+
+ await sleep(100);
+ }
+
+ throw new Error("The browser never published a DevTools endpoint.");
+}
+
+/** A minimal CDP client: send a command, await its reply. */
+function client(socket) {
+ let nextId = 0;
+ const pending = new Map();
+
+ socket.addEventListener("message", (event) => {
+ const message = JSON.parse(event.data);
+ const waiter = pending.get(message.id);
+
+ if (!waiter) return;
+
+ pending.delete(message.id);
+
+ if (message.error) waiter.reject(new Error(message.error.message));
+ else waiter.resolve(message.result);
+ });
+
+ return (method, params = {}) =>
+ new Promise((resolve, reject) => {
+ const id = ++nextId;
+
+ pending.set(id, { resolve, reject });
+ socket.send(JSON.stringify({ id, method, params }));
+ });
+}
+
+/** Evaluates an expression in the page and returns its value, surfacing a page-side throw. */
+async function evaluate(send, expression) {
+ const result = await send("Runtime.evaluate", {
+ expression,
+ awaitPromise: true,
+ returnByValue: true,
+ });
+
+ if (result.exceptionDetails) {
+ throw new Error(result.exceptionDetails.exception?.description ?? "evaluation failed");
+ }
+
+ return result.result.value;
+}
+
+/**
+ * Decodes the renderer's data URL into the bytes to write.
+ *
+ * The two formats arrive differently: a PNG comes back base64, while an SVG comes back as percent-
+ * encoded text. Treating the SVG as base64 produces a file that is the right size and entirely
+ * corrupt, so the declared encoding is what decides, not the format.
+ */
+function decodeDataUrl(dataUrl) {
+ const comma = dataUrl.indexOf(",");
+ const header = dataUrl.slice(0, comma);
+ const payload = dataUrl.slice(comma + 1);
+
+ return header.includes(";base64")
+ ? Buffer.from(payload, "base64")
+ : Buffer.from(decodeURIComponent(payload), "utf8");
+}
+
+const server = await serveViewer();
+const port = server.address().port;
+const profile = await mkdtemp(join(tmpdir(), "aspirec4-chrome-"));
+
+const chrome = spawn(
+ await findChrome(),
+ [
+ "--headless=new",
+ "--remote-debugging-port=0",
+ // The container is not privileged, and the page is one this package generated from the
+ // consumer's own model rather than anything fetched from the network.
+ "--no-sandbox",
+ "--disable-dev-shm-usage",
+ "--hide-scrollbars",
+ "--window-size=1600,1000",
+ `--user-data-dir=${profile}`,
+ `http://127.0.0.1:${port}/`,
+ ],
+ { stdio: ["ignore", "ignore", "pipe"] },
+);
+
+// The chosen debugging port is only discoverable from the browser's own startup banner.
+const debugPort = await new Promise((resolve, reject) => {
+ let banner = "";
+
+ chrome.stderr.on("data", (chunk) => {
+ banner += chunk;
+
+ const match = banner.match(/DevTools listening on ws:\/\/127\.0\.0\.1:(\d+)/);
+
+ if (match) resolve(Number(match[1]));
+ });
+
+ chrome.on("exit", (code) => reject(new Error(`chromium exited with code ${code}: ${banner}`)));
+});
+
+let failure = null;
+
+try {
+ const socket = new WebSocket(await connect(debugPort));
+
+ await new Promise((resolve, reject) => {
+ socket.addEventListener("open", resolve, { once: true });
+ socket.addEventListener("error", () => reject(new Error("could not attach to the page")), { once: true });
+ });
+
+ const send = client(socket);
+
+ await send("Runtime.enable");
+
+ // The hook is published once the nodes are laid out, so its presence is the diagram being ready.
+ // Polled rather than waited on with an event, because ELK lays out asynchronously after load.
+ let ready = false;
+
+ for (let attempt = 0; attempt < 600 && !ready; attempt++) {
+ ready = await evaluate(send, "typeof globalThis.__aspirec4RenderImage === 'function'");
+
+ if (!ready) await sleep(100);
+ }
+
+ if (!ready) {
+ throw new Error("The viewer never finished laying out the diagram.");
+ }
+
+ for (const format of formats) {
+ const dataUrl = await evaluate(send, `globalThis.__aspirec4RenderImage(${JSON.stringify(format)})`);
+
+ if (typeof dataUrl !== "string" || !dataUrl.includes(",")) {
+ throw new Error(`The viewer produced no ${format}.`);
+ }
+
+ await writeFile(join(OUTPUT, `${baseName}.${format}`), decodeDataUrl(dataUrl));
+ }
+
+ socket.close();
+} catch (error) {
+ failure = error;
+} finally {
+ chrome.kill();
+ server.close();
+}
+
+if (failure) {
+ console.error(failure.message);
+ process.exit(1);
+}
diff --git a/src/src/EntityFrameworkCore/Assets/viewer/app.js b/src/src/EntityFrameworkCore/Assets/viewer/app.js
index 4de1614..99171fd 100644
--- a/src/src/EntityFrameworkCore/Assets/viewer/app.js
+++ b/src/src/EntityFrameworkCore/Assets/viewer/app.js
@@ -65,17 +65,19 @@ function dependentMarker(fk) {
* The relationship's name, in both directions.
*
* A foreign key has a navigation on the dependent and usually an inverse collection on the principal.
- * Where the model declares only one, the other is marked "?" rather than hidden — an unnamed
- * direction is information. Only when neither is declared does it fall back to the constraint name,
- * and then to the columns.
+ * Edges here are drawn principal -> dependent, so the principal's navigation is named first and the
+ * arrow in the label agrees with the arrow on the edge. Where the model declares only one end, only
+ * that one is named: a single arrow says which way it can be travelled, and nothing claims the other
+ * direction exists. Only when neither is declared does it fall back to the constraint name, and then
+ * to the columns.
*/
function relationshipLabel(fk) {
- const dependent = fk.navigationName;
- const principal = fk.principalNavigationName;
+ const forward = fk.principalNavigationName;
+ const reverse = fk.navigationName;
- if (dependent && principal) return `${dependent} ⇄ ${principal}`;
- if (dependent) return `${dependent} → ?`;
- if (principal) return `? → ${principal}`;
+ if (forward && reverse) return `${forward} ⇄ ${reverse}`;
+ if (forward) return `${forward} →`;
+ if (reverse) return `← ${reverse}`;
if (fk.constraintName) return fk.constraintName;
return (fk.columns ?? []).join(", ");
@@ -166,6 +168,93 @@ const columnBadges = (col) => {
const isEnumColumn = (col) => col.domainTypeKind === "Enum";
+const COMPLEX_KIND = "ComplexValueObject";
+
+/** The property a flattened complex member belongs to: the segment before the first underscore. */
+const complexOwner = (col) => col.name.split("_")[0];
+
+/**
+ * Folds a table's flattened complex value-object columns under the property that owns them.
+ *
+ * EF maps a complex value object into its owner's table as one column per member, named
+ * `{Property}_{Member}`, so a card otherwise shows a run of rows that belong together while saying
+ * nothing about what they are. The owning prefixes are collected first, because a member whose own
+ * type is an enum or a nested value object carries that type rather than the enclosing one and would
+ * not be recognised on its own.
+ *
+ * @returns rows in model order: a column row per ordinary column, a group row per complex property.
+ */
+function rowPlan(table) {
+ const columns = table.columns ?? [];
+ const owners = new Set(columns.filter((c) => c.domainTypeKind === COMPLEX_KIND).map(complexOwner));
+ const rows = [];
+ const groups = new Map();
+
+ for (const col of columns) {
+ const owner = complexOwner(col);
+
+ if (!col.name.includes("_") || !owners.has(owner)) {
+ rows.push({ kind: "column", key: col.name, col });
+
+ continue;
+ }
+
+ let group = groups.get(owner);
+
+ if (!group) {
+ group = { kind: "group", key: owner, name: owner, typeName: null, columns: [] };
+
+ groups.set(owner, group);
+ rows.push(group);
+ }
+
+ // The outermost member names the group: a nested value object's own members carry the inner type,
+ // so the shallowest member is the one that reports the property's own type.
+ const shallow = !col.name.slice(owner.length + 1).includes("_");
+
+ if (group.typeName === null && col.domainTypeKind === COMPLEX_KIND && shallow) {
+ group.typeName = col.domainTypeName;
+ }
+
+ group.columns.push(col);
+ }
+
+ for (const group of groups.values()) {
+ group.typeName ??= group.columns[0]?.domainTypeName ?? "";
+ }
+
+ return rows;
+}
+
+/** Whether any table flattens a complex value object, and so has anything to expand. */
+const hasComplexColumns = (tables) =>
+ tables.some((t) => (t.columns ?? []).some((c) => c.domainTypeKind === COMPLEX_KIND));
+
+/** The member name shown inside its group, with the owning property's prefix removed. */
+const memberName = (group, col) => col.name.slice(group.name.length + 1);
+
+/** A group row's type cell: the value object, and when it is closed what it is holding. */
+const groupType = (group, open) => (open ? group.typeName : `${group.typeName} (${group.columns.length})`);
+
+/** The group keys a card is showing: the reader's own, plus any opened to reveal a search match. */
+const expandedOf = (data) => new Set([...(data.expanded ?? []), ...(data.forced ?? [])]);
+
+/**
+ * A row's type cell and the tooltip beside it.
+ *
+ * A member of an open group whose domain type is the group's own value object is shown as its database
+ * type alone: the group row above it already names the value object, and repeating it on every member
+ * crowds out the one thing those rows are there to say.
+ *
+ * @param group the group the row belongs to, or null for a column of the table itself.
+ */
+function rowType(col, group) {
+ const own = group && col.domainTypeKind === COMPLEX_KIND && col.domainTypeName === group.typeName;
+ const shown = own ? { ...col, domainTypeName: null, domainTypeKind: null } : col;
+
+ return { text: columnType(shown), annotation: columnAnnotation(shown) };
+}
+
const bothShown = () =>
DOMAIN_TYPE_DISPLAY === "DomainTypeFirst" || DOMAIN_TYPE_DISPLAY === "DatabaseFirst";
@@ -202,7 +291,132 @@ const columnType = (col) => {
return t;
};
-function EntityNode({ data, selected }) {
+/** One ordinary column row, or one member of an opened complex value object. */
+function ColumnRow({ col, name, type, needle, className }) {
+ return h(
+ "div",
+ {
+ // A table can match on a column the reader cannot see the reason for, so the row that caused
+ // the hit is marked rather than only the card around it.
+ className: `col${className}${needle && col.name.toLowerCase().includes(needle) ? " hit" : ""}`,
+ },
+ h(
+ "span",
+ { className: "name" },
+ h("span", { className: "col-name" }, name),
+ ...columnBadges(col).map((k) => h("span", { className: `badge ${k}`, key: k }, k.toUpperCase())),
+ ),
+ h(
+ "span",
+ {
+ className: "type",
+ // The database type stays reachable even when the domain type is the headline.
+ title: !bothShown() && type.annotation ? type.annotation : undefined,
+ },
+ type.text,
+ ),
+ );
+}
+
+/**
+ * The rows a card draws, with each complex value object folded under a row that opens it.
+ *
+ * The group's own row is a button rather than a decoration: a reader following a relationship into a
+ * table wants the flattened members on demand, not a run of prefixed columns they have to reassemble.
+ */
+function cardRowElements(data, onToggle) {
+ const expanded = expandedOf(data);
+ const elements = [];
+
+ for (const row of rowPlan(data.table)) {
+ if (row.kind === "column") {
+ elements.push(
+ h(ColumnRow, {
+ key: row.key,
+ col: row.col,
+ name: row.col.name,
+ type: rowType(row.col, null),
+ needle: data.needle,
+ className: "",
+ }),
+ );
+
+ continue;
+ }
+
+ const open = expanded.has(row.key);
+
+ elements.push(
+ h(
+ "div",
+ { key: row.key, className: `col group${open ? " open" : ""}` },
+ h(
+ "span",
+ { className: "name" },
+ h(
+ "button",
+ {
+ type: "button",
+ className: "chevron",
+ "aria-expanded": open,
+ title: `${open ? "Collapse" : "Expand"} ${row.name}`,
+ onClick: (event) => {
+ // The card is draggable and selectable; neither should happen on a disclosure.
+ event.stopPropagation();
+ onToggle(row.key);
+ },
+ },
+ open ? "▾" : "▸",
+ ),
+ h("span", { className: "col-name" }, row.name),
+ ),
+ h("span", { className: "type" }, groupType(row, open)),
+ ),
+ );
+
+ if (!open) continue;
+
+ for (const col of row.columns) {
+ elements.push(
+ h(ColumnRow, {
+ key: col.name,
+ col,
+ name: memberName(row, col),
+ type: rowType(col, row),
+ needle: data.needle,
+ className: " member",
+ }),
+ );
+ }
+ }
+
+ return elements;
+}
+
+function EntityNode({ id, data, selected }) {
+ const { setNodes } = useReactFlow();
+
+ /** Opens or closes one group on this card, and re-sizes it to what it now draws. */
+ const onToggle = useCallback(
+ (key) =>
+ setNodes((nodes) =>
+ saveFrom(
+ fitContexts(
+ nodes.map((node) => {
+ if (node.id !== id) return node;
+
+ const expanded = new Set(node.data.expanded ?? []);
+
+ if (!expanded.delete(key)) expanded.add(key);
+
+ return resizeEntity({ ...node, data: { ...node.data, expanded: [...expanded] } });
+ }),
+ ),
+ ),
+ ),
+ [id, setNodes],
+ );
+
return h(
"div",
{
@@ -226,34 +440,7 @@ function EntityNode({ data, selected }) {
data.table.schema ? h("span", { className: "schema" }, data.table.schema) : null,
),
// "names" mode is the overview: the header alone, so a large schema can be read at a glance.
- data.tables === "names"
- ? null
- : (data.table.columns ?? []).map((col) =>
- h(
- "div",
- {
- // A table can match on a column the reader cannot see the reason for, so the row
- // that caused the hit is marked rather than only the card around it.
- className: `col${data.needle && col.name.toLowerCase().includes(data.needle) ? " hit" : ""}`,
- key: col.name,
- },
- h(
- "span",
- { className: "name" },
- h("span", { className: "col-name" }, col.name),
- ...columnBadges(col).map((k) => h("span", { className: `badge ${k}`, key: k }, k.toUpperCase())),
- ),
- h(
- "span",
- {
- className: "type",
- // The database type stays reachable even when the domain type is the headline.
- title: !bothShown() && columnAnnotation(col) ? columnAnnotation(col) : undefined,
- },
- columnType(col),
- ),
- ),
- ),
+ data.tables === "names" ? null : cardRowElements(data, onToggle),
h(Handle, { type: "source", position: Position.Bottom, isConnectable: false }),
);
}
@@ -304,6 +491,11 @@ const BADGE_PADDING = 8;
const BADGE_LETTER_SPACING = 0.04;
const MEASURE_BUFFER = 3;
+// Mirroring index.html: the chevron's box and the indent a grouped member row carries.
+const CHEVRON_WIDTH = 14;
+const CHEVRON_GAP = 4;
+const MEMBER_INDENT = 18;
+
const textWidth = (text, font) => {
if (!text) return 0;
@@ -312,7 +504,24 @@ const textWidth = (text, font) => {
return measureContext.measureText(text).width;
};
-/** The width a table's card needs for every column name, badge and type to fit. */
+/** The width one column row needs, as a name, its badges and its type. */
+function columnRowWidth(col, name, indent, type) {
+ let row = indent + textWidth(name, FONT_SANS);
+
+ for (const badge of columnBadges(col)) {
+ const text = badge.toUpperCase();
+ row += BADGE_GAP + textWidth(text, FONT_BADGE) + BADGE_PADDING + text.length * 9 * BADGE_LETTER_SPACING;
+ }
+
+ return row + COLUMN_GAP + textWidth(type, FONT_TYPE);
+}
+
+/**
+ * The width a table's card needs for every column name, badge and type to fit.
+ *
+ * A collapsed group is measured as though it were open, so expanding one never re-widens the card and
+ * nothing has to be laid out again to accommodate it.
+ */
function cardWidth(table, tables) {
let widest = textWidth(table.name, FONT_HEADER);
@@ -320,22 +529,48 @@ function cardWidth(table, tables) {
// In names mode only the header is drawn, so only the header has to fit.
if (tables !== "names") {
- for (const col of table.columns ?? []) {
- let row = textWidth(col.name, FONT_SANS);
+ for (const row of rowPlan(table)) {
+ if (row.kind === "column") {
+ widest = Math.max(widest, columnRowWidth(row.col, row.col.name, 0, rowType(row.col, null).text));
- for (const badge of columnBadges(col)) {
- const text = badge.toUpperCase();
- row += BADGE_GAP + textWidth(text, FONT_BADGE) + BADGE_PADDING + text.length * 9 * BADGE_LETTER_SPACING;
+ continue;
}
- row += COLUMN_GAP + textWidth(columnType(col), FONT_TYPE);
- widest = Math.max(widest, row);
+ // The closed form carries the member count, so it is the wider of the two.
+ widest = Math.max(
+ widest,
+ CHEVRON_WIDTH +
+ CHEVRON_GAP +
+ textWidth(row.name, FONT_SANS) +
+ COLUMN_GAP +
+ textWidth(groupType(row, false), FONT_TYPE),
+ );
+
+ for (const col of row.columns) {
+ widest = Math.max(
+ widest,
+ columnRowWidth(col, memberName(row, col), MEMBER_INDENT, rowType(col, row).text),
+ );
+ }
}
}
return Math.ceil(widest + CARD_PADDING * 2 + ENTITY_BORDER + MEASURE_BUFFER);
}
+/** How many rows a card draws: a closed group is one row, an open one is itself plus its members. */
+function cardRows(table, tables, expanded) {
+ if (tables === "names") return 0;
+
+ let rows = 0;
+
+ for (const row of rowPlan(table)) {
+ rows += row.kind === "column" ? 1 : 1 + (expanded.has(row.key) ? row.columns.length : 0);
+ }
+
+ return rows;
+}
+
/**
* The rendered card's size — measured for the width, fixed per row for the height.
*
@@ -343,13 +578,11 @@ function cardWidth(table, tables) {
* references itself, because the self-loop needs a gutter beside the card.
*
* @param tables the table display mode: "columns" draws every column, "names" only the header.
+ * @param expanded the complex value-object groups this card is showing the members of.
*/
-const cardSize = (table, tables) => ({
+const cardSize = (table, tables, expanded = new Set()) => ({
width: Math.max(ENTITY_MIN_WIDTH, cardWidth(table, tables)),
- height:
- ENTITY_BORDER +
- ENTITY_HEADER_HEIGHT +
- (tables === "names" ? 0 : (table.columns?.length ?? 0) * ENTITY_ROW_HEIGHT),
+ height: ENTITY_BORDER + ENTITY_HEADER_HEIGHT + cardRows(table, tables, expanded) * ENTITY_ROW_HEIGHT,
});
const SELF_LOOP_REACH = 280;
@@ -419,7 +652,7 @@ const entitySize = (table, selfReferencing, tables) => {
* what ELK returns.
*/
/** The container's own margin around its tables, mirroring the ELK padding above. */
-const CONTEXT_PADDING = { top: 52, right: 28, bottom: 28, left: 28 };
+const CONTEXT_PADDING = { top: 56, right: 32, bottom: 32, left: 32 };
/**
* A node's current size. A manual resize sets the node's own width and height, which then wins over
@@ -430,6 +663,30 @@ const nodeWidth = (node) =>
const nodeHeight = (node) => node.height ?? node.measured?.height ?? node.data?.card?.height ?? 0;
+/**
+ * Re-sizes an entity for the groups it is currently showing.
+ *
+ * Only the height moves: a card is measured as though every group were open, so opening one never
+ * changes its width and the arrangement around it stays put. A card the reader has resized by hand
+ * keeps the size they gave it.
+ */
+function resizeEntity(node) {
+ if (node.type !== "entity" || node.height != null) return node;
+
+ // Only the row count changes, so the height is recomputed directly rather than re-measuring every
+ // name and type through the canvas — this runs for every card on every keystroke of a search.
+ const rows = cardRows(node.data.table, node.data.tables, expandedOf(node.data));
+ const height = ENTITY_BORDER + ENTITY_HEADER_HEIGHT + rows * ENTITY_ROW_HEIGHT;
+
+ if (node.data.card?.height === height && node.style?.height === height) return node;
+
+ return {
+ ...node,
+ style: { ...node.style, height },
+ data: { ...node.data, card: { ...node.data.card, height } },
+ };
+}
+
/**
* Resizes and moves each context container so it wraps its own tables, preserving every table's
* absolute position.
@@ -541,6 +798,9 @@ function saveLayout(nodes, tables, mode) {
entry.height = node.height;
}
+ // Which groups the reader opened, but not the ones a search opened for them.
+ if (node.data?.expanded?.length > 0) entry.expanded = node.data.expanded;
+
entities[node.id] = entry;
}
}
@@ -568,6 +828,29 @@ function loadLayout(tables, mode) {
}
}
+/**
+ * Persists the arrangement using the tables carried by the nodes themselves.
+ *
+ * Folding a group changes a card's height, so it has to be saved like a drag or a resize — but it is
+ * toggled from inside the card, which has no access to the model. Every entity node holds its own
+ * table and the display mode, which is all the fingerprint needs.
+ *
+ * @returns the nodes it was given, so a caller can save and return in one step.
+ */
+function saveFrom(nodes) {
+ const entities = nodes.filter((node) => node.type === "entity");
+
+ if (entities.length > 0) {
+ saveLayout(
+ nodes,
+ entities.map((node) => node.data.table),
+ entities[0].data.tables,
+ );
+ }
+
+ return nodes;
+}
+
/** Rebuilds the graph from a saved arrangement, dropping anything the model no longer has. */
function restoreLayout(saved, tables, colourOf, mode) {
const nodes = [];
@@ -592,7 +875,8 @@ function restoreLayout(saved, tables, colourOf, mode) {
if (!table || !known.has(id)) continue;
- const card = cardSize(table, mode);
+ const expanded = position.expanded ?? [];
+ const card = cardSize(table, mode, new Set(expanded));
const manual = position.width != null || position.height != null;
const width = manual ? position.width : card.width;
const height = manual ? position.height : card.height;
@@ -606,7 +890,16 @@ function restoreLayout(saved, tables, colourOf, mode) {
// stays un-sized and keeps following its content.
...(manual ? { width, height } : {}),
style: { width, height },
- data: { table, colour: colourOf(table.context), match: "", needle: "", card, tables: mode },
+ data: {
+ table,
+ colour: colourOf(table.context),
+ match: "",
+ needle: "",
+ card,
+ tables: mode,
+ expanded,
+ forced: [],
+ },
});
}
@@ -639,7 +932,7 @@ async function layout(tables, edges, colourOf, mode) {
// one row was already closer to that ratio than wrapping would be, and 1.4 produced a
// ragged three-plus-one. A target squarer than the viewport is what actually wraps.
"elk.aspectRatio": "1.1",
- "elk.spacing.nodeNode": "60",
+ "elk.spacing.nodeNode": "88",
},
children: contexts.map((context) => ({
id: `ctx:${context}`,
@@ -648,9 +941,23 @@ async function layout(tables, edges, colourOf, mode) {
"elk.direction": "DOWN",
// Top carries the label that sits on the border line; the other three are even, so the
// container reads as a frame around its tables rather than a box they are pushed into.
- "elk.padding": "[top=52,left=28,bottom=28,right=28]",
- "elk.spacing.nodeNode": "48",
- "elk.layered.spacing.nodeNodeBetweenLayers": "76",
+ "elk.padding": "[top=56,left=32,bottom=32,right=32]",
+ // The gap between layers carries the relationship labels, which are drawn at the middle
+ // of an edge over their own background: too little room and a label lands on the card
+ // below it. The sideways gap only has to separate two cards, so it is smaller.
+ "elk.spacing.nodeNode": "72",
+ "elk.layered.spacing.nodeNodeBetweenLayers": "120",
+ // Tables that no relationship connects form separate components, which ELK lays out one
+ // by one and then packs — a seam the between-layer spacing never reaches. Left at its
+ // default of 20 those groups sit almost touching, which reads as one crowded block
+ // rather than as the unrelated groups they are.
+ "elk.spacing.componentComponent": "120",
+ // Edges routed around a card keep clear of it rather than running along its border, and
+ // parallel edges stay far enough apart to be followed individually.
+ "elk.spacing.edgeNode": "40",
+ "elk.layered.spacing.edgeNodeBetweenLayers": "40",
+ "elk.spacing.edgeEdge": "24",
+ "elk.layered.spacing.edgeEdgeBetweenLayers": "24",
},
children: tables
.filter((t) => t.context === context)
@@ -694,7 +1001,8 @@ async function layout(tables, edges, colourOf, mode) {
parentId: container.id,
position: { x: child.x ?? 0, y: child.y ?? 0 },
style: { width: card.width, height: card.height },
- data: { table, colour, match: "", needle: "", card, tables: mode },
+ // Complex value objects start folded: a fresh card shows the table, not its interiors.
+ data: { table, colour, match: "", needle: "", card, tables: mode, expanded: [], forced: [] },
});
}
}
@@ -834,17 +1142,23 @@ async function save(dataUrl, fileName) {
}
/**
- * Renders the current diagram to an image and downloads it.
+ * Renders the current diagram to an image and returns it as a data URL.
*
* The crow's-foot markers are defined in a stand-alone <svg> outside the viewport, so a capture
* of the viewport alone resolves every `url(#erd-…)` to nothing and loses the cardinality. A copy
* rides along for the duration of the capture.
+ *
+ * Separate from {@link exportImage} so the AppHost's image export can render the diagram without
+ * downloading it: a headless browser has nowhere to put a download, and intercepting one to get at
+ * the bytes is a great deal of machinery for something the renderer already has in hand.
+ *
+ * @returns the data URL, or null when there is nothing laid out to capture.
*/
-async function exportImage(format, nodes, title) {
+async function renderImage(format, nodes, title) {
const viewport = document.querySelector(".react-flow__viewport");
const bounds = drawingBounds(nodes);
- if (!viewport || !bounds) return false;
+ if (!viewport || !bounds) return null;
const natural = Math.max(bounds.width, bounds.height) + EXPORT_PADDING * 2;
const scale = Math.min(1, EXPORT_MAX_SIDE / natural);
@@ -872,16 +1186,26 @@ async function exportImage(format, nodes, title) {
},
});
- await save(dataUrl, `${(title || "erd").replaceAll(/[^\w.-]+/g, "-").toLowerCase()}.${format}`);
-
- return true;
+ return dataUrl;
} finally {
markers?.remove();
}
}
+/** Renders the current diagram to an image and downloads it. */
+async function exportImage(format, nodes, title) {
+ const dataUrl = await renderImage(format, nodes, title);
+
+ if (!dataUrl) return false;
+
+ await save(dataUrl, `${(title || "erd").replaceAll(/[^\w.-]+/g, "-").toLowerCase()}.${format}`);
+
+ return true;
+}
+
function Diagram({ model }) {
const tables = useMemo(() => flatten(model), [model]);
+ const complex = useMemo(() => hasComplexColumns(tables), [tables]);
const [nodes, setNodes, onNodesChange] = useNodesState([]);
const [edges, setEdges, onEdgesChange] = useEdgesState([]);
const [query, setQuery] = useState("");
@@ -963,16 +1287,37 @@ function Diagram({ model }) {
const hits = new Set(matches);
setNodes((nodes) =>
- nodes.map((n) => {
- // Containers are never dimmed; doing so would wash out the tables inside them.
- if (n.type !== "entity") return n;
-
- const match = !needle ? "" : n.id === current ? "hit current" : hits.has(n.id) ? "hit" : "dimmed";
-
- if (n.data.match === match && n.data.needle === needle) return n;
+ fitContexts(
+ nodes.map((n) => {
+ // Containers are never dimmed; doing so would wash out the tables inside them.
+ if (n.type !== "entity") return n;
+
+ const match = !needle ? "" : n.id === current ? "hit current" : hits.has(n.id) ? "hit" : "dimmed";
+
+ // A match inside a folded complex value object would otherwise be reported and then not
+ // shown. The groups opened this way are held apart from the reader's own, so clearing
+ // the search folds them back rather than leaving the card as the search left it.
+ const forced = !needle
+ ? []
+ : rowPlan(n.data.table)
+ .filter(
+ (row) =>
+ row.kind === "group" && row.columns.some((c) => c.name.toLowerCase().includes(needle)),
+ )
+ .map((row) => row.key);
+
+ if (
+ n.data.match === match &&
+ n.data.needle === needle &&
+ n.data.forced?.length === forced.length &&
+ forced.every((key) => n.data.forced.includes(key))
+ ) {
+ return n;
+ }
- return { ...n, data: { ...n.data, match, needle } };
- }),
+ return resizeEntity({ ...n, data: { ...n.data, match, needle, forced } });
+ }),
+ ),
);
// A relationship is only fully in play when both of its ends are, so an edge recedes with
@@ -1048,6 +1393,52 @@ function Diagram({ model }) {
[nodes],
);
+ // The hook the AppHost's viewer-fidelity export calls, so an image produced headlessly is the same
+ // one this toolbar produces. Published only once the nodes are laid out, which is what makes its
+ // presence the signal that the diagram is ready to capture.
+ useEffect(() => {
+ if (nodes.length === 0) return undefined;
+
+ globalThis.__aspirec4RenderImage = (format) => renderImage(format, nodes, document.title);
+
+ return () => {
+ delete globalThis.__aspirec4RenderImage;
+ };
+ }, [nodes]);
+
+ /**
+ * Opens or folds every complex value object on every card.
+ *
+ * The arrangement is saved straight away: the cards have changed height, so a reload that restored
+ * the previous one would reopen the diagram with the containers fitted to the wrong sizes.
+ */
+ const groupKeys = useCallback(
+ (table) =>
+ rowPlan(table)
+ .filter((row) => row.kind === "group")
+ .map((row) => row.key),
+ [],
+ );
+
+ const setAllExpanded = useCallback(
+ (open) =>
+ setNodes((current) =>
+ saveFrom(
+ fitContexts(
+ current.map((node) =>
+ node.type === "entity"
+ ? resizeEntity({
+ ...node,
+ data: { ...node.data, expanded: open ? groupKeys(node.data.table) : [] },
+ })
+ : node,
+ ),
+ ),
+ ),
+ ),
+ [setNodes, groupKeys],
+ );
+
/** A segmented choice over a settings key, shared by the toolbar and the settings panel. */
const segmented = (key, options, label) =>
h(
@@ -1137,6 +1528,36 @@ function Diagram({ model }) {
h("span", { className: "sep" }),
h("span", { className: "count" }, "View"),
segmented("tables", TABLES, "View"),
+ // Only shown when the model has something to fold, so it is not dead chrome on a diagram
+ // whose tables are all plain columns.
+ ...(complex && settings.tables !== "names"
+ ? [
+ h("span", { className: "sep" }),
+ h("span", { className: "count" }, "Complex"),
+ h(
+ "div",
+ { className: "segmented", role: "group", "aria-label": "Complex value objects" },
+ h(
+ "button",
+ {
+ type: "button",
+ title: "Show the members of every complex value object",
+ onClick: () => setAllExpanded(true),
+ },
+ "Expand all",
+ ),
+ h(
+ "button",
+ {
+ type: "button",
+ title: "Fold every complex value object back to its property",
+ onClick: () => setAllExpanded(false),
+ },
+ "Collapse all",
+ ),
+ ),
+ ]
+ : []),
h("span", { className: "sep" }),
h("span", { className: "count" }, "Export"),
...["png", "svg"].map((format) =>
diff --git a/src/src/EntityFrameworkCore/Assets/viewer/index.html b/src/src/EntityFrameworkCore/Assets/viewer/index.html
index dc837ce..3574891 100644
--- a/src/src/EntityFrameworkCore/Assets/viewer/index.html
+++ b/src/src/EntityFrameworkCore/Assets/viewer/index.html
@@ -345,6 +345,41 @@
font-size: 11px;
}
+ /*
+ * A complex value object is folded under the property that owns it: the group row discloses
+ * its members, which are indented and set in the muted colour so the card still reads as a
+ * list of the table's own columns.
+ */
+ .entity .col.group .name {
+ gap: 4px;
+ }
+
+ /* Sized for the glyph, not for the text beside it: a 9px triangle reads as a speck. */
+ .entity .col .chevron {
+ flex: none;
+ width: 14px;
+ padding: 0;
+ border: 0;
+ background: none;
+ color: var(--muted);
+ font-size: 11px;
+ line-height: 1;
+ text-align: left;
+ cursor: pointer;
+ }
+
+ .entity .col .chevron:hover {
+ color: var(--fg);
+ }
+
+ .entity .col.member {
+ padding-left: 30px;
+ }
+
+ .entity .col.member .col-name {
+ color: var(--muted);
+ }
+
/* Colour separates what a column does: key, reference, uniqueness. */
.badge {
flex: none;
diff --git a/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs b/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs
new file mode 100644
index 0000000..d0bf303
--- /dev/null
+++ b/src/src/EntityFrameworkCore/D2/D2LayoutEngineNames.cs
@@ -0,0 +1,19 @@
+namespace Aspire.Hosting.AspireC4.EntityFrameworkCore.D2;
+
+/// Maps onto the names the d2 CLI accepts for --layout.
+///
+/// Shared by the sidecar resources and the image exporter so a diagram's exported image is laid out by
+/// the same engine as the one being served.
+///
+static class D2LayoutEngineNames
+{
+#pragma warning disable IDE0072 // Add missing cases
+ public static string ToEngineName(this D2LayoutEngine engine) =>
+ engine switch
+ {
+ D2LayoutEngine.Dagre => "dagre",
+ D2LayoutEngine.Tala => "tala",
+ _ => "elk",
+ };
+#pragma warning restore IDE0072 // Add missing cases
+}
diff --git a/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs b/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs
index f364a38..7acaa85 100644
--- a/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs
+++ b/src/src/EntityFrameworkCore/D2/D2ModelBuilder.cs
@@ -152,7 +152,9 @@ static List BuildEdges(EfModel model, Dictionary pathsBy
SourceColumn = foreignKey.Columns[i],
TargetTable = targetPath,
TargetColumn = foreignKey.PrincipalColumns[i],
- Label = EfRelationshipName.Label(foreignKey),
+ // The edge is attached to the column holding the foreign key, so it runs from
+ // the dependent and its label reads in that order.
+ Label = EfRelationshipName.Label(foreignKey, EfRelationshipDirection.DependentToPrincipal),
};
// Composite keys and multiple navigations can describe the same column pair.
diff --git a/src/src/EntityFrameworkCore/EfModelMetadataReader.cs b/src/src/EntityFrameworkCore/EfModelMetadataReader.cs
index 32cdbc4..9c70165 100644
--- a/src/src/EntityFrameworkCore/EfModelMetadataReader.cs
+++ b/src/src/EntityFrameworkCore/EfModelMetadataReader.cs
@@ -250,8 +250,19 @@ static IEnumerable GetLoadableTypes(Assembly assembly)
}
}
+ /// Whether a type is a DbContext the diagram should show.
+ ///
+ /// An abstract or open-generic context — the DbContextBase<T> a real context derives from
+ /// — is never instantiated and owns no tables of its own, so reading it adds an empty node to the
+ /// diagram beside the context that actually has the model.
+ ///
static bool IsDbContext(Type type)
{
+ if (type.IsAbstract || type.IsGenericTypeDefinition || type.ContainsGenericParameters)
+ {
+ return false;
+ }
+
try
{
for (var current = type.BaseType; current is not null; current = current.BaseType)
@@ -516,7 +527,8 @@ Dictionary entities
var column =
(explicitName is null ? null : table.Columns.FirstOrDefault(c => c.PropertyName == explicitName))
?? table.Columns.FirstOrDefault(c => c.PropertyName == navigation.Name + "Id")
- ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id");
+ ?? table.Columns.FirstOrDefault(c => c.PropertyName == target.Name + "Id")
+ ?? SharedPrimaryKeyColumn(table, target);
if (column is null)
{
@@ -525,13 +537,15 @@ Dictionary entities
column.IsForeignKey = true;
+ var isUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique;
+
table.ForeignKeys.Add(
new ForeignKeyShape
{
PrincipalEntity = target.FullName ?? target.Name,
NavigationName = navigation.Name,
- PrincipalNavigationName = PrincipalNavigation(target, dependent),
- IsUnique = (column.IsPrimaryKey && isSingleColumnKey) || column.IsUnique,
+ PrincipalNavigationName = PrincipalNavigation(target, dependent, isUnique),
+ IsUnique = isUnique,
IsRequired = !column.IsNullable,
Columns = [column.Name],
}
@@ -539,12 +553,89 @@ Dictionary entities
}
}
+ ///
+ /// The dependent's own primary key, when that key doubles as the foreign key to the principal.
+ ///
+ ///
+ /// A shared-primary-key one-to-one — RepositoryState.Id being the Asset it describes —
+ /// declares no <Navigation>Id property, so the usual column lookup finds nothing and the
+ /// relationship disappears entirely. What identifies it is the dependent having borrowed the
+ /// principal's identity: the principal's key type is its own identifier, and the dependent is keyed by
+ /// that same type. A primitive key is deliberately not enough, because every entity keyed by
+ /// Guid or int would then match every other one.
+ ///
+ static ColumnShape? SharedPrimaryKeyColumn(TableShape table, Type principal)
+ {
+ var keyColumns = table.Columns.Where(c => c.IsPrimaryKey).ToList();
+
+ if (keyColumns.Count != 1 || PrimaryKeyType(principal) is not { } principalKeyType)
+ {
+ return null;
+ }
+
+ return
+ ValueObjectType(principalKeyType) is not null
+ && IsOwnIdentifier(principal.Name, principalKeyType.Name)
+ && keyColumns[0].ClrTypeName == principalKeyType.FullName
+ ? keyColumns[0]
+ : null;
+ }
+
+ ///
+ /// Whether a key type is the entity's own identifier, judged by name: AssetId belongs to
+ /// Asset — or AssetEntity — and so marks that entity as the owner of the identity
+ /// rather than a borrower of someone else's.
+ ///
+ static bool IsOwnIdentifier(string entityName, string keyTypeName)
+ {
+ if (!keyTypeName.EndsWith("Id", StringComparison.Ordinal))
+ {
+ return false;
+ }
+
+ var stem = keyTypeName[..^"Id".Length];
+ var owner = entityName.EndsWith("Entity", StringComparison.Ordinal)
+ ? entityName[..^"Entity".Length]
+ : entityName;
+
+ return stem.Length > 0 && string.Equals(stem, owner, StringComparison.Ordinal);
+ }
+
+ /// The type of an entity's single primary key property, following the same conventions as
+ /// ; for a composite or unrecognised key.
+ static Type? PrimaryKeyType(Type entity)
+ {
+ List properties = [.. entity.GetProperties(BindingFlags.Public | BindingFlags.Instance)];
+ List keyed = [.. properties.Where(p => HasAttribute(p, "Key"))];
+
+ if (keyed.Count > 0)
+ {
+ return keyed.Count == 1 ? keyed[0].PropertyType : null;
+ }
+
+ return properties
+ .FirstOrDefault(p =>
+ string.Equals(p.Name, "Id", StringComparison.OrdinalIgnoreCase)
+ || string.Equals(p.Name, entity.Name + "Id", StringComparison.OrdinalIgnoreCase)
+ )
+ ?.PropertyType;
+ }
+
///
/// The principal-side navigation: a collection on the principal whose element is the dependent.
///
- static string? PrincipalNavigation(Type principal, Type dependent)
+ /// The entity the foreign key points at.
+ /// The entity the foreign key lives on.
+ ///
+ /// Whether the foreign key is unique. A one-to-one has no collection to find, so its inverse is a
+ /// reference to the dependent — which is only safe to read as the inverse when the key says the
+ /// relationship is one-to-one, otherwise any two entities that point at each other would pair up.
+ ///
+ static string? PrincipalNavigation(Type principal, Type dependent, bool isUnique)
{
- foreach (var property in principal.GetProperties(BindingFlags.Public | BindingFlags.Instance))
+ List properties = [.. principal.GetProperties(BindingFlags.Public | BindingFlags.Instance)];
+
+ foreach (var property in properties)
{
if (IsCollection(property.PropertyType) && property.PropertyType.GetGenericArguments()[0] == dependent)
{
@@ -552,7 +643,7 @@ Dictionary entities
}
}
- return null;
+ return isUnique ? properties.FirstOrDefault(p => p.PropertyType == dependent)?.Name : null;
}
///
@@ -632,10 +723,39 @@ static HashSet ReadUniqueIndexProperties(Type entity)
return null;
}
+ // A framework type is never an entity in someone's model. Any class this reader does not
+ // recognise as a scalar would otherwise be taken for a navigation and gain a table of its own,
+ // named after the framework type — and because AddReachableEntities walks a navigation's own
+ // properties, one unmapped type drags a tree of them into the diagram behind it.
+ if (IsFrameworkType(type))
+ {
+ return null;
+ }
+
// A class that maps to a column (string, byte[], ...) is not a navigation.
return !IsScalar(type) ? type : null;
}
+ ///
+ /// Whether a type belongs to the framework rather than to the model being read.
+ ///
+ ///
+ /// Matched on the namespace root, so a user type is only ever caught by this if it was declared
+ /// directly in System or Microsoft — which EF would not map as an entity either.
+ ///
+ static bool IsFrameworkType(Type type)
+ {
+ var @namespace = type.Namespace;
+
+ return @namespace is not null
+ && (
+ @namespace.Equals("System", StringComparison.Ordinal)
+ || @namespace.StartsWith("System.", StringComparison.Ordinal)
+ || @namespace.Equals("Microsoft", StringComparison.Ordinal)
+ || @namespace.StartsWith("Microsoft.", StringComparison.Ordinal)
+ );
+ }
+
static bool IsCollection(Type type) =>
type.IsGenericType && CollectionFullNames.Contains(type.GetGenericTypeDefinition().FullName ?? string.Empty);
@@ -805,6 +925,15 @@ static string ResolveStoreType(Type type)
"System.TimeSpan" => "time",
"System.DateOnly" => "date",
"System.TimeOnly" => "time",
+ // A JSON document is a column, not a table. Without these it resolves to unknown, and an
+ // unknown class is taken for a navigation — which is how a property such as
+ // `JsonDocument Payload` used to invent an entity named after the framework type.
+ "System.Text.Json.JsonDocument"
+ or "System.Text.Json.JsonElement"
+ or "System.Text.Json.Nodes.JsonNode"
+ or "System.Text.Json.Nodes.JsonObject"
+ or "System.Text.Json.Nodes.JsonArray"
+ or "System.Text.Json.Nodes.JsonValue" => "json",
_ => UnknownStoreType,
};
}
diff --git a/src/src/EntityFrameworkCore/EfRelationshipDirection.cs b/src/src/EntityFrameworkCore/EfRelationshipDirection.cs
new file mode 100644
index 0000000..278b2f6
--- /dev/null
+++ b/src/src/EntityFrameworkCore/EfRelationshipDirection.cs
@@ -0,0 +1,19 @@
+namespace Aspire.Hosting.AspireC4.EntityFrameworkCore;
+
+///
+/// Which end of a relationship a renderer draws the edge from.
+///
+///
+/// The renderers disagree, and legitimately so: d2 attaches an edge to the column that holds the
+/// foreign key, so it runs from the dependent, while the interactive viewer and Mermaid run from the
+/// principal so the line flows toward the many end. A relationship label names a direction of travel,
+/// so it only reads correctly when it is ordered to match the edge it sits on.
+///
+enum EfRelationshipDirection
+{
+ /// The edge starts at the table holding the foreign key.
+ DependentToPrincipal,
+
+ /// The edge starts at the table the foreign key points at.
+ PrincipalToDependent,
+}
diff --git a/src/src/EntityFrameworkCore/EfRelationshipName.cs b/src/src/EntityFrameworkCore/EfRelationshipName.cs
index 7c805d0..479f57c 100644
--- a/src/src/EntityFrameworkCore/EfRelationshipName.cs
+++ b/src/src/EntityFrameworkCore/EfRelationshipName.cs
@@ -7,33 +7,38 @@ namespace Aspire.Hosting.AspireC4.EntityFrameworkCore;
///
///
/// Both ends are named, because a relationship reads in both directions: a foreign key has a
-/// navigation on the dependent and usually an inverse collection on the principal. Where the model
-/// declares only one, the other is marked ? rather than hidden — an unnamed direction is
-/// information. Only when neither is declared does it fall back to the constraint name, and then to
-/// the columns.
+/// navigation on the dependent and usually an inverse collection on the principal. The declared end
+/// nearest the start of the edge is named first, so the arrow in the label and the arrow on the edge
+/// agree. Where the model declares only one end, only that one is named — a single arrow says which
+/// way it can be travelled, and nothing claims the other direction exists. Only when neither end is
+/// declared does it fall back to the constraint name, and then to the columns.
///
static class EfRelationshipName
{
/// The label a renderer shows on a relationship.
- public static string Label(EfForeignKey foreignKey)
+ /// The relationship to name.
+ /// Which end the renderer draws the edge from.
+ public static string Label(EfForeignKey foreignKey, EfRelationshipDirection direction)
{
ArgumentNullException.ThrowIfNull(foreignKey);
- var dependent = foreignKey.NavigationName;
- var principal = foreignKey.PrincipalNavigationName;
+ var (forward, reverse) =
+ direction == EfRelationshipDirection.DependentToPrincipal
+ ? (foreignKey.NavigationName, foreignKey.PrincipalNavigationName)
+ : (foreignKey.PrincipalNavigationName, foreignKey.NavigationName);
- if (!string.IsNullOrEmpty(dependent) && !string.IsNullOrEmpty(principal))
+ if (!string.IsNullOrEmpty(forward) && !string.IsNullOrEmpty(reverse))
{
- return $"{dependent} ⇄ {principal}";
+ return $"{forward} ⇄ {reverse}";
}
- if (!string.IsNullOrEmpty(dependent))
+ if (!string.IsNullOrEmpty(forward))
{
- return $"{dependent} → ?";
+ return $"{forward} →";
}
- if (!string.IsNullOrEmpty(principal))
- return $"? → {principal}";
+ if (!string.IsNullOrEmpty(reverse))
+ return $"← {reverse}";
// If neither end is named, fall back to the constraint name, and then to the columns.
return !string.IsNullOrEmpty(foreignKey.ConstraintName)
diff --git a/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj
index 749eafc..2161b83 100644
--- a/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj
+++ b/src/src/EntityFrameworkCore/EntityFrameworkCore.csproj
@@ -34,6 +34,8 @@
+
+