RazorDocs Search

Cli

Namespaces

RazorWire CLI

The RazorWire CLI is a command-line tool for managing RazorWire projects. Its primary feature is the ability to export a reactive RazorWire site into a static or hybrid directory for hosting on services like S3 or traditional web servers.

Installation

You can run the CLI directly using the dotnet run command from the project directory, or build it as a global tool.

dotnet run --project Web/ForgeTrust.Runnable.Web.RazorWire.Cli -- [command] [options]

Commands

export

Exports a RazorWire application to a static directory.

Options:

  • -o|--output <path>: Output directory where the static files will be saved (default: dist).
  • -r|--routes <path>: Optional path to a file containing seed routes to crawl.
  • -u|--url <url>: Base URL of a running application used for crawling.
  • -p|--project <path.csproj>: Path to a .NET project to run automatically and export.
  • -d|--dll <path.dll>: Path to a .NET DLL to run automatically and export.
  • --app-args <token>: Repeatable app-argument token to pass through when launching --project or --dll.
  • --no-build: Project mode only. Skips the release publish step and reuses existing published output.

Exactly one source option is required: --url, --project, or --dll.

When launched app processes are started by the CLI (--project or --dll), they run in production environment (DOTNET_ENVIRONMENT=Production, ASPNETCORE_ENVIRONMENT=Production).

When --project is used:

  • Project mode publishes a release build by default.
  • Project mode resolves the published app DLL and launches that DLL for crawling.
  • Add --no-build to skip publishing and reuse existing published output.

When --dll is used:

  • The CLI launches the provided DLL directly (no build or DLL resolution step).

For both --project and --dll:

  • If you do not pass --urls via --app-args, the CLI appends --urls http://127.0.0.1:0.
  • The CLI waits for startup, crawls the app, then shuts the process down automatically.

Example:

dotnet run --project Web/ForgeTrust.Runnable.Web.RazorWire.Cli -- export -o ./dist -u http://localhost:5233

dotnet run --project Web/ForgeTrust.Runnable.Web.RazorWire.Cli -- export -o ./dist -p ./examples/razorwire-mvc/RazorWireWebExample.csproj

dotnet run --project Web/ForgeTrust.Runnable.Web.RazorWire.Cli -- export -o ./dist -d ./bin/Release/net10.0/MyApp.dll --app-args --urls --app-args http://127.0.0.1:5009
Type

RazorWireCliModule

A terminal/CLI module for RazorWire providing static site export capabilities.

Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services)

Configures services needed for the CLI, including the ExportEngine and enhanced console logging.

Parameters

  • contextThe startup context.
  • servicesThe service collection to populate.
Method

ConfigureHostBeforeServices

void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)

Executes pre-service host configuration; currently no implementation is required.

Parameters

  • contextThe startup context.
  • builderThe host builder.
Method

ConfigureHostAfterServices

void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)

Executes post-service host configuration; currently no implementation is required.

Parameters

  • contextThe startup context.
  • builderThe host builder.
Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder)

Registers dependencies for this module; currently no implementation is required.

Parameters

  • builderThe module dependency builder.
Type

ExportContext

Provides context and state for an export operation, including configuration and crawl progress.

Property

OutputPath

string OutputPath { get; }

Gets the path where exported files will be saved.

Property

SeedRoutesPath

string? SeedRoutesPath { get; }

Gets the optional path to a seed routes file.

Property

BaseUrl

string BaseUrl { get; }

Gets the base URL of the source application being exported.

Property

Visited

HashSet<string> Visited { get; }

Gets the set of URLs that have already been visited during the crawl.

Property

Queue

Queue<string> Queue { get; }

Gets the queue of URLs pending processing.

Type

ITargetAppProcess

Represents a started or startable external target application process.

Method

Start

void Start()

Starts the process and begins asynchronous output capture.

Property

HasExited

bool HasExited { get; }

Gets a value indicating whether the process has exited.

Type

ITargetAppProcessFactory

Creates ITargetAppProcess instances for launch specifications.

Method

Create

ITargetAppProcess Create(ProcessLaunchSpec spec)

Creates a new process wrapper for the provided launch spec.

Parameters

  • specThe process launch specification.

Returns

A process wrapper ready to start.

Type

TargetAppProcessFactory

Default ITargetAppProcessFactory implementation.

Type

ExportSourceRequestFactory

Creates validated export source requests from CLI options.

Type

ProcessLaunchSpec

Describes how to launch an external process.

Property

FileName

string FileName { get; init; }

Gets the executable file name.

Property

Arguments

IReadOnlyList<string> Arguments { get; init; }

Gets the argument tokens passed to the process.

Property

EnvironmentOverrides

IReadOnlyDictionary<string, string> EnvironmentOverrides { get; init; }

Gets environment variable overrides applied for process startup.

Property

WorkingDirectory

string WorkingDirectory { get; init; }

Gets the working directory for the process.

Type

ExportSourceResolver

Resolves export sources and, when needed, orchestrates launching a target application for crawling.

Property

ListeningUrlTimeout

TimeSpan ListeningUrlTimeout { get; set; }

Gets or sets the maximum time to wait for the launched target app to emit a listening URL.

Property

AppReadyTimeout

TimeSpan AppReadyTimeout { get; set; }

Gets or sets the maximum time to wait for the launched target app to respond as ready.

Property

AppReadyPollInterval

TimeSpan AppReadyPollInterval { get; set; }

Gets or sets the polling interval used while probing target app readiness.

Type

ExportCommand

A command for exporting a RazorWire site to a static directory.

Method

ExecuteAsync

2 overloads
ValueTask ExecuteAsync(IConsole console)

Executes the export process for the RazorWire site to the configured output directory, validating options and writing progress to the console.

Parameters

  • consoleThe console used to write progress and completion messages.

Returns

A ValueTask that completes when the export operation finishes.

ValueTask ExecuteAsync(IConsole console, CancellationToken cancellationToken)

Executes the export process using an explicit cancellation token.

Parameters

  • consoleThe console used to write progress and completion messages.
  • cancellationTokenCancellation token for startup and export operations.

Returns

A ValueTask that completes when the export operation finishes.

Property

OutputPath

string OutputPath { get; init; }

Gets or sets the path to the directory where the exported site will be written. Defaults to "dist".

Property

SeedRoutesPath

string? SeedRoutesPath { get; init; }

Gets or sets an optional path to a file containing initial seed routes for the exporter.

Property

BaseUrl

string? BaseUrl { get; init; }

Gets or sets the base URL of a running application to crawl.

Property

ProjectPath

string? ProjectPath { get; init; }

Gets or sets a path to a .csproj file to run and export.

Property

DllPath

string? DllPath { get; init; }

Gets or sets a path to a .dll file to run and export.

Property

AppArgs

string[] AppArgs { get; init; }

Gets or sets app arguments forwarded to the launched target app. Repeat this option for each token.

Property

NoBuild

bool NoBuild { get; init; }

Gets or sets a value indicating whether project mode should skip build before launch.

Type

ExportEngine

A static generation engine that crawls a RazorWire application and exports its routes to static HTML files.

Method

RunAsync

Task RunAsync(ExportContext context, CancellationToken cancellationToken = default)

Crawls the site starting from configured seed routes (or the root) and exports discovered pages and frame sources to the output path.

Parameters

  • contextExport configuration and runtime state including base URL, output path, queue, and visited set.
  • cancellationTokenToken to observe for cooperative cancellation of the crawl and export operations.

Returns

A task that completes when the crawl and export operations have finished.

Exceptions

  • FileNotFoundExceptionThrown when ExportContext.SeedRoutesPath is specified but the file does not exist.

Remarks

If ExportContext.SeedRoutesPath is provided, the file is read and each line is validated and normalized to a root-relative route; invalid seeds are logged. If the seed file exists but yields no valid routes, the root path ("/") is enqueued. If no seed file is provided, the root path is enqueued. Discovered internal links and frame sources are queued and processed until the queue is exhausted or the operation is cancelled.

Method

ExportRouteAsync

Task ExportRouteAsync(HttpClient client, string route, ExportContext context, CancellationToken cancellationToken)

Fetches the HTML or asset for the specified route from the base URL, writes the file to the output directory, and enqueues any discovered internal links for further export.

Method

MapRouteToFilePath

string MapRouteToFilePath(string route, string outputPath, bool isHtml)

Maps a root-relative route to an absolute file path inside the configured output directory.

Method

ExtractLinks

Method

ExtractFrames

void ExtractFrames(string html, ExportContext context)

Extracts root-relative `src` values from <turbo-frame> elements in the provided HTML and enqueues each unvisited path for export.

Parameters

  • htmlHTML content to scan.
  • contextThe export context.
Method

ExtractAssets

void ExtractAssets(string html, string currentRoute, ExportContext context)

Extracts root-relative asset references (scripts, styles, images) from the provided HTML and enqueues each unvisited path for export.

Parameters

  • htmlHTML content to scan.
  • currentRouteThe route of the page being scanned, used for resolving relative URLs.
  • contextThe export context.
Method

ResolveRelativeUrl

string ResolveRelativeUrl(string baseRoute, string url)

Resolves a potentially relative URL against a base route.