> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/documentation/en/framework/web.md).

# Web Fundamentals

Organize ASP .NET Core applications with plugins to connect controllers, data services, request pipelines, and protocol extensions.

[Zongsoft.Web](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Web) provides general controller, binding, formatting, routing, credential authentication and file access capabilities; [Zongsoft.Plugins.Web](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Plugins.Web) integrates these capabilities into the plugin host and is responsible for Web part discovery and application lifecycle. The business controller is placed in the plugin, and the host is responsible for hosting and assembly.

{% hint style="info" %}
When designing and implementing business HTTP APIs, follow the [REST API Design Guidelines](https://github.com/Zongsoft/Guidelines/blob/main/zongsoft.rest-api.guidelines.md) (in Chinese). See [Prerequisites: Development Guidelines](/documentation/en/get-started/prerequisites.md#development-guidelines) for C# coding conventions and shared development requirements.
{% endhint %}

## First Understand What the Request Goes Through

A request is first processed by the host middleware, and then matched with the controller and operation; model binding converts the path, query, request header and request body into parameters, the controller calls the business service, and the formatter outputs the response. Authentication establishes the identity of the caller, and authorization determines whether an operation is allowed. Both have their own responsibilities.

The plugin web portal will initialize the application context and application [initializer](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/IApplicationInitializer.cs), then add CORS, localization, method coverage, routing, authentication, authorization, response compression and static files, and finally map the controller and Hub. Check relative order when extending middleware rather than reinstalling the entire pipeline.

## Choose How to Use It

Reference [Zongsoft.Web](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Web) when you only need the MVC auxiliary capabilities of the framework; use the Plugins.Web host when you need to discover the business controller through the manifest. Ready-made launcher see [Web Host](/documentation/en/hosting/web.md).

Source: [hosting/web/default/Program.cs](https://github.com/Zongsoft/hosting/blob/main/web/default/Program.cs#L12) (excerpt; see source for context).

{% code title="Program.cs" %}

```csharp
static void Main(string[] args)
{
	var app = Zongsoft.Web.Application.Web([..args, "host=web", "site=default", "daemon=zongsoft.web"]);

	//如果要启用私有部署模式则打开下行代码注释
	//app.Configuration["Deployment"] = "private";

	app.Map("/", ctx => { ctx.Response.Redirect("/Application"); return Task.CompletedTask; });
	app.Run();
}
```

{% endcode %}

The project needs to reference [`Zongsoft.Plugins.Web`](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Plugins.Web), and the runtime directory also needs a basic plugin list and business plugins. This entry itself does not generate a business API or database structure.

## Learning Path

* [Deploy Controller Plugins](/documentation/en/framework/web/controllers.md): From class library, manifest to one HTTP request.
* [Requests and Data Service APIs](/documentation/en/framework/web/data-services.md): Connect the data service to the CRUD interface and understand binding, paging and capability switching.
* [OpenAPI and gRPC](/documentation/en/framework/web/protocols.md): View interface documentation, register protocol services and check endpoints.
* [Security](/documentation/en/framework/security.md): Configure credentials, authorization and verification codes.

## Request Status and Shared Services

Web application context can bridge the current request body and session. After the request ends, you cannot continue to rely on the objects in the request; the background task should explicitly receive the required business data instead of retaining the request context. Common plugin services registered through service features default to shared instances, see [Service ownership](/documentation/en/framework/core/services/locating.md) for details.

{% hint style="warning" %}
🚨 Current plugin hosts include a permissive default CORS policy. Before the business goes online, it should be adjusted according to the actual source and credential method; the presence of authentication and authorization middleware does not mean that all endpoints are automatically protected. Management endpoints such as plugins, modules, files, and diagnostics should also be included in the access policy.
{% endhint %}

## Troubleshooting Ideas

First confirm that the host is listening and the network is reachable, then confirm that the plugin is loaded, the assembly is added as a web part, the routing template matches, and finally the service resolution and business dependencies are checked. 404 should usually be investigated through routing and discovery; authentication failure and service denial should be investigated along security and service links.

Implementation basis: [Web portal](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins.Web/src/Application.cs), [Web builder](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins.Web/src/WebApplicationBuilder.cs), [Web basic source code](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Web/src).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/framework/web.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.