# csharp-code-scan

**Repository Path**: chusj/csharp-code-scan

## Basic Information

- **Project Name**: csharp-code-scan
- **Description**: 用于快速扫描C#代码项目的注释，主要是提取类(文件)注释 和 方法注释
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# .NET 代码注释分析工具

[.NET](https://dotnet.microsoft.com/) | [Roslyn](https://github.com/dotnet/roslyn) | [EPPlus](https://epplussoftware.com/)

基于 **Roslyn API** 的代码注释覆盖率统计分析工具，适用于 .NET Framework / .NET 项目。自动扫描 `.csproj` 中的 C# 源文件，统计类、接口、方法的 XML 文档注释覆盖率，并将结果导出为结构化的 Excel 报表，便于团队进行代码质量合规检查（合同要求注释率 ≥ 80%）。

## 功能特性

- **自动识别项目结构**：输入目录路径，自动递归查找 `.csproj` 文件；检测到 `.sln` 时自动按解决方案分组，每个 `.sln` 对应一个 Excel 输出文件
- **注释覆盖率统计**：基于 Roslyn 语法树，精确识别 `///` 单行注释与 `/** */` 多行注释，统计类/接口/方法的注释覆盖情况
- **多维度数据输出**：
  - **file sheet**：文件级别统计（文件名、类型、类名、注释状态、代码行数）
  - **method sheet**：方法级别统计（修饰符、方法名、注释状态、代码行数、同文件内调用次数）
  - **汇总页**：每个项目的概览统计，含注释合格率与合规判断（✅ 达标 / ❌ 未达标）
- **大文件/大方法检测**（可选）：通过 `appsettings.json` 配置，可生成独立 sheet 列出超过指定行数的文件和大型方法
- **智能过滤**：自动排除 `.Designer.cs`、构造函数、WinForms 事件处理方法（`_Click`、`_Load`、`_SelectedValueChanged`）
- **Excel 友好体验**：冻结首行、自动筛选、列宽自适应、达标/未达标颜色标识

## 系统要求

- [.NET 8 Runtime](https://dotnet.microsoft.com/download/dotnet/8.0) 或更高版本
- Windows / Linux / macOS

## 快速开始

### 1. 克隆仓库

```bash
git clone https://github.com/<your-username>/code-analysis.git
cd code-analysis
```

### 2. 还原依赖

```bash
dotnet restore
```

### 3. 运行

```bash
dotnet run -- "E:\\path\\to\\your\\project"
```

> **注意**：Windows 路径中的反斜杠 `\` 在命令行中需转义为 `\\`。

程序启动后进入循环模式，分析完成后可继续输入其他项目路径，或使用以下方式退出：

| 操作 | 说明 |
|------|------|
| 输入 `Q` / `q` | 退出 |
| 输入 `exit` / `quit` | 退出 |
| 按 `Ctrl + Q` | 退出 |

### 命令行参数

```bash
# 直接通过参数传入项目路径
dotnet run -- "E:\\path\\to\\project"

# 也可先进入项目目录再运行
dotnet run --project CodeAnalysis.csproj -- "E:\\path\\to\\project"
```

## 项目结构

```
CodeAnalysis/
├── Program.cs                  # 入口：交互循环、.sln/.csproj 分组、汇总统计
├── CodeAnalysis.csproj         # 项目文件，声明依赖
├── appsettings.json            # 配置文件（输出路径、大文件/方法阈值）
├── Services/
│   ├── CodeAnalyzer.cs         # 核心分析服务：Roslyn 语法树解析、注释检测、统计
│   └── ExcelExporter.cs        # Excel 导出服务：EPPlus 报表生成与格式化
├── Models/
│   ├── SourceFileInfo.cs       # 类型/文件信息记录
│   ├── MethodInfo.cs           # 方法信息记录
│   └── ProjectExportData.cs    # 项目级导出数据聚合
└── README.md                   # 项目说明（本文件）
```

## 数据流

```
用户输入路径
    → Program.Main 循环接收
    → 递归查找 .csproj，检测 .sln 并按方案分组
    → 每个 .csproj 调用 CodeAnalyzer.AnalyzeProjectAsync
    → 同组 .csproj 结果合并为 ProjectExportData
    → ExcelExporter.Export 写入单个 Excel（含汇总页 + 多 sheet）
    → 控制台输出注释率统计与合同合规判断
    → 循环等待下一次输入
```

## Excel 输出结构

### 汇总页

| csproj | 文件数 | 类总数 | 代码行数 | 有注释类总数 | 类注释合格率 | 类注释是否通过 | 方法总数 | 有注释方法总数 | 方法注释合格率 | 方法注释是否通过 |

### file sheet

| 项目 | 文件名 | 文件路径 | 文件类型 | 类名/接口名 | 类注释 | 代码行数 |
|------|--------|----------|----------|-------------|--------|----------|

底部追加汇总行：`汇总: 总计 N，有注释 M，注释率 XX.X% — ✅ 达标 (≥80%)` 或 `❌ 未达标 (<80%)`

### method sheet

| 项目 | 文件名 | 类名 | 方法修饰符 | 方法名 | 方法注释 | 代码行数 | 调用次数 |
|------|--------|------|------------|--------|----------|----------|----------|

### 输出文件命名

```
{sln名}扫描结果-{yyyyMMdd_HHmmss}.xlsx
```

## 配置文件

项目根目录下的 `appsettings.json` 用于自定义输出行为：

```json
{
  "OutputPath": "E:\\codeup\\code.analysis\\output",
  "BigFileRows": 2000,
  "CreateBigFileSheet": false,
  "BigMethodRows": 300,
  "CreateBigMethodSheet": false
}
```

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `OutputPath` | string | `output/`（程序所在目录） | Excel 输出目录 |
| `BigFileRows` | int | `1000` | 文件代码行数超过此值时视为大文件 |
| `CreateBigFileSheet` | bool | `false` | 是否生成 BigFile 独立 sheet |
| `BigMethodRows` | int | `200` | 方法代码行数超过此值时视为大方法 |
| `CreateBigMethodSheet` | bool | `false` | 是否生成 BigMethod 独立 sheet |

> 配置项也可通过环境变量覆盖。

## 过滤规则

以下内容**不纳入统计**：

- 文件名以 `.Designer.cs` 结尾的文件
- 构造方法（方法名与所属类名一致）
- WinForms 自动生成事件方法：方法名以 `_Click`、`_SelectedValueChanged`、`_Load` 结尾

## 技术栈

| 组件 | 用途 |
|------|------|
| .NET 8 | 运行时框架 |
| Microsoft.CodeAnalysis.CSharp (Roslyn) | C# 语法树解析与注释检测 |
| EPPlus 7 | Excel 报表生成 |
| Microsoft.Extensions.Configuration | 配置文件读取 |

## 常见问题

**Q: 提示 "未找到任何 .csproj 文件"？**

确认传入的路径正确指向包含 `.csproj` 项目的目录，而非 `.sln` 文件所在目录。

**Q: 如何修改合规阈值？**

当前阈值硬编码为 80%。如需自定义，修改 `Program.cs` 和 `ExcelExporter.cs` 中的 `>= 80` 判断逻辑，或发起 PR 使其可配置。

**Q: 支持 .NET 6/7 项目吗？**

可以。工具仅读取 `.csproj` 文件路径并解析其中的 `.cs` 源文件，不依赖目标框架版本，因此兼容各版本的 .NET 项目。

**Q: 分析大量文件时速度如何？**

工具采用异步文件读取 + 单线程 Roslyn 解析，对于数百个文件的典型企业项目，分析 + 导出通常在数秒内完成。

## 贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -m 'feat: xxx'`)
4. 推送到分支 (`git push origin feature/xxx`)
5. 提交 Pull Request

## License

MIT License — 详见 [LICENSE](LICENSE) 文件。