ForgeTrust AppSurface
AppSurface
AppSurface gives .NET teams a modular startup pipeline for web, console, and distributed apps. Start with the pillar you need, then drill into concrete examples and API reference.
Start Here
Follow the proof path first.
Understand what the system is for, see it working, then choose the next implementation route with context.
Decide if AppSurface fits
Start here when you need to know whether AppSurface is better than plain ASP.NET Core startup code for your app or team.
-
Should my team use AppSurface?
GuideShould I Use AppSurface?
Compare plain ASP.NET Core with AppSurface's module model before installing extra packages.
-
What is the evaluator path?
GuideStart Here for AppSurface Evaluators
Follow the shortest reading path for team leads, managers, architects, and senior developers evaluating startup standardization.
Prove the first service
Run the smallest web proof, then inspect the first reusable startup concern.
-
Can I run it in minutes?
TutorialFirst Success Path
Start with the existing web example and verify the first response before reading deeper docs.
-
What does a module buy me?
GuideFrom Program.cs to an AppSurface Module
See browser status and production error page setup move from scattered startup policy to a named AppSurface concern.
Recover and read the vocabulary
Use these when the first run or first module does not behave as expected.
-
Why did startup or module composition fail?
TroubleshootingTroubleshoot Startup and Modules
Diagnose module registration, dependency, configuration, route, static asset, docs surface, and package-choice mistakes.
-
What do the core terms mean?
GlossaryAppSurface Glossary
Learn the vocabulary used by AppSurface package docs and examples.
Choose a package
Start here when you need the smallest useful install path for a new app.
-
Which AppSurface package should I install first?
GuideAppSurface package chooser
Start with the generated package chooser, then add only the optional modules your app actually needs.
-
Which Auth package do I need?
GuideAppSurface Auth Adoption Ladder
Choose between host-owned ASP.NET Core auth, AppSurface Auth contracts, DevAuth, OIDC, and Auth.Testing before copying auth proof code.
-
How do I make CI evidence match changed risk?
GuideEvidenceHost: risk-mediated CI
Plan explicit coverage and E2E evidence by changed-risk profile without treating skipped tests as complete coverage.
Evaluate release risk
Use these routes when you need to decide whether current changes are safe to adopt.
Build docs with AppSurface Docs
Use this path when you want to host authored docs and generated API reference from your own repository.
See it working
Follow concrete application paths before drilling into reference material.
-
Show me a working app, not just abstractions
ExampleWeb app example
Walk through a minimal ASP.NET Core app that uses AppSurface modules end to end.
-
How does this fit distributed systems?
GuideAspire Projects
See how the same modular approach extends into .NET Aspire and service-default composition.
-
What about CLI and worker flows?
GuideConsole Projects
Follow the console tooling for commands, critical services, and shared startup patterns.
Build the mental model before you choose an implementation path.
Follow task-oriented guides that turn intent into working implementation steps.
-
Form Loading Feedback Guide
RazorWire form loading gives an accepted Turbo form submission visible feedback while the browser waits for token preparation or the server. It applies to forms enhanced with `rw-active="true"`; it does not add a general request or navigation loading API. The app can supply a nearby status message, and RazorWire shows its accessible top bar when no app indicator applies.
-
Form Interactions Guide
Use RazorWire form interactions when a server-rendered form needs small local mechanics without page-specific JavaScript: reveal or disable conditional fields, add and duplicate model-bound rows at multiple collection levels, and remove rows while keeping ASP.NET Core model binding predictable. The package owns row mechanics; the application still owns its model, field markup, validation policy, persistence, and failed-post rendering keys.
Inspect concrete, working proof that shows the system behaving in practice.
-
RazorWire MVC Example Example
Run the RazorWire MVC sample and inspect its interactive server-rendered flows.
-
Nested Collections Quickstart Guide
Run the existing MVC host to try RazorWire's nested collection commands with a small `DateOnly` model. Each action owns its own dates; hidden `.index` markers retain sparse binding keys through an invalid POST and correction. The [Form Interactions guide](../../Web/ForgeTrust.RazorWire/Docs/form-interactions.md#nested-collections-and-index-tokens) is the canonical API and migration reference, including template placeholders, copy/removal rules, events, and diagnostics.
Review package entry points, install choices, and package-level adoption guidance.
-
RazorWire Guide
RazorWire lets ASP.NET Core MVC apps update UI by returning Razor fragments from the server instead of building a separate JSON endpoint and client-state rendering loop.
-
AppSurface CLI Guide
Use [appsurface durable doctor](../../Durable/runtime-doctor.md) for a non-mutating store/runtime diagnosis in text or version-one JSON. It accepts environment-source names and optional paired worker/actual-threshold inputs, and supplies explicit exits and next actions. Clean output links the [canonical Durable worker starter](../../start-here/durable-worker.md) while requiring the diagnosed application's own composition verifier; its null command does not invent or execute that verifier.
Dive into namespaces, APIs, and type-level detail once you know what you are looking for.
Review changelogs, upgrade guidance, and release-facing project history.
Recover from failures, debug edge cases, and understand what to check next.
-
Troubleshoot Startup and Modules Troubleshooting
Diagnose first-run module registration, dependency, configuration, route, static asset, docs surface, and package-choice failures.
-
Failed Form UX Guide
RazorWire-enhanced forms now have a convention for server failures. A form with `rw-active="true"` gets request markers, a default form-local fallback UI for unhandled failures, server-side helpers for high-quality validation errors, and development diagnostics for anti-forgery failures.