Skip to content

Commit 2fdc1fa

Browse files
czhcomczhcom
committed
.Net10 迁移
1 parent 2befd5d commit 2fdc1fa

File tree

1 file changed

+213
-43
lines changed

1 file changed

+213
-43
lines changed

‎README.md‎

Lines changed: 213 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,207 @@
11
## Dorisoy.Pan
22

3-
Dorisoy.Pan 是基于.net core8 的跨平台文档管理系统，使用 MS SQL 2012 / MySql8.0（或更高版本）后端数据库，您可以在 Windows、Linux 或 Mac 上运行它,项目中的所有方法都是异步的,支持令牌基身份验证,项目体系结构遵循著名的软件模式和最佳安全实践。源代码是完全可定制的,热插拔且清晰的体系结构,使开发定制功能和遵循任何业务需求变得容易。
4-
系统使用最新的 Microsoft 技术，高性能稳定性和安全性。
3+
Dorisoy.Pan 是基于 **.NET 10** 的跨平台文档管理系统，使用 MS SQL 2012 / MySQL 8.0（或更高版本）后端数据库，您可以在 Windows、Linux 或 Mac 上运行它。项目中的所有方法都是异步的，支持 JWT 令牌身份验证，项目体系结构遵循 CQRS + MediatR 模式和最佳安全实践。源代码完全可定制，热插拔且清晰的体系结构，使开发定制功能和遵循任何业务需求变得容易。
54

