Documentation
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.
-
Open page
Should my team use AppSurface?
GuideShould I Use AppSurface?
Compare plain ASP.NET Core with AppSurface's module model before installing extra packages.
-
Open page
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.
-
Open page
Can I run it in minutes?
TutorialFirst Success Path
Start with the existing web example and verify the first response before reading deeper docs.
-
Open page
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.
-
Open page
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.
-
Open page
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.
Evaluate release risk
Use these routes when you need to decide whether current changes are safe to adopt.
Build docs with RazorDocs
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.
-
Open page
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.
-
Open page
How does this fit distributed systems?
GuideAspire Projects
See how the same modular approach extends into .NET Aspire and service-default composition.
-
Open page
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.
-
OpenRazorWire 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.
-
OpenSecurity & Anti-Forgery Troubleshooting
When using RazorWire Turbo Streams to replace or update parts of a page that contain forms, the original Anti-Forgery token hidden input may be lost. To prevent `400 Bad Request` errors on subsequent form submissions, ensure the token is included in your updated HTML.
Inspect concrete, working proof that shows the system behaving in practice.
-
OpenRazorWire MVC Example Example
This sample is the concrete proof behind the RazorWire package README. It shows how returned Razor fragments, islands, and SSE fit into a normal ASP.NET Core MVC app without a separate client rendering stack.
-
OpenConfig validation example Example
This sample shows scalar validation on a strongly typed AppSurface config wrapper.
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.
-
OpenReleases Guide
Start with the public release hub, then drill into the unreleased proof artifact, the compact changelog, and the pre-1.0 upgrade policy.
-
OpenUnreleased Release
Living proof artifact for the next coordinated AppSurface release. This page is intentionally provisional until a version is tagged.
Recover from failures, debug edge cases, and understand what to check next.
-
OpenTroubleshoot Startup and Modules Troubleshooting
Diagnose first-run module registration, dependency, configuration, route, static asset, docs surface, and package-choice failures.
-
OpenFailed 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.