Zongsoft Framework

English | 简体中文

---

This is a collection of open source projects for the Zongsoft development framework, supporting .NET 8,9,10 and other versions. The ecosystem of pluggable applications is a big strength of Zongsoft, help us build it!

💡 After cloning this project's source code, you need to use the git submodule update command to update the submodules.

• 🛠️ Contributors can use the code analysis checks to verify coding style and build diagnostics.
• 📦 Maintainers should read the NuGet publishing guide before releasing packages.

Where to Start

A typical Zongsoft application consists of a host, business plugins and capability plugins. The host owns startup and lifecycle; business modules compile against Core or shared contracts; deployment manifests and configuration compose implementations for databases, caching, messaging and expressions.

Your task	Starting point
Understand application/module containers, named providers and injection	Core guide
Create a host, deploy capabilities and write a decoupled consumer plugin	Plugin runtime guide
Deploy a controller as a plugin and verify HTTP requests	Complete Web plugin example
Configure model mappings and database drivers	Data engine
Select message drivers, subscriptions and reliable storage	Message drivers and Core messaging contracts
Change framework implementations or collaborate with AI	AGENTS.md and skill routing

💡 dotnet add package supplies compile-time references; it does not deploy plugins. Applications normally obtain shared interfaces through ApplicationContext.Current.Services, an application-defined Module.Current.Services and agreed configuration, without constructing each third-party implementation in business modules.

🚨 Plugins execute with host privileges, not in a sandbox. Deployment manifests can overwrite files, while databases, cloud services, brokers and model calls can have side effects. Verify in isolation before connecting real workloads.

Projects

• Zongsoft.Core

  Includes shared interfaces, classes, enumerations, etc., providing the necessary core functionality for the Zongsoft development framework.

• Zongsoft.Data

  An ORM data engine that provides GraphQL-like functionality, with drivers including:

  • mssql Microsoft SQL Server Driver
  • mysql MySQL/MariaDB Driver
  • sqlite SQLite Driver
  • duckdb DuckDB Driver
  • postgres PostgreSQL Driver
  • influxdb InfluxDB Driver
  • tdengine TDengine Driver
  • clickhouse ClickHouse Driver

• Zongsoft.Commands

  Provides some commonly used commands, enabling the application layer to execute specific functions via the command line.

• Zongsoft.Diagnostics

  Provides common OpenTelemetry configuration, Console/OTLP export and protocol processing without an ASP.NET Core dependency.

  • Zongsoft.Diagnostics.Web: Prometheus/Kestrel scraping for Web hosts only; daemon and terminal export metrics through a Collector.

• Zongsoft.Hardwares

  Provides cross-platform functionality for retrieving hardware information.

• Zongsoft.Intelligences

  Provides a suite of AI functionalities including Large Language Models, Agents, and Retrieval Augmented Generation，implemented as plugins based on libraries such as Microsoft.Extensions.AI and Microsoft.Agents.AI.

• Zongsoft.Net

  Provides support for high-performance network communication based on new technologies such as Pipelines and Buffers.

• Zongsoft.Plugins

  Provides essential features for plugin application development.

• Zongsoft.Plugins.Web

  Provides plugin support for the Web applications.

• Zongsoft.Reporting

  Provides report application development capabilities.

• Zongsoft.Security

  Provides security-related capabilities, including authentication, authorization, password, certificates, etc.

• Zongsoft.Web

  Provides general capabilities for the Web application development.

  • open-api

    Provides a pluggable extension for the Open-API specification.

  • grpc

    Provides a pluggable extension for gRPC on the ASP.NET server side.

• messaging

  • kafka

    Provides plugin support for the Kafka message queues.

  • rabbit

    Provides plugin support for the RabbitMQ message queues.

  • mqtt

    Provides plugin support for the Mqtt message queues.

  • zero

    Provides plugin support for the ZeroMQ message queues.

• upgrading

  • deployer

    A local deployer for automatic upgrading, published as a standalone Native AOT application.

  • upgrader

    An upgrader plugin library for automatic upgrading, providing update detection, downloading, and deployment support for host applications.

  • web

    A Web server-side plugin library for automatic upgrading, providing release package publishing and download service support.

  • tool

    An automatic upgrade packaging tool, providing the pack, checksum, and publish subcommands.

• externals

  • aliyun

    Provides plugin support for Alibaba Cloud-related services, implemented based on Alibaba Cloud RESTful API interfaces.

  • amazon

    Provides plugin support for Amazon Web Services related services, based on the plugin framework of the open-source AWS-SDK project.

  • closedxml

    Provides functions such as spreadsheet (Excel) generation, extract, import, export, and template rendering, based on the ClosedXml open source project's plugin architecture.

  • hangfire

    Provides time-based task scheduling functionality based on the Hangfire open source project's plugin architecture.

  • redis

    Provides features such as distributed caching, distributed locks, and sequence number generation, based on the plugin architecture of the StackExchange.Redis open-source project.

  • polly

    Provides transient fault resilience handling features such as Timeout, Retry, Fallback, Circuit Breaker, and Rate Limiter, based on the plugin architecture of the Polly open source project.

  • opc

    Provides OPC IoT protocol connection, read&write, subscription, and other functions based on the OPC Foundation open source projects.

  • lua

    Provides Lua expression parsing and calculation, script execution, and other functions based on the NLua open source project's plugin architecture.

  • python

    Provides Python expression parsing and calculation, script execution, and other functions based on the IronPython open source project's plugin architecture.

  • scriban

    Provides Scriban expression parsing and calculation, text template rendering, and other functions based on the Scriban open source project's plugin architecture.

  • wechat

    Provides WeChat authentication, WeChat Pay, WeChat Media Platform, and other related functions, implemented based on the WeChat RESTful API interface.

Code Analysis

Framework uses the Zongsoft.CodeAnalysis NuGet package. Directory.Build.props adds a development-only reference to C# projects, and Directory.Packages.props controls the version. Analyzer sources, tests, build settings and C# rules are maintained only in guidelines and update with the package. The root .editorconfig retains editor settings and existing VB preferences. See the coding guidelines and coverage guide for the complete rules and limitations.

Check commands · EditorConfig synchronization · Restore and upgrade

Check commands

After restoring the target project, run these checks from the repository root. This example checks Core; replace the project and file paths for your change:

dotnet build ./Zongsoft.Core/src/Zongsoft.Core.csproj --no-restore -p:GeneratePackageOnBuild=false
dotnet format whitespace ./Zongsoft.Core/src/Zongsoft.Core.csproj --no-restore --verify-no-changes --include ./Zongsoft.Core/src/Components/Handler.cs
dotnet format style ./Zongsoft.Core/src/Zongsoft.Core.csproj --no-restore --verify-no-changes --diagnostics IDE0049

These commands do not rewrite source files. --include paths are relative to the working directory. C# builds run in strict mode by default and treat configured style violations as errors. ZS0005 replaces IDE0005 and permits ordinary using System;; unused-import checks still require XML documentation generation; CS4014 and CA2012 remain errors. IDE0049 does not run during builds, so the editor or the separate dotnet format style check is needed. Use dotnet restore for the target project before the first check.

Directory.Build.props sets ZongsoftCodeStyleStrict=true for local, CI, and NuGet publishing builds. This checks the entire project and any project references actually built, not just changed lines. Builds follow the project's configured target frameworks; formatting checks do not replace compilation and analysis for each target. CI checks the strict build; run the separate IDE0049 command when reviewing style changes.

💡 dotnet format whitespace compares formatted text directly and does not apply diagnostic suppressors. It may still report permitted directive indentation or compact try/catch/finally blocks; loaded-analyzer build diagnostics govern these exceptions. Keep --verify-no-changes for verification. Limit intentional formatting fixes to changed files and inspect the diff. Do not run unrestricted repository-wide formatting, import organization or public API renaming.

Using aliases, production global imports, dependency grouping and import length ordering, Chinese region labels, field qualification by visibility, and design contracts still require review. Standard import organizers use alphabetical ordering and cannot implement the guideline's length ordering.

C# rules update with the package; do not duplicate them in the root EditorConfig. Git checks out C# files with CRLF to match EditorConfig; new text files default to CRLF, with LF for shell scripts. Preserve existing encodings and BOMs; existing LF files need a local EditorConfig override to prevent editor-driven line-ending conversion.

EditorConfig synchronization

Directory.Build.props sets the synchronization destination to the framework root:

<ZongsoftGuidelinesSynchronization>$(MSBuildThisFileDirectory)</ZongsoftGuidelinesSynchronization>

With Zongsoft.CodeAnalysis 0.2.0 or later, actual builds automatically synchronize the root .editorconfig from the package template. Files with matching sizes and modification times are skipped, and subdirectory overrides are preserved. No manual synchronization or check command is needed; review and commit changes.

VS fast up-to-date checking remains enabled. If VS skips a project, use Rebuild or Clean followed by Build. Standalone clean, restore and design-time builds do not synchronize. Restore a package version that includes this synchronization implementation. See the synchronization guide.

Restore and upgrade

Ensure the required version has been published to a configured NuGet source, then restore the project normally. The package automatically loads the analyzer, build settings and global C# rules. No copied sources, manual props imports or submodule are required. PrivateAssets="all" prevents the framework's business packages from imposing this analyzer on downstream consumers; business systems reference it explicitly.

Before the first publication, validate a local package:

dotnet pack ../guidelines/analysis/analyzers/src/Zongsoft.CodeAnalysis.Analyzers.csproj -c Release
dotnet restore ./Zongsoft.Core/src/Zongsoft.Core.csproj --source ../guidelines/analysis --source 'https://api.nuget.org/v3/index.json'
dotnet build ./Zongsoft.Core/src/Zongsoft.Core.csproj --no-restore -p:GeneratePackageOnBuild=false

The local source is only for pre-publication validation and is not added to repository configuration. An unpublished version cannot be restored from public feeds in a fresh checkout or CI. Once published to an accessible feed, normal development does not require an adjacent guidelines directory.

For upgrades, change, validate and publish the package in guidelines, then update its version in Directory.Packages.props, restore and build. Roll back by selecting an earlier package version. Synchronize the package's .editorconfig template when basic editor settings change.

The packaged Global AnalyzerConfig controls C# diagnostics. Matching local EditorConfig settings take precedence, so retain only intentional project overrides. Both repositories now have identical root EditorConfig files without duplicated C# rules. See Microsoft's configuration documentation for precedence and package distribution.

Contributing

Please do not submit a Question and Discussion in the Issues of the project. Issues are used to report bugs and features. If you wish to participate in the contribution, you are welcome to submit a code merge request(PullRequest) or an issue.

For new features, be sure to create a functional feedback(Issue) to describe your recommendations in detail so that we can fully discuss them, which will also allow us to better coordinate our work to prevent duplication of development and help you adjust recommendations or requirements to make it successfully accepted into the project.

You are welcome to write articles for our open source projects to promote, if you need to forward your Articles, Blogs, Videos, etc. on the official website(http://zongsoft.com/blog), you can contact us by email.

If you're new to posting issues, we ask that you read "How To Ask Questions The Smart Way", "How to Ask a Question in Open Source Community" and "How to Report Bugs Effectively" prior to posting. Well written bug reports help us help you!

Sponsorship

We look forward to your support and sponsorship. You can provide us with the necessary financial support in the following ways:

1. Follow the Zongsoft WeChat public account and reward our articles;
2. Follow the Zongsoft Organization and make a donation to us;
3. If your organization requires on-site technical support and coaching, or if you need some new features, instant bug fixes, etc., please contact us by email.

License

Licensed under the LGPL license.