Start Here for AppSurface Evaluators
Follow the shortest path for deciding whether AppSurface fits an ASP.NET Core app or a team-wide startup standard.
Source of truth
Section landing
Use this section as the entry point.
Orient quickly, verify what the product is for, and follow the strongest proof path.
In this section
-
Should I Use AppSurface? Guide
Decide when plain ASP.NET Core startup code is enough and when an AppSurface module makes a setup concern clearer.
-
First Success Path Tutorial
Run the existing minimal web example and verify the first response before reading deeper docs.
-
AppSurface v0.1 package chooser Guide
Start with the package that matches the app you are building, then add optional web modules and support surfaces only when you need them.
-
Use RazorDocs in your repository Guide
Learn when to adopt RazorDocs, how to host it, and how to use authored metadata to turn repository Markdown and C# APIs into a usable docs site.
-
AppSurface Guide
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.
Use this path when you need to decide whether AppSurface belongs in an ASP.NET Core service or across a set of services.
The target reader is a team lead, engineering manager, architect, or senior developer who owns startup consistency. You may be evaluating from one service first. That is fine. The question is still the same: when does a named AppSurface module make startup clearer than keeping the setup directly in Program.cs?
The Short Path
- Read Should I Use AppSurface? to decide whether plain ASP.NET Core is still enough.
- Run First Success Path to prove the smallest web app starts.
- Read From Program.cs to an AppSurface Module to inspect one concrete startup concern as a module.
- Keep Troubleshoot Startup and Modules nearby if the first run or module composition does not behave as expected.
- Use the AppSurface Glossary when a term in package docs is unfamiliar.
What AppSurface Is
AppSurface is a small module composition layer over familiar .NET and ASP.NET Core primitives. It does not replace the host, middleware, routing, dependency injection, or options model.
AppSurface gives you a place to name startup concerns. A module can register services, configure host behavior, configure web options, register middleware, and map endpoints through one documented surface.
Start with the package chooser when you need an install path. Start with this evaluator path when you need the adoption argument.
What To Look For
Look for a setup concern that is repeated, safety-sensitive, or easy to configure differently in each service.
Good early candidates look like this:
- Each service needs the same browser-facing recovery behavior.
- Each service needs the same API-friendly exception or status behavior.
- A team wants the same startup convention without copying a block of
Program.cs. - A setup concern has enough policy that it deserves a name, tests, and reference docs.
AppSurface is not valuable because Program.cs is bad. It is valuable when Program.cs is carrying a policy that your team should understand, reuse, and verify.
Common Pitfalls
- Do not install every optional AppSurface package first. Pick the package that matches the app.
- Do not hide ASP.NET Core. AppSurface should make the underlying ASP.NET Core behavior easier to find, not harder.
- Do not turn a one-off local choice into a shared module too early. Name the concern when the policy matters.
- Do not compare AppSurface against large application frameworks in this Start Here path. The first comparison is plain ASP.NET Core startup code.