> 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/faq.md). # FAQ Locate common issues in plugins, configuration, data, messaging, and delivery by observable phenomena. ## The Package Is Installed, Why Does the Plugin Not Appear? The package reference is used for compilation, and the manifest and related products need to be entered into the scan directory at runtime. Check the actual process path first, then `.plugin`, dependency declarations, and DLLs. See [minimal deployment](/documentation/en/get-started/deploy-first-plugin.md) for complete steps. ## The Plugin Appears, Why Does the First Call Still Fail? Services may delay establishing connections, and third-party dependencies may be overridden by other packages during deployment. Check [service resolution](/documentation/en/framework/core/services/locating.md), the selected connection and the final DLL version; the plugin list only proves part of the loading phase. ## Why Is There No Change After Modifying `.option`? Check whether the file matches the application name or plugin manifest base name, environment and host/site; then check whether subsequent configuration sources overwrite this key. Don't default to all components supporting hot updates on the fly. See [Options configuration](/documentation/en/references/option-files.md) for details. ## Can the Host Portal Write Business Directly? Application composition and startup configuration are the responsibility of the host. Business rules are recommended to be placed in plugin services and then called by commands, [workers](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Components/IWorker.cs) or controllers. This makes it easier to reuse and verify between [Terminal and Web](/documentation/en/hosting/hosting.md). ## Why Are the Results Different for `Resolve`, `Find`, and `Locate`? They are respectively biased towards container registration resolution, service matching, name and provider positioning. Redis in "Connection name @Redis" is a provider alias; other providers may not have corresponding aliases. See [Complete rules](/documentation/en/framework/core/services/locating.md). ## Why Is the Query Missing a Navigation Field? Check mappings and schemas. `*` does not mean full expansion of any level; navigation needs to be declared accordingly. `:20` in navigation is a limited quantity, not a top-level page number. See [Data Schemas](/documentation/en/framework/data/schema.md) and [Query](/documentation/en/framework/data/querying.md). ## Why Does an Asynchronous Query Report an Error in a Loop? Obtaining an asynchronous sequence does not mean that the query has been completed, execution and reading may occur during enumeration. Error handling, cancellation and resource lifecycle should cover the enumeration scope. See [Data Access Interfaces](/documentation/en/framework/data/data-access.md). ## The Message Publishing Returns Successfully, Why Is the Business Not Completed? The return value may represent a local send, a protocol publish result, or a Broker persistent admission. It is not a general business confirmation. ZeroMQ may also return `null` when there is no online matching subscription; Kafka's explicit confirmation needs to consider background automatic commit. See [reliable delivery](/documentation/en/framework/messaging/reliability.md). ## Why Is the Asynchronous Message Handler Not Awaited? The current synchronous delegate subscription overload receives `System.Action`. Passing in the asynchronous lambda will form `async void`. You should implement `IHandler` instead or inherit the asynchronous handler base class, refer to [Message example](/documentation/en/framework/messaging.md). ## The Excel Worksheet Exists, Why Can’t the Import Find the Table? The ClosedXml extractor looks for real Excel Table and model qualified names, such as `__Sales.User__`. A worksheet name or a normal range cannot replace Table. See [spreadsheet extension](/documentation/en/framework/externals/documents.md). ## Why Is the Entry Incorrect After Installation or Upgrade? Distinguish between display name, service name, assembly name and running application name. The packaging tool uses the name inference entry, and the upgrader uses the actual application identity matching release; the web class library `Zongsoft.Web.dll` is not the host entry. See [Pack](/documentation/en/tools/packager.md) and [Upgrade recovery](/documentation/en/framework/upgrading/workflow.md). ## Does the Existence of `.deployment` Mean the Upgrade Is Successful? It indicates that a deployment handover is pending. It is also necessary to confirm the exit of old processes, replacement of files, startup of new processes and business health. Full deployment may clear the data and logs in the application directory, and data storage and recovery must be arranged before deployment. See [Automatic Upgrades](/documentation/en/framework/upgrading.md). ## Which Path Should Be Read First? The first contact starts with [Architecture](/documentation/en/overview/architecture.md) and [basic concepts](/documentation/en/overview/concepts.md), and then completes [Business plugin](/documentation/en/get-started/first-business-plugin.md). If you have existing business needs, go to [Reading navigation](/documentation/en/zongsoft-framework.md) on the homepage to enter the corresponding data, message, Web or external extension topics. --- # 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/faq.md?ask=&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.