> 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/framework/plugins/application-model.md).

# 插件应用模型

理解插件式应用中的宿主、应用上下文、模块和服务。

插件式应用由宿主程序、插件框架、插件树、应用上下文和[应用模块](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/IApplicationModule.cs)组成。宿主负责“进程如何启动”，插件负责“能力如何进入应用”。

## 宿主程序

宿主程序负责启动进程并建立运行环境。它通常只包含 `Program.cs`、项目文件、部署脚本和基础配置。业务能力应尽量放入插件，而不是固化在宿主中。

框架提供两类常用启动入口：

* `Application.Daemon(...)`：用于后台服务、Worker 和常驻进程。
* `Application.Terminal(...)`：用于命令行、终端工具和交互式程序。

这些入口会创建 .NET Host，加载宿主 `.option` 配置，注册插件配置源，加载插件树并初始化应用上下文。

## 应用上下文

应用上下文表示当前运行中的应用实例，对应核心库中的 [`IApplicationContext`](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/IApplicationContext.cs)。它包含应用名称、版本、环境、配置、模块集合、服务提供器、事件管理器、[工作器](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Components/IWorker.cs)和运行时属性。

Web 宿主中的 `/Application` 接口会返回当前应用上下文的基本信息。

## 模块

模块对应核心库中的 [`IApplicationModule`](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/IApplicationModule.cs)。模块有名称、版本、程序集、服务容器和属性集合；继承 `ApplicationModule<TEvents>` 的模块还可以拥有自己的事件注册表。

模块名称很重要：数据访问、服务注册、日志命名和模块隔离都会使用模块名作为边界。例如数据服务默认会根据类型所在程序集的 [`ApplicationModuleAttribute`](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/ApplicationModuleAttribute.cs) 查找模块名，再获得对应的数据访问器。

Web 宿主中的 `/Modules` 接口可用于查看当前加载的模块信息。

## 服务

插件可以向应用注册服务。宿主启动时会扫描宿主程序集和插件清单中的程序集，把符合服务注册约定的类型加入服务容器；插件树中的 `/Workspace/Environment/Services` 节点也可以把声明式构件注册为单例服务。

模块也可以拥有自己的服务域。[`ApplicationModule`](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/ApplicationModule.cs) 会基于应用服务容器创建模块级服务提供器，用于隔离或命名模块内部服务。

## 工作台与启动节点

默认插件会把常用运行时对象挂载到 `/Workbench` 下，例如：

* `/Workbench/Modules`：当前[应用模块](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/IApplicationModule.cs)集合。
* `/Workbench/Services`：当前应用服务容器。
* `/Workbench/Events`：全局事件管理器。
* `/Workbench/Configuration/ConnectionSettings/Drivers`：连接设置驱动集合。
* `/Workbench/Startup`：启动时需要加载或运行的[工作器](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Components/IWorker.cs)集合。

这使插件之间可以通过稳定路径发现能力，而不是直接引用彼此的实现类型。

## 从业务边界到运行实例

插件和模块没有自动的一一对应关系。模块对象由应用定义，并通过 `/Workbench/Modules` 加入应用；程序集上的 [`ApplicationModuleAttribute`](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/ApplicationModuleAttribute.cs) 则参与类型的模块归属。两者应使用一致的模块名。完整声明和调用见[第一个业务插件](/get-started/first-business-plugin.md)。

模块容器优先解析模块服务，再回退应用共享服务，适合业务局部实现与公共基础设施协作。它不会自动建立独立进程、数据库或请求作用域，详见[基础概念](/overview/concepts.md#module-service-provider)。

## 启动与停止的职责

构建宿主期间先加载插件树并注册服务，随后初始化应用上下文。[工作台](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins/src/IWorkbenchBase.cs)首次构建时组织其子节点，并将 Startup 子树后置；宿主进入启动、停止阶段时打开和关闭工作台。

对象构造、应用初始化和持续工作是不同阶段。需要保持消息订阅或周期任务的组件应使用[工作器](/framework/core/components/worker.md)管理启动、取消和释放；不要依靠构造函数启动无法停止的后台任务。

{% hint style="warning" %}
🚨 插件节点构建失败不代表所有已发生的外部操作都能回滚。组件应控制构造副作用，并实现明确的停止和清理路径。
{% endhint %}

源码定位：[应用上下文](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Plugins/src/PluginApplicationContext.cs)、[模块容器](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Services/ApplicationModule.cs)。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/plugins/application-model.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.