65
商用版本下载：[http://shop.unitos.cn/item/6](http://shop.unitos.cn/item/6)
76

7+
---
8+
9+
### 技术栈
10+
11+
| 分类 | 技术 / 版本 |
12+
|---|---|
13+
| 运行时框架 | .NET 10 (`net10.0`) |
14+
| ORM | Entity Framework Core 10.0.3 |
15+
| MySQL 驱动 | MySql.EntityFrameworkCore 10.0.1（Oracle 官方驱动） |
16+
| SQL Server | Microsoft.EntityFrameworkCore.SqlServer 10.0.3 |
17+
| 身份认证 | ASP.NET Core Identity + JWT Bearer (`Microsoft.AspNetCore.Authentication.JwtBearer 10.0.3`) |
18+
| CQRS / 中介者 | MediatR 14.0.0 |
19+
| 对象映射 | AutoMapper 16.0.0 |
20+
| 参数验证 | FluentValidation 12.1.1 |
21+
| API 文档 | Swashbuckle.AspNetCore 10.1.2 |
22+
| 缓存 | NewLife.Redis 6.4.x（可选，不安装 Redis 时自动降级） |
23+
| 日志 | NLog 6.1.0 |
24+
| JSON | Newtonsoft.Json 13.0.4 |
25+
| 图片处理 | SixLabors.ImageSharp 3.1.12 |
26+
27+
---
28+
829
### 先决条件
930

10-
.NET 7.0+ SDK and VISUAL STUDIO 2019, SQL SERVER, MySQL 8.0
31+
- **.NET 10.0 SDK**（Preview / RC）及以上
32+
- **Visual Studio 2022 17.14+**（或 VS Code + C# Dev Kit）
33+
- **MySQL 8.0+** 或 **SQL Server 2012+**
34+
- **Redis**（可选）—— 用于文件上传并发锁控制，未安装时系统自动降级为无锁模式
35+
- **Node.js >= 14** 及 **npm >= 6**（仅前端 Angular UI 需要）
1136

12-
### 服务端启动步骤
37+
---
1338

14-
1.使用 visual studio 2019+，打开解决方案文件 "Dorisoy.Pan.sln"。
39+
### 服务端启动步骤（Web 目录）
1540

16-
2.右键单击解决方案资源管理器并还原 nuget 软件包。
41+
1. 使用 Visual Studio 2022 或命令行打开解决方案 `Web/Dorisoy.Pan.sln`。
1742

18-
3.在"Dorisoy.Pan.API 项目中更改“appsettings”中的数据库连接字符串。
43+
2. 还原 NuGet 包：
44+
```bash
45+
dotnet restore Web/Dorisoy.Pan.sln
46+
```
1947

20-
4.从“visual studio 菜单-->工具-->nuget 软件包管理器-->软件包管理器控制台”打开软件包管理器控制台。
48+
3. 修改 `Web/Dorisoy.Pan.API/appsettings.json` 中的数据库连接字符串：
49+
```json
50+
"connectionStrings": {
51+
"DocumentDbConnectionString": "server='你的MySQL地址';Port=3306;user='用户名';password='密码';database=dorisoy_pan;Allow User Variables=True",
52+
"Redis": "127.0.0.1:6379"
53+
}
54+
```
55+
> **注意**：如果本地未安装 Redis，保留默认配置即可。系统会自动降级，上传等功能不受影响。
2156
22-
5.在 package manager 控制台中，选择默认项目为 “Dorisoy.Pan.Domain”。
57+
4. 初始化数据库（任选一种方式）：
2358

24-
6.在 package manager 控制台中运行“Update-Database”命令，创建数据库并插入初始数据。
59+
**方式一：使用 EF Core Migration**
60+
```bash
61+
# 在 Package Manager Console 中，默认项目选择 Dorisoy.Pan.Domain
62+
Update-Database
63+
```
2564

26-
7.如果你的数据库为MySQL（示例），请附加SQL/下的SQL脚步 PROCEDURE-MySQL.sql 并重建存储过程。
65+
**方式二：直接执行 SQL 脚本**
66+
- MySQL：执行 `SQL/MySQL.sql`
67+
- SQL Server：执行 `SQL/MsSQL.sql`
68+
- MySQL 存储过程：执行 `SQL/PROCEDURE-MySQL.sql`
2769

28-
8.在解决方案资源管理器中，右键单击“Dorisoy.Pan.API" 然后从菜单中单击 `设置为启动项`。
70+
5. 启动项目：
71+
```bash
72+
dotnet run --project Web/Dorisoy.Pan.API
73+
```
74+
或在 Visual Studio 中将 `Dorisoy.Pan.API` 设为启动项目，按 F5 运行。
2975

30-
9.按 F5 键运行项目。
76+
6. 打开浏览器访问 Swagger：`http://localhost:5000/swagger`
3177

32-
### 前端启动步骤
78+
---
3379

34-
如果您还没有安装 nodejs，请下载并全局安装 nodejs: https://nodejs.org ,确保您的 nodejs 版本>= 4.0 且 NPM >= 3 同时全局安装 TypeScript。
80+
### 前端启动步骤（UI 目录）
3581

36-
全局安装 Angular-CLI 命令："npm install -g @angular/cli"
82+
1. 全局安装 Angular CLI：
83+
```bash
84+
npm install -g @angular/cli
85+
```
3786

38-
1.使用 visual code 打开项目目录 "\UI"。
87+
2. 安装依赖：
88+
```bash
89+
cd UI
90+
npm install
91+
```
3992

40-
2.新建：终端-> "npm install" 初始化安装依赖。
93+
3. 启动开发服务器：
94+
```bash
95+
npm run start
96+
```
4197

42-
3.终端-> "npm run start" 启动 Angular Server。
98+
4. 浏览器访问：`http://localhost:4200`
4399

44-
4.当 ** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ ** 监听时在浏览器运行。
100+
5. 生产构建：
101+
```bash
102+
ng build --configuration production
103+
```
104+
构建产物位于 `UI/dist/` 目录。
45105

46-
要在生产模式下运行本地副本并构建源，请执行 "ng build --prod" ，这将生成应用程序的生产版本，所有 html，css 和 js 代码都被缩小并放入 dist 文件夹。此文件夹可以在发布应用程序时放入生产服务器。
106+
---
47107

48108
### Demo
49109

50110
演示地址：[http://pan.doriso.cn/](http://pan.doriso.cn/)
51111

52-
默认账号：admin@gmail.com 密码：admin@123
112+
默认账号：`admin@gmail.com`　密码：`admin@123`
113+
114+
---
53115

54116
### 项目结构
55117

56-
<pre class="prettyprint">
57-
58-
├──Dorisoy.Pan.sln/ * 解决方案
59-
│ │
60-
│ ├──Dorisoy.Pan.API * REST API Controller, Dependancy configuration, Auto mapper profile
61-
│ │
62-
│ ├──Dorisoy.Pan.MediatR * Command handler, Query handler, Fluent API validation
63-
│ │
64-
│ ├──Dorisoy.Pan.Repository * Each entity repository
65-
│ │
66-
│ ├──Dorisoy.Pan.Domain * Entity framework dbContext
67-
| |
68-
│ ├──Dorisoy.Pan.Common * Generic repository and Unit of work patterns
69-
│ │
70-
│ ├──Dorisoy.Pan.Data * Entity classes and DTO classes
71-
│ │
72-
│ ├──Dorisoy.Pan.Helper * Utility classes
73-
74-
</pre>
118+
```
119+
Web/
120+
├── Dorisoy.Pan.API # REST API 控制器、DI 配置、Swagger、启动入口
121+
├── Dorisoy.Pan.MediatR # CQRS Command/Query Handler、FluentValidation 验证
122+
├── Dorisoy.Pan.Repository # 实体仓储层（AutoMapper Profile）
123+
├── Dorisoy.Pan.Domain # EF Core DbContext、数据库迁移
124+
├── Dorisoy.Pan.Common # 通用仓储、UnitOfWork、查询扩展方法
125+
├── Dorisoy.Pan.Data # 实体类（Entity）、DTO 类
126+
└── Dorisoy.Pan.Helper # 工具类（加密、缩略图、路径等）
127+
128+
Client/ # Avalonia 跨平台桌面/移动客户端
129+
├── Dorisoy.Pan # 主 UI 项目（Avalonia）
130+
├── Dorisoy.Pan.Desktop # 桌面端入口
131+
├── Dorisoy.Pan.Android # Android 端入口
132+
├── Dorisoy.Pan.iOS # iOS 端入口
133+
└── Dorisoy.Pan.Web # WebAssembly 端入口
134+
135+
UI/ # Angular Web 前端
136+
SQL/ # 数据库初始化脚本
137+
Screen/ # 截图资源
138+
```
139+
140+
---
141+
142+
### .NET 10 迁移说明
143+
144+
本项目已从 .NET 8 完整迁移至 .NET 10。以下是迁移过程中的关键变更和注意事项：
145+
146+
#### 1. 目标框架升级
147+
所有 Web 项目的 `TargetFramework` 已从 `net8.0` 更新为 `net10.0`。
148+
149+
#### 2. MySQL 驱动更换
150+
| 变更前 | 变更后 |
151+
|---|---|
152+
| Pomelo.EntityFrameworkCore.MySql 9.0.0 | **MySql.EntityFrameworkCore 10.0.1**（Oracle 官方） |
153+
154+
**原因**：Pomelo 9.0.0 不兼容 EF Core 10，Oracle 官方驱动已支持 .NET 10。
155+
156+
**影响**：
157+
- `MySqlValueGenerationStrategy` 枚举值大小写变更（如 `IdentityColumn` → `IdentityColumn`）
158+
- 命名空间从 `MySqlConnector` 变更为 `MySql.Data.MySqlClient`
159+
- `MySqlParameter` 引用需更新
160+
161+
#### 3. EF Core 10 Contains 查询破坏性变更
162+
EF Core 10 对本地集合的 `Contains()` SQL 翻译方式发生了重大变化，官方建议使用 `EF.Constant()` 包裹。但 **MySql.EntityFrameworkCore 不支持 `EF.Constant()` + `Contains()` 组合**，会抛出：
163+
```
164+
System.InvalidOperationException: Expression '@xxx' in the SQL tree does not have a type mapping assigned.
165+
```
166+
167+
**解决方案**：项目中创建了 `WhereContains` 扩展方法（位于 `Dorisoy.Pan.Common/QueryableContainsExtensions.cs`），用 Expression Tree 动态构建 OR 谓词替代 IN 子句：
168+
```csharp
169+
// 修改前（EF Core 10 + MySQL 会报错）：
170+
.Where(c => allUserIds.Contains(c.Id))
171+
172+
// 修改后：
173+
.WhereContains(c => c.Id, allUserIds)
174+
175+
// 生成 SQL: WHERE Id = @p0 OR Id = @p1 OR Id = @p2 ...
176+
```
177+
178+
> **注意**：仅 EF Core IQueryable 查询需要使用 `WhereContains`，内存中的 LINQ-to-Objects 操作继续使用普通 `.Contains()`。
179+
180+
#### 4. AutoMapper 16.0 构造函数变更
181+
AutoMapper 16.0 移除了接受 `Action<IMapperConfigurationExpression>` 的构造函数，需改用 `MapperConfiguration` 方式创建。
182+
183+
#### 5. Swashbuckle / OpenApi 2.x 破坏性变更
184+
Swashbuckle 10.1.2 依赖 Microsoft.OpenApi 2.x，API 有重大变化：
185+
- `OpenApiSecurityScheme` 构造方式变更
186+
- `AddSecurityRequirement` 签名变更，需使用 lambda 表达式 + `OpenApiSecuritySchemeReference`
187+
188+
#### 6. 数据库自动补列
189+
实体新增了 `Md5` 字段但历史数据库可能没有此列，系统在 `Startup.cs` 中自动检测并执行 `ALTER TABLE` 添加缺失列。
190+
191+
#### 7. Redis 可选降级
192+
文件上传模块使用 Redis 做并发锁控制。当 Redis 不可用时（未安装或连接失败），系统自动降级为无锁模式，不影响正常的文件上传功能。仅在多用户并发上传同一文件时可能丢失锁控制。
193+
194+
---
75195

76196
### 截图
77197

78-
## Desktop 客户端示例
198+
#### Desktop 客户端
79199

80200
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/desktop1.png"/>
81201
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/desktop2.png"/>
82202
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/desktop3.png"/>
83203

84-
## Web 客户端示例
204+
#### Web 客户端
85205

86206
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/s%20(1).png"/>
87207
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/s%20(2).png"/>
@@ -91,3 +211,53 @@ Dorisoy.Pan 是基于.net core8 的跨平台文档管理系统，使用 MS SQL 2
91211
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/s%20(6).png"/>
92212
<img src="https://github.com/dorisoy/Dorisoy.Pan/blob/main/Screen/s%20(7).png"/>
93213

214+
---
215+
216+
### 更新日志
217+
218+
#### v2.0.0（2026-02）
219+
220+
- 目标框架从 .NET 9 升级至 **.NET 10**（`net10.0`）
221+
- 所有 NuGet 依赖升级至最新版本
222+
- MySQL 驱动从 Pomelo.EntityFrameworkCore.MySql 9.0.0 更换为 **MySql.EntityFrameworkCore 10.0.1**（Oracle 官方驱动）
223+
- 新增 `WhereContains` 扩展方法，解决 EF Core 10 + MySql.EntityFrameworkCore 的 `Contains()` 类型映射异常
224+
- 修复 AutoMapper 16.0 构造函数破坏性变更
225+
- 修复 Swashbuckle 10.1.2 + Microsoft.OpenApi 2.x 破坏性变更
226+
- 新增数据库自动补列机制（启动时检测并添加缺失的 `Md5` 列）
227+
- Redis 改为可选依赖，不可用时自动降级为无锁模式
228+
- `appsettings.json` 新增 `ConnectionStrings:Redis` 配置项
229+
- EF Core Migration 适配 Oracle MySQL 驱动（`MySQLValueGenerationStrategy` 枚举、命名空间等）
230+
- 修复 `MySqlConnector` → `MySql.Data.MySqlClient` 命名空间迁移
231+
232+
#### v1.3.0（2025-10）
233+
234+
- 目标框架升级至 **.NET 9**
235+
- 同步升级 EF Core 9、ASP.NET Core 9 等依赖
236+
237+
#### v1.2.0（2025）
238+
239+
- 目标框架升级至 **.NET 8**（LTS）
240+
- 同步升级 EF Core 8、ASP.NET Core 8 等依赖
241+
242+
#### v1.1.0（2024）
243+
244+
- 目标框架升级至 **.NET 7**
245+
- 同步升级 EF Core 7、ASP.NET Core 7 等依赖
246+
247+
#### v1.0.0（2024）
248+
249+
- 首个开源版本发布
250+
- 基于 **.NET 6**（LTS）构建
251+
- 支持 MySQL 8.0 / MS SQL Server 2012+
252+
- 使用 Pomelo.EntityFrameworkCore.MySql 作为 MySQL 驱动
253+
- Angular 前端 + ASP.NET Core Web API 后端
254+
- Avalonia 跨平台桌面客户端（Windows / macOS / Linux）
255+
- JWT 令牌身份验证
256+
- CQRS + MediatR 架构模式
257+
- 文件加密存储、缩略图生成、文件夹共享、星标收藏等核心功能
258+
259+
---
260+
261+
### License
262+
263+
[MIT](LICENSE)

0 commit comments

Comments
 (0)