From c9cb0e526ff7c1059bba8bf331536ab7a6b12542 Mon Sep 17 00:00:00 2001 From: "Jeremy D. Miller" Date: Tue, 21 Apr 2026 15:20:12 -0500 Subject: [PATCH] docs: cross-link shared-libs.jasperfx.net and weasel.jasperfx.net MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sweeps Wolverine's guide for the main landing points of four topics that now have canonical homes elsewhere in the Critter Stack, and adds deep-links so readers can find the authoritative reference instead of bouncing through GitHub. - docs/guide/command-line.md — intro info box pointing at shared-libs.jasperfx.net/cli for the JasperFx command-line library (writing commands, arguments/flags, environment checks). Keeps this page focused on the Wolverine-specific surface. - docs/guide/codegen.md — intro info box pointing at shared-libs.jasperfx.net/codegen (frames, variables, MethodCall, generated types, codegen CLI). Also links the `codegen` CLI reference inline next to the existing "commands are from JasperFx.CodeGeneration.Commands" tip, and adds a one-line pointer under the "Using CritterStackDefaults" heading to shared-libs.jasperfx.net/configuration/critter-stack-defaults. - docs/guide/handlers/middleware.md — "Custom Code Generation" section now links shared-libs.jasperfx.net/codegen for the Frame / Variable / MethodCall model in depth rather than leaving users to grep source. - docs/guide/durability/managing.md — per-command Weasel CLI refs (db-apply / db-assert / db-patch / db-dump / db-list) added as an info box next to the existing `dotnet run -- db-apply` snippet. Also fixes the Weasel.CommandLine footnote to point at the /cli/ landing instead of the weasel root. - docs/guide/durability/efcore/migrations.md — adds a "for the finer-grained Weasel commands see the Weasel CLI reference" pointer under the CLI commands section. No content was moved or duplicated — these are purely outbound references so readers know where the canonical docs live. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guide/codegen.md | 8 +++++++- docs/guide/command-line.md | 4 ++++ docs/guide/durability/efcore/migrations.md | 2 +- docs/guide/durability/managing.md | 13 ++++++++++++- docs/guide/handlers/middleware.md | 2 +- 5 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/guide/codegen.md b/docs/guide/codegen.md index 7d71452c4..56c766916 100644 --- a/docs/guide/codegen.md +++ b/docs/guide/codegen.md @@ -10,6 +10,10 @@ your message handlers. Wolverine's [middleware strategy](/guide/handlers/middlew middleware directly into the runtime pipeline without requiring the copious usage of adapter interfaces that is prevalent in most other .NET frameworks. +::: info +This page covers Wolverine-specific use of code generation. The shared JasperFx code-generation library that backs it — [frames](https://shared-libs.jasperfx.net/codegen/frames.html), [variables](https://shared-libs.jasperfx.net/codegen/variables.html), [`MethodCall`](https://shared-libs.jasperfx.net/codegen/method-call.html), [generated types](https://shared-libs.jasperfx.net/codegen/generated-types.html), and the [`codegen` CLI command](https://shared-libs.jasperfx.net/codegen/cli.html) — is documented at [shared-libs.jasperfx.net/codegen](https://shared-libs.jasperfx.net/codegen/). Reach for it when you're authoring a custom `IVariableSource` or middleware frame. +::: + That's great when everything is working as it should, but there's a couple issues: 1. The usage of the Roslyn compiler at runtime *can sometimes be slow* on its first usage. This can lead to sluggish *cold start* @@ -301,7 +305,7 @@ JasperFx). ::: tip All of these commands are from the JasperFx.CodeGeneration.Commands library that Wolverine adds as -a dependency. This is shared with [Marten](https://martendb.io) as well. +a dependency. This is shared with [Marten](https://martendb.io) as well. See the [`codegen` CLI reference](https://shared-libs.jasperfx.net/codegen/cli.html) for every subcommand and flag. ::: To preview the generated source code, use this command line usage from the root directory of your .NET project: @@ -401,6 +405,8 @@ For Console applications or non-standard project structures, you may need to cus ### Using CritterStackDefaults +`CritterStackDefaults` is the shared entry point for opinionated defaults across the Critter Stack (Wolverine, Marten, Polecat, …). Full reference: [shared-libs.jasperfx.net/configuration/critter-stack-defaults](https://shared-libs.jasperfx.net/configuration/critter-stack-defaults.html). + You can configure the output path globally for all Critter Stack tools: diff --git a/docs/guide/command-line.md b/docs/guide/command-line.md index 5f3d9628a..a9c49e7b2 100644 --- a/docs/guide/command-line.md +++ b/docs/guide/command-line.md @@ -6,6 +6,10 @@ With help from its [JasperFx](https://github.com/JasperFx) team mate [Oakton](ht tools. To get started, apply Oakton as the command line parser in your applications as shown in the last line of code in this sample application bootstrapping from Wolverine's [Getting Started](/tutorials/getting-started): +::: info +This page covers the Wolverine-specific CLI surface. The underlying JasperFx command-line library that backs `RunJasperFxCommands` — including how to [author your own commands](https://shared-libs.jasperfx.net/cli/writing-commands.html), [argument/flag handling](https://shared-libs.jasperfx.net/cli/arguments-flags.html), and [environment checks](https://shared-libs.jasperfx.net/cli/environment-checks.html) — is documented at [shared-libs.jasperfx.net/cli](https://shared-libs.jasperfx.net/cli/). When a command accepts a generic flag not listed on this page, that's where to look first. +::: + ```cs diff --git a/docs/guide/durability/efcore/migrations.md b/docs/guide/durability/efcore/migrations.md index 8fe80f84a..a4be4eaa1 100644 --- a/docs/guide/durability/efcore/migrations.md +++ b/docs/guide/durability/efcore/migrations.md @@ -105,4 +105,4 @@ dotnet run -- resources list dotnet run -- resources clear ``` -These commands manage both Wolverine's internal tables and your EF Core entity tables together. +These commands manage both Wolverine's internal tables and your EF Core entity tables together. For the finer-grained Weasel commands (`db-apply`, `db-assert`, `db-patch`, `db-dump`, `db-list`) — useful for CI deploy gates and exporting DDL — see the [Weasel CLI reference](https://weasel.jasperfx.net/cli/). diff --git a/docs/guide/durability/managing.md b/docs/guide/durability/managing.md index 76d275cbe..d3f12c812 100644 --- a/docs/guide/durability/managing.md +++ b/docs/guide/durability/managing.md @@ -115,13 +115,24 @@ The available commands are: storage Administer the envelope storage ``` -There's admittedly some duplication here with different options coming from [Oakton](https://jasperfx.github.io/oakton) itself, the [Weasel.CommandLine](https://weasel.jasperfx.net/) library, +There's admittedly some duplication here with different options coming from [Oakton](https://jasperfx.github.io/oakton) itself, the [Weasel.CommandLine](https://weasel.jasperfx.net/cli/) library, and the `storage` command from Wolverine itself. To build out the schema objects for [message persistence](/guide/durability/), you can use this command to apply any outstanding database changes necessary to bring the database schema to the Wolverine configuration: ```bash dotnet run -- db-apply ``` + +::: info +The `db-apply`, `db-assert`, `db-patch`, `db-dump`, and `db-list` commands come from Weasel. See the per-command references at: + +- [`db-apply`](https://weasel.jasperfx.net/cli/db-apply.html) — apply all outstanding changes to the configured database(s) +- [`db-assert`](https://weasel.jasperfx.net/cli/db-assert.html) — assert the live schema matches the configuration (good for CI deploy gates) +- [`db-patch`](https://weasel.jasperfx.net/cli/db-patch.html) — emit a SQL patch + rollback file for pending changes +- [`db-dump`](https://weasel.jasperfx.net/cli/db-dump.html) — dump the full DDL for the configured database(s) +- [`db-list`](https://weasel.jasperfx.net/cli/db-list.html) — list configured databases +::: + > NOTE: See the [Exporting SQL Scripts](#exporting-sql-scripts) section down the page for details of applying migrations when integrating with Marten or this option -- but just know that this will also clear out any existing message data: diff --git a/docs/guide/handlers/middleware.md b/docs/guide/handlers/middleware.md index 1ac5f14c7..fe4bbcac0 100644 --- a/docs/guide/handlers/middleware.md +++ b/docs/guide/handlers/middleware.md @@ -359,7 +359,7 @@ on an individual handler method or apply to all handler methods on the same hand ## Custom Code Generation -For more advanced usage, you can drop down to the JasperFx.CodeGeneration `Frame` model to directly inject code. +For more advanced usage, you can drop down to the JasperFx.CodeGeneration `Frame` model to directly inject code. The `Frame` model itself — plus `Variable`, `MethodCall`, and the built-in frames Wolverine composes with — is documented in depth at [shared-libs.jasperfx.net/codegen](https://shared-libs.jasperfx.net/codegen/). The first step is to create a JasperFx.CodeGeneration `Frame` class that generates that code around the inner message or HTTP handler: