How dotnetcore/freesql works
Project Type and Purpose
• This is a monolithic, modular .NET ORM framework (FreeSql) designed as a library/SDK rather than a standalone application.
• Purpose: Provide a unified O/RM abstraction over multiple databases (MySQL, SQL Server, PostgreSQL, SQLite, Oracle, ClickHouse, etc.), plus optional higher-level patterns (DbContext, Repository/UnitOfWork), code generation, and extension points.
File Structure
• Top-level Modules:
• FreeSql (core engine)
• Providers (one subfolder per database provider)
• Extensions (AggregateRoot, BaseEntity, EFModel, JsonMap, LazyLoading, ZeroEntity, Generator)
• FreeSql.DbContext, FreeSql.Repository, FreeSql.All (package orchestrators)
• Examples (usage demos per pattern)
• Tests (unit/functional tests organized by feature and provider)
• Build & CI: Directory.Build.props, .github/workflows/docfx.yml (documentation), gitee-mirror.yml.
• Docs: README.md, README.zh-CN.md.
README for Insights
• Confirms core features: CodeFirst, DbFirst, advanced mapping, Expression analysis, navigation properties, read/write separation, filters, optimistic/pessimistic locks.
• Highlights supported databases and optional modules: Repository/UnitOfWork, BaseEntity, Generator tool.
a. Main Components
1. Consumer Layer
• Examples & End User Applications call into FreeSql APIs.
2. FreeSql Core
• FreeSqlBuilder, IFreeSql, key abstractions (Interfaces, DataAnnotations, Internal engines).
3. Provider Layer
• FreeSql.Provider.* (MySql, SqlServer, PostgreSQL, Oracle, etc.)
• Implements IAdo, IAop, ICodeFirst, IDbFirst, IFreeSql interfaces.
4. Extensions Layer
• FreeSql.Extensions.* (AggregateRoot, BaseEntity, EFModel, JsonMap, LazyLoading, ZeroEntity)
• FreeSql.Generator (code-gen tooling).
5. Higher-Level Patterns
• FreeSql.DbContext (Repository + UnitOfWork wrapper)
• FreeSql.Repository (generic repository)
• FreeSql.All (umbrella package)
6. Persistence Targets
• Relational Databases (MySQL, PostgreSQL, SQL Server, SQLite, etc.)
• NoSQL/Time Series (ClickHouse, TDengine, QuestDB)
7. Supporting Components
• Tests (unit and provider-specific tests)
• Documentation (DocFX pipeline)
• CI/CD (GitHub Actions).
b. Relationships & Data Flow
• Consumer Layer → FreeSqlBuilder (core API)
• FreeSqlBuilder configures:
• Selected Provider (e.g., .UseConnectionString(DataType.MySql, …))
• Optional Extensions/Plugins (e.g., UseAutoSyncStructure, AOP hooks)
• Core API invokes Extension hooks (Global filters, AOP delegates).
• Core dispatches SQL generation calls down into the selected Provider.
• Provider maps to AdoProvider → AdoCommand → AdoConnection → DB
• Higher-Level Patterns (DbContext, Repository) sit atop Core, orchestrating transactions and object graph persistence.
• Generator tool introspects database schema via Provider layer and emits model classes (DbFirst).
c. Architectural Patterns & Design Principles
• Layered Architecture: clear separation of Core, Provider, Extensions, and Consumer layers.
• Dependency Inversion: interfaces in Core, implementations in Providers & Extensions.
• Plugin/Extension points: Extensions and Providers loaded via DI or builder pattern.
• Repository & UnitOfWork patterns in FreeSql.DbContext module.
• Single Responsibility: each package/project has narrow focus (Core vs. Provider vs. Extension).
d. Technologies & Frameworks
• C#/.NET Standard libraries
• GitHub Actions (CI: DocFX documentation publishing, NuGet packaging)
• DocFX for docs site
• Fody in Examples (transaction weaving)
• Razor (in Generator module) for code templates
Detailed Capture
• Core components: list sub-modules (DataAnnotations, Interface, Internal, Extensions folder under FreeSql).
• Provider component for each supported DB family.
• Extension modules as optional plugins.
• FreeSql.All as meta-package that brings Core, Providers, Extensions together.
• CI/CD and docs pipeline as side processes, not in data path but in lifecycle.