# C# 编码规则

## 版本与组织

- `Directory.Build.props` 指定 C# 14；属性优先使用 `field` 关键字管理编译器生成的后备字段。目标框架以各 `.csproj` 的覆盖值为准。
- 可使用 C# 14 及此前版本的语言特性，调用 API 仍须兼容目标框架。保留各项目 Nullable 设置；开发环境需要支持 C# 14 的 SDK。
- 类型、方法、公开属性使用 PascalCase，参数和局部变量使用 camelCase；私有字段沿用文件现有风格。
- 命名空间匹配项目与目录，例如 `Store.Management.Api.Users`；Core 项目保留 `MAX.*` 命名空间。
- 新文件优先文件范围命名空间；不批量重排无关代码。
- 新代码优先显式类型；修改已有代码时不批量替换 var。控制流使用大括号，每条语句独立一行，避免无意义空行。
- 公共接口及复杂行为补充 XML 注释，解释约束和原因，不要求固定注释比例。
- 对职责一致的重复逻辑适度提取，避免重复实现传输、配置和容器功能，不为单次用途增加多层抽象。

## MVVM、DI 与异步

- ViewModel 使用 Prism `BindableBase`，属性优先以 `field` 配合 `SetProperty(ref field, value)`；需要跨成员访问或特殊存储语义时保留显式字段，不引入 DevExpress MVVM。
- 命令使用现有 DelegateCommand / AsyncDelegateCommand；服务优先构造注入，由现有 Prism/Autofac 容器管理生命周期。
- 调用内部库 API 前核实当前项目的依赖和类型；不要为了简单工具让 API/Core 依赖 UI 包。
- 异步返回 Task 并按需传递 CancellationToken；async void 限于 UI 事件。
- 不在 UI 线程用 Result/Wait 阻塞网络或文件操作；库层可 ConfigureAwait(false)，更新控件和绑定时回到 UI 线程。
- 公共入口校验参数，API DTO 沿用 DataAnnotations；区分取消、业务失败和致命错误。
- 复用现有 NLog 封装记录错误，保留异常类型和上下文，不强制每个 catch 调用 Debug.WriteLine，不记录密码或 Token。
- 释放自有 IDisposable、取消源与事件订阅；注入的外部 HttpClient 由调用者管理。

## 序列化

API 层保持 System.Text.Json / RestSharp 协议；JSON 配置服务保持 Newtonsoft.Json 格式。不因统一库名而改变服务端字段、配置兼容性或增加依赖。

## field 属性示例

```csharp
public string Keyword
{
    get => field ?? string.Empty;
    set => SetProperty(ref field, value);
}

public DelegateCommand RefreshCommand => field ??= new DelegateCommand(Refresh);
```

属性的初始值、可空性与通知行为应按实际需求明确；不要仅为使用 field 改写无关代码。