
When creating a new ASP.NET Core Web API project in Visual Studio or with the .NET CLI, you may notice a checkbox labeled "Do not use top-level statements." This small option has sparked plenty of discussion among developers. Should you check it or leave it unchecked? What changes in your project when you do? Top-level statements were introduced in C# 9 to reduce boilerplate, and they became the default in .NET 6 templates. However, many teams still prefer the traditional Program class with an explicit Main method. This article explains the differences, the trade-offs, and when choosing not to use top-level statements makes sense for a Web API.
How AAMAX.CO Builds Robust Web APIs and Applications
Architecture decisions like this one shape how maintainable and scalable your software becomes over time. AAMAX.CO is a full-service digital marketing company offering web development, digital marketing, and SEO services worldwide. Their engineers design clean, well-structured APIs and back-end systems through their web application development services, following established conventions that make projects easy for teams to understand and extend. Whether they are building a new .NET API, modernizing a legacy application, or integrating third-party services, they focus on reliability, security, and long-term maintainability.
What Are Top-Level Statements?
Top-level statements allow you to write executable code directly at the root of a file without wrapping it in a namespace, class, and static Main method. The compiler automatically generates the entry point for you. In a modern Web API template with top-level statements, Program.cs might contain only a handful of lines: creating a WebApplication builder, registering services such as controllers and Swagger, building the app, configuring middleware, and calling Run.
Without top-level statements, the same file includes a namespace declaration, a Program class, and a static Main method that receives command-line arguments. The functionality is identical, but the structure is more explicit.
What the Checkbox Actually Does
Selecting "Do not use top-level statements" simply tells the template to generate Program.cs using the traditional structure. It does not change how ASP.NET Core works, how fast your API runs, or which features are available. It only affects how the entry point code is written. You can switch styles later by manually refactoring Program.cs, so this decision is not permanent.
Reasons Developers Choose Not to Use Top-Level Statements
Familiarity and readability: Developers who have worked with C# for years are accustomed to seeing an explicit Main method. The traditional structure makes the application's entry point obvious, especially for team members transitioning from older .NET Framework projects.
Consistency across a codebase: Large organizations often maintain many services built over different .NET versions. Keeping the same Program structure everywhere simplifies onboarding and code reviews.
Explicit namespaces: Top-level statement files exist in the global namespace. Some teams prefer every file, including Program.cs, to live inside a defined namespace to match architectural conventions and analyzer rules.
Integration testing: When using WebApplicationFactory for integration tests, test projects need to reference the Program class. With top-level statements, the generated Program class is internal by default, so developers often add a public partial Program class declaration or use InternalsVisibleTo. An explicit public Program class avoids this extra step.
Organizing startup logic: In complex APIs, startup code can grow large with dependency injection registrations, authentication configuration, and middleware pipelines. Some teams find it easier to split this into methods within an explicit Program class or a separate Startup class.
Reasons to Keep Top-Level Statements
Top-level statements produce cleaner, shorter files that are easier for newcomers to read. They align with the minimal hosting model introduced in .NET 6 and with Minimal APIs, which focus on concise endpoint definitions. Official documentation and most new tutorials use this style, so following it keeps your project aligned with current community examples. For small to medium services, the reduced ceremony can improve developer productivity.
Structuring a Web API Without Top-Level Statements
If you choose the traditional approach, a clean structure might include:
- A namespace matching your project, such as MyCompany.OrdersApi.
- A public Program class with a static Main method.
- Private static methods like ConfigureServices and ConfigurePipeline to organize builder and middleware setup.
- Extension methods in separate files for grouping related registrations, such as authentication, database contexts, and API versioning.
This approach keeps Program.cs short and focused while making each concern easy to locate and test.
Best Practices Regardless of Your Choice
- Keep Program.cs lean by moving service registrations into extension methods.
- Use configuration files and environment variables rather than hard-coded values.
- Apply consistent middleware ordering for exception handling, HTTPS redirection, authentication, and authorization.
- Document your API with OpenAPI so consumers understand endpoints and contracts.
- Write integration tests that spin up your API in memory to verify behavior.
- Agree on a team convention and apply it consistently across all services.
Performance and Compatibility
There is no performance difference between the two styles. The compiler generates essentially the same entry point either way. Both approaches support controllers, Minimal APIs, dependency injection, middleware, and every ASP.NET Core feature. Your decision should be based entirely on readability, team preferences, and testing needs.
Final Thoughts
The "Do not use top-level statements" option is a stylistic choice rather than a technical limitation. Checking it gives you a familiar, explicit Program class that some teams find more organized and easier to test. Leaving it unchecked produces concise, modern code aligned with current .NET guidance. Neither choice is wrong. What matters most is consistency, clean organization of startup logic, and a codebase that your team can maintain confidently as your Web API grows.