XiHan.Framework

A fast, lightweight, efficient and thoughtfully built modern modular framework for .NET

Built on .NET 10 · 66 modular components · [DependsOn] declarations · topologically sorted loading

English | 简体中文

Overview

XiHan.Framework is a modular backend framework for enterprise applications, designed for ASP.NET Core services in a decoupled frontend/backend setup. It prefers what .NET already provides over third-party libraries, and puts the emphasis on clear module boundaries, controlled dependencies and maintainable extension points. Modules declare their dependencies with the [DependsOn] attribute and are loaded in topological order; application services plus dynamic API conventions give every module the same way to expose its endpoints.

Documentation

Destination	Contents
Documentation site	Full guides and per-package API docs for all 66 packages
Framework engineering notes	Layered architecture, module catalog, directory layout, dependencies
Changelog	Release notes and upgrade advisories
Contributing guide	Branch conventions, commit rules, local build and test

Design Principles

• Layered architecture — follow clear layering, no circular dependencies
• Dependency inversion — higher layers do not depend on lower ones; both depend on abstractions
• Single responsibility — each package owns exactly one functional area
• Open/closed — open for extension, closed for modification, customizable through interfaces and base classes
• .NET 10 first — use the built-ins (DI, logging, serialization) and reach for third-party libraries only when necessary
• Performance — built on .NET 10's high-performance features; AOT is out of scope (SqlSugar / Castle DynamicProxy / Newtonsoft.Json are not trimming-compatible yet)

Tech Stack

Category	Technology
Runtime	.NET
Language	C#
ORM	SqlSugarCore
Logging	Serilog.AspNetCore
Caching	Microsoft.Extensions.Caching.Hybrid + StackExchangeRedis
AOP	Castle.Core (DynamicProxy)
Cryptography	BouncyCastle.Cryptography
Serialization	System.Text.Json (built-in) + Newtonsoft.Json
Templating	Scriban
AI	Microsoft.Extensions.AI + Microsoft.Agents.AI + MCP
HTTP resilience	Microsoft.Extensions.Http.Polly
gRPC	Grpc.AspNetCore
Realtime	ASP.NET Core SignalR
API docs	Scalar.AspNetCore + Swashbuckle.AspNetCore
IP geolocation	IP2Region.Net
Notifications	MailKit + Telegram.Bot
Search	Elastic.Clients.Elasticsearch
Testing	xunit.v3 + Microsoft.Testing.Platform (with the CodeCoverage extension)

Exact versions live in the PackageReference entries under framework/src.

Getting Started

Install

Install the modules you need from NuGet:

# Core module
dotnet add package XiHan.Framework.Core

# Web API module (includes the full middleware pipeline)
dotnet add package XiHan.Framework.Web.Api

# API documentation module
dotnet add package XiHan.Framework.Web.Docs

# Data access module
dotnet add package XiHan.Framework.Data

Define a Module

Every module derives from XiHanModule and declares its dependencies with [DependsOn]:

using XiHan.Framework.Core.Modularity;
using XiHan.Framework.Web.Api;
using XiHan.Framework.Data;

[DependsOn(
    typeof(XiHanWebApiModule),
    typeof(XiHanDataModule)
)]
public class MyAppModule : XiHanModule
{
    public override Task ConfigureServicesAsync(ServiceConfigurationContext context)
    {
        // Register services
        return Task.CompletedTask;
    }

    public override Task OnApplicationInitializationAsync(ApplicationInitializationContext context)
    {
        // Initialize the application
        return Task.CompletedTask;
    }
}

Bootstrap the Application

using XiHan.Framework.Core.Extensions.DependencyInjection;
using XiHan.Framework.Web.Core.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);
await builder.AddApplicationAsync<MyAppModule>();

var app = builder.Build();
await app.InitializeApplicationAsync();
await app.RunAsync();

Module Lifecycle

Each module exposes 7 lifecycle hooks, executed in topological order:

Service registration                  Application initialization
┌──────────────────────┐            ┌────────────────────────────────┐
│ PreConfigureServices │            │ OnPreApplicationInitialization │
│ ConfigureServices    │     →      │ OnApplicationInitialization    │
│ PostConfigureServices│            │ OnPostApplicationInitialization│
└──────────────────────┘            └────────────────────────────────┘
                                                  ↓
                                    ┌────────────────────────────────┐
                                    │ OnApplicationShutdown          │
                                    └────────────────────────────────┘

NuGet Packages

Every module is published to NuGet.org; package names match project names:

# Search all XiHan.Framework packages
dotnet package search XiHan.Framework

Common package	Purpose
XiHan.Framework.Core	Modularity core (required)
XiHan.Framework.Web.Api	Full Web API middleware pipeline
XiHan.Framework.Web.Docs	Scalar + Swagger documentation
XiHan.Framework.Data	SqlSugar data access
XiHan.Framework.Caching	HybridCache + Redis
XiHan.Framework.Authentication	JWT / OAuth2 authentication
XiHan.Framework.Authorization	RBAC authorization
XiHan.Framework.EventBus	Event bus + outbox
XiHan.Framework.AI	Microsoft.Extensions.AI + MCP

The full module catalog lives in the framework engineering notes.

Requirements

Dependency	Version
.NET SDK	10.0+
C#	Latest
Platforms	Windows / Linux / macOS

Ecosystem

• XiHan.Framework - A fast, lightweight, efficient and thoughtfully built modern modular framework for .NET
• XiHan.UI - A fast, lightweight, efficient and thoughtfully built framework-agnostic headless UI component library
• XiHan.BasicApp - A beautifully crafted general-purpose admin kernel built on .NET (XiHan.Framework) and TypeScript (XiHan.UI)

Contributing

Issues and pull requests are welcome — see the contributing guide.

Acknowledgements

In no particular order.

Project	Thanks for
Abp	Inspiring parts of the architecture and design
Other third-party dependencies	Being the foundation this project is built upon

Support & Sponsorship

If this project helps your work, feel free to buy the author a coffee.

Official sponsorship page: https://docs.xihanfun.com/cosmos/sponsor

License

Copyright (c) 2021-Present XiHanFun and contributors.

Released under the MIT License — see License.

The XiHan.Framework logo and name belong to the author; third-party dependencies and services are governed by their own licenses and terms.

This project is provided for study and reference; the author assumes no liability for any use of the software.