Cursor rule

1---
2description: CodeSpirit 项目配置规范 - 目标框架、SDK类型、集中式包管理
3globs: *.csproj
4alwaysApply: false
5---
6 
7# csproj 项目配置规范
8 
9## 目标框架
10 
11- **必须使用 .NET 10**: `<TargetFramework>net10.0</TargetFramework>`
12- 添加或更新包时，必须与当前解决方案的包版本保持一致
13 
14## SDK 类型选择
15 
16| 项目类型 | SDK |
17|---------|-----|
18| API 服务 | `Microsoft.NET.Sdk.Web` |
19| 组件库 / 类库 | `Microsoft.NET.Sdk` |
20| AppHost | `Aspire.AppHost.Sdk/13.0.2` |
21 
22## PropertyGroup 配置规范
23 
24### 通用配置
25 
26```xml
27<PropertyGroup>
28  <TargetFramework>net10.0</TargetFramework>
29  <ImplicitUsings>enable</ImplicitUsings>
30</PropertyGroup>
31```
32 
33### Web API 项目
34 
35```xml
36<PropertyGroup>
37  <TargetFramework>net10.0</TargetFramework>
38  <ImplicitUsings>enable</ImplicitUsings>
39  <Nullable>disable</Nullable>
40  <UserSecretsId>{生成的GUID}</UserSecretsId>
41  <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
42  <DockerfileContext>..\..</DockerfileContext>
43</PropertyGroup>
44```
45 
46### AppHost 项目
47 
48```xml
49<PropertyGroup>
50  <OutputType>Exe</OutputType>
51  <TargetFramework>net10.0</TargetFramework>
52  <ImplicitUsings>enable</ImplicitUsings>
53  <Nullable>enable</Nullable>
54  <IsAspireHost>true</IsAspireHost>
55</PropertyGroup>
56```
57 
58### 测试项目
59 
60```xml
61<PropertyGroup>
62  <TargetFramework>net10.0</TargetFramework>
63  <ImplicitUsings>enable</ImplicitUsings>
64  <IsPackable>false</IsPackable>
65</PropertyGroup>
66 
67<ItemGroup>
68  <Using Include="Xunit" />
69</ItemGroup>
70```
71 
72### 需要生成文档的组件库
73 
74```xml
75<PropertyGroup>
76  <GenerateDocumentationFile>true</GenerateDocumentationFile>
77</PropertyGroup>
78```
79 
80## 集中式包管理（Central Package Management）
81 
82> ✅ **重要**: 项目已启用集中式包管理，所有包版本在 `Directory.Packages.props` 中统一管理
83 
84### 包引用规范
85 
861. **添加新包时**：
87   - 首先在 `Directory.Packages.props` 中添加 `<PackageVersion Include="PackageName" Version="x.y.z" />`
88   - 然后在项目文件中添加 `<PackageReference Include="PackageName" />`（**不指定 Version**）
89 
902. **项目文件中的包引用**：
91```xml
92   <!-- ✅ 正确：不指定版本，由 Directory.Packages.props 管理 -->
93   <PackageReference Include="Newtonsoft.Json" />
94   
95   <!-- ❌ 错误：不要指定版本 -->
96   <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
97```
98 
993. **版本覆盖（特殊情况）**：
100   - 仅在必要时使用 `VersionOverride`，并添加注释说明原因
101   - 例如：使用 `Aspire.Microsoft.EntityFrameworkCore.SqlServer` 的项目需要 EF Core 10.0.0
102```xml
103   <!-- 注意：Aspire.Microsoft.EntityFrameworkCore.SqlServer 13.0.2 需要 EF Core 10.0.0 -->
104   <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" VersionOverride="10.0.0" />
105```
106 
1074. **查看所有包版本**：
108   - 查看 `Directory.Packages.props` 文件
109   - 包按功能分类组织（Aspire、EF Core、Extensions 等）
110 
111### 核心框架包版本
112 
113所有包版本在 `Directory.Packages.props` 中定义，主要版本如下：
114 
115| 包类别 | 版本 |
116|--------|------|
117| Aspire.* (大部分) | `13.0.2` |
118| Aspire.Hosting.Elasticsearch | `13.1.0` |
119| Aspire.Elastic.Clients.Elasticsearch | `13.1.0` |
120| Microsoft.Extensions.* | `10.0.0` |
121| Microsoft.AspNetCore.* | `10.0.0` |
122| Microsoft.EntityFrameworkCore.* | `9.0.9` (默认) / `10.0.0` (使用 Aspire EF Core 集成) |
123| Pomelo.EntityFrameworkCore.MySql | `9.0.0` |
124| OpenTelemetry.* | `1.11.1` |
125| StackExchange.Redis | `2.9.32` |
126| Newtonsoft.Json | `13.0.3` |
127| AutoMapper | `13.0.1` |
128| FluentValidation | `11.11.0` |
129| Scrutor | `4.2.2` |
130| LinqKit.Core | `1.2.8` |
131| Polly | `8.5.2` |
132 
133### 测试包版本
134 
135| 包 | 版本 |
136|---|------|
137| Microsoft.NET.Test.Sdk | `17.13.0` |
138| xunit | `2.9.3` |
139| xunit.runner.visualstudio | `3.0.2` |
140| Moq | `4.20.72` |
141| coverlet.collector | `6.0.4` |
142| Microsoft.EntityFrameworkCore.InMemory | `9.0.9` |
143| FluentAssertions | `7.0.0` |
144| NBomber | `6.2.0-beta.4` |
145 
146## 项目引用路径
147 
148- 使用相对路径 `..\..\` 格式
149- 路径分隔符使用反斜杠 `\`
150 
151### 示例
152 
153```xml
154<ItemGroup>
155  <ProjectReference Include="..\..\CodeSpirit.Core\CodeSpirit.Core.csproj" />
156  <ProjectReference Include="..\..\CodeSpirit.Shared\CodeSpirit.Shared.csproj" />
157</ItemGroup>
158```
159 
160## 工具包配置
161 
162对于仅作为开发工具使用的包，需添加资产限制：
163 
164```xml
165<PackageReference Include="Microsoft.EntityFrameworkCore.Tools">
166  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
167  <PrivateAssets>all</PrivateAssets>
168</PackageReference>
169```
170 
171## 迁移文件夹
172 
173API 项目如需 EF 迁移，应创建按数据库类型分离的迁移目录：
174 
175```xml
176<ItemGroup>
177  <Folder Include="Data\Migrations\MySql\" />
178  <Folder Include="Data\Migrations\SqlServer\" />
179</ItemGroup>
180```
181 
182## 传递依赖处理
183 
184### 避免冗余引用
185 
186以下包通过项目引用传递可用，通常不需要显式引用：
187 
188- **通过 `CodeSpirit.Shared` 传递**：
189  - `Newtonsoft.Json`
190  - `Microsoft.EntityFrameworkCore.SqlServer`
191  - `Pomelo.EntityFrameworkCore.MySql`
192  - `LinqKit.Core`
193  - `Microsoft.EntityFrameworkCore`
194  - `RabbitMQ.Client`
195  - `Aspire.RabbitMQ.Client`
196 
197- **通过 `CodeSpirit.ServiceDefaults` 传递**：
198  - `Aspire.Seq`
199  - `Aspire.StackExchange.Redis.DistributedCaching`
200 
201- **通过 `FrameworkReference` 提供**：
202  - `Microsoft.AspNetCore.Http.Abstractions`（.NET 10）
203  - `Microsoft.AspNetCore.Mvc.Core`（.NET 10）
204 
205如果项目确实需要这些包，应添加注释说明原因。
206 
207## 禁止事项
208 
209- ❌ **不要在 PackageReference 中指定 Version**（使用集中式包管理）
210- ❌ 不要混用不同版本的同一包
211- ❌ 不要使用 `<LangVersion>` 指定语言版本（使用框架默认）
212- ❌ 不要在 PackageReference 中使用浮动版本 (如 `*`)
213- ❌ 不要使用绝对路径引用项目
214- ❌ 不要添加通过传递依赖已可用的包引用（除非有特殊需求）