## 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](https://framework.docs.xihanfun.com) | Full guides and per-package API docs for all 66 packages |
| [Framework engineering notes](./framework/README.md) | Layered architecture, module catalog, directory layout, dependencies |
| [Changelog](https://framework.docs.xihanfun.com/changelog) | Release notes and upgrade advisories |
| [Contributing guide](./CONTRIBUTING.md) | 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, plus Newtonsoft.Json pulled in transitively by SqlSugar, 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) |
| 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:
```bash
# 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]`:
```csharp
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
```csharp
using XiHan.Framework.Core.Extensions.DependencyInjection;
using XiHan.Framework.Web.Core.Extensions.DependencyInjection;
var builder = WebApplication.CreateBuilder(args);
await builder.AddApplicationAsync
