Start Here for AppSurface Evaluators

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

1. Read Should I Use AppSurface? to decide whether plain ASP.NET Core is still enough.
2. Run First Success Path to prove the smallest web app starts.
3. Run the Product Readiness Lab when you need a composed product-shaped proof with a readiness report.
4. Read From Program.cs to an AppSurface Module to inspect one concrete startup concern as a module.
5. Keep Troubleshoot Startup and Modules nearby if the first run or module composition does not behave as expected.
6. 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.

Use the product-readiness lab after the smallest web proof when the question changes from “can it start?” to “what would AppSurface own in a product app?” The lab report intentionally separates local proofs from host-owned production work: product state can be proven with Postgres, while Durable Task worker/client hosting and storage provider setup remain application-owned.

Use the fast report when you want no infrastructure:

dotnet run --project examples/product-readiness-lab/ProductReadinessLab.csproj -- --report

Use the AppHost verifier when you want every locally provable row to be exercised, including Postgres product-state persistence:

aspire run --non-interactive --apphost examples/product-readiness-lab-apphost/ProductReadinessLabAppHost.csproj -- verify

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.