代码分析工具 - netcorepal-cloud-framework (original) (raw)
代码分析工具¶
NetCorePal.Extensions.CodeAnalysis.Tools 是基于 NetCorePal 代码分析框架的命令行工具，用于从 .NET 项目生成交互式架构可视化 HTML 文件（基于 .NET 10 单文件执行）。
⚠️ 重要说明¶
工具生效的前提条件：目标分析的项目/程序集必须引用 NetCorePal.Extensions.CodeAnalysis 包。该包包含了源生成器，能够在编译时自动生成代码分析所需的元数据。
<PackageReference Include="NetCorePal.Extensions.CodeAnalysis" />
没有引用此包的项目将无法生成分析结果。
安装¶
作为全局 dotnet 工具安装：
dotnet tool install -g NetCorePal.Extensions.CodeAnalysis.Tools
或在项目中本地安装：
dotnet tool install NetCorePal.Extensions.CodeAnalysis.Tools
使用方法¶
命令概览¶
工具提供两个主要命令：
| 命令 | 说明 |
|---|---|
| generate | 分析项目/解决方案并生成交互式 HTML 可视化 |
| snapshot | 管理架构快照以追踪演进历史 |
快速参考：
`# 生成架构可视化 netcorepal-codeanalysis generate [选项]
创建架构快照
netcorepal-codeanalysis snapshot add [选项] `
快速上手¶
`# 进入项目目录 cd MyApp
自动发现并分析当前目录下的解决方案或项目
netcorepal-codeanalysis generate
指定解决方案文件（.sln/.slnx）
netcorepal-codeanalysis generate --solution MySolution.sln
指定项目文件（可多次指定）
netcorepal-codeanalysis generate --project MyProject.csproj
自定义输出文件和标题
netcorepal-codeanalysis generate --output my-architecture.html --title "我的架构图"
启用详细输出
netcorepal-codeanalysis generate --verbose `
命令参数¶
| 选项 | 别名 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| --solution | -s | 文件路径 | 无 | 要分析的解决方案文件，支持 .sln/.slnx |
| --project | -p | 文件路径（可多次） | 无 | 要分析的项目文件（.csproj），可重复指定多个 |
| --output | -o | 文件路径 | architecture-visualization.html | 输出的 HTML 文件路径 |
| --format | -f | 字符串 | html | 输出格式：html 或 markdown（也可使用 md） |
| --title </td> <td>-t</td> <td>字符串</td> <td>架构可视化</td> <td>生成页面/文档的标题</td> </tr> <tr> <td>--verbose</td> <td>-v</td> <td>开关</td> <td>false</td> <td>启用详细日志输出</td> </tr> <tr> <td>--include-tests</td> <td>无</td> <td>开关</td> <td>false</td> <td>包含测试项目（默认不包含；规则见下文“测试项目识别规则”）</td> </tr> </tbody></table> <h4 id="generate-命令¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#generate-命令¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a><code>generate</code> 命令<a href="#generate" title="Permanent link">¶</a></h4><p><strong>输入源选项（按优先级排序）：</strong></p> <ul> <li><code>--assembly, -a</code>：指定程序集文件 (.dll)。可多次指定</li> <li><code>--project, -p</code>：指定项目文件 (.csproj)。可多次指定</li> <li><code>--solution, -s</code>：指定解决方案文件 (.sln)。可多次指定</li> </ul> <p><strong>构建选项：</strong></p> <ul> <li><code>--configuration, -c</code>：构建配置 (Debug/Release)。默认：Debug</li> </ul> <p><strong>输出选项：</strong></p> <ul> <li><code>--output, -o</code>：输出 HTML 文件路径。默认：code-analysis.html</li> <li><code>--title, -t</code>：HTML 页面标题。默认：Architecture Visualization</li> <li><code>--verbose, -v</code>：启用详细输出用于调试</li> </ul> <h3 id="使用示例¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#使用示例¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>使用示例<a href="#%5F8" title="Permanent link">¶</a></h3><ol> <li><strong>自动发现分析：</strong></li> </ol> <p>`# 进入项目目录 cd MyApp</p> <h1 id="自动发现并分析当前目录下的解决方案项目程序集"><a class="anchor" aria-hidden="true" tabindex="-1" href="#自动发现并分析当前目录下的解决方案项目程序集"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>自动发现并分析当前目录下的解决方案/项目/程序集</h1><p>netcorepal-codeanalysis generate</p> <h1 id="自动发现并指定输出文件"><a class="anchor" aria-hidden="true" tabindex="-1" href="#自动发现并指定输出文件"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>自动发现并指定输出文件</h1><p>netcorepal-codeanalysis generate -o my-architecture.html `</p> <ol> <li><strong>分析特定解决方案：</strong></li> </ol> <p><code>cd MyApp netcorepal-codeanalysis generate \ --solution MyApp.sln \ --output architecture.html \ --title "我的应用架构" </code></p> <ol> <li><strong>分析多个项目：</strong></li> </ol> <p><code>cd MyApp netcorepal-codeanalysis generate \ -p MyApp/MyApp.csproj \ -p MyApp.Domain/MyApp.Domain.csproj \ -o docs/architecture.html </code></p> <h2 id="输出格式¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#输出格式¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>输出格式<a href="#%5F9" title="Permanent link">¶</a></h2><p>工具支持两种输出格式：</p> <h3 id="html-格式（默认）¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#html-格式（默认）¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>HTML 格式（默认）<a href="#html" title="Permanent link">¶</a></h3><p>生成交互式 HTML 可视化页面，包含完整的导航、图表切换和在线编辑功能。</p> <p>`# 生成 HTML 格式（默认） netcorepal-codeanalysis generate</p> <h1 id="显式指定-html-格式"><a class="anchor" aria-hidden="true" tabindex="-1" href="#显式指定-html-格式"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>显式指定 HTML 格式</h1><p>netcorepal-codeanalysis generate --format html `</p> <h3 id="markdown-格式¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#markdown-格式¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>Markdown 格式<a href="#markdown" title="Permanent link">¶</a></h3><p>生成 Markdown 文档，便于大语言模型理解业务模型，包含： - 概览统计（节点和关系计数） - 架构元素列表（按类型分组） - 组件关系详情 - 嵌入式 Mermaid 图表（架构总览图、处理流程图、聚合关系图） - 版本历史趋势（如果启用历史记录）</p> <p>`# 生成 Markdown 格式 netcorepal-codeanalysis generate --format markdown</p> <h1 id="或使用简写"><a class="anchor" aria-hidden="true" tabindex="-1" href="#或使用简写"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>或使用简写</h1><p>netcorepal-codeanalysis generate --format md</p> <h1 id="自定义输出文件名"><a class="anchor" aria-hidden="true" tabindex="-1" href="#自定义输出文件名"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>自定义输出文件名</h1><p>netcorepal-codeanalysis generate --format markdown --output architecture.md</p> <h1 id="自定义标题"><a class="anchor" aria-hidden="true" tabindex="-1" href="#自定义标题"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>自定义标题</h1><p>netcorepal-codeanalysis generate --format md --title "订单系统架构分析" `</p> <p><strong>注意</strong>：当使用默认输出文件名时，Markdown 格式会自动将文件扩展名改为 <code>.md</code>。</p> <h2 id="自动发现机制¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#自动发现机制¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>自动发现机制<a href="#%5F10" title="Permanent link">¶</a></h2><p>当未提供 <code>--solution</code> 与 <code>--project</code> 时，工具会在“当前目录（顶层）”自动发现分析目标：</p> <ul> <li>优先级：<code>.slnx</code> > <code>.sln</code> > 顶层 <code>*.csproj</code></li> <li>非递归扫描目录：仅加载当前目录顶层的解决方案/项目文件，随后递归分析其依赖项目</li> <li>默认排除测试项目：除非显式传入 <code>--include-tests</code></li> <li>输出可见性：</li> <li>选择 <code>.slnx/.sln</code> 会打印 <code>Using solution (...): <文件名></code>；随后打印“Projects to analyze (N)”并列出递归依赖在内的完整项目清单</li> <li>选择顶层 <code>*.csproj</code> 会直接打印“Projects to analyze (N)”并列出包含递归依赖的完整清单</li> </ul> <blockquote> <p>说明：工具会在隔离的临时工作目录中生成并执行动态 <code>app.cs</code>，并使用 <code>--no-launch-profile</code> 运行以避免继承当前目录的 <code>launchSettings.json</code>/<code>global.json</code> 等环境影响。</p> </blockquote> <h3 id="测试项目识别规则¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#测试项目识别规则¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>测试项目识别规则<a href="#%5F11" title="Permanent link">¶</a></h3><ul> <li>默认行为：测试项目会被排除在分析之外（除非显式传入 <code>--include-tests</code>）</li> <li>判定规则（满足任一即视为测试项目）：</li> <li>项目文件所在路径的任一父级目录名为 <code>test</code> 或 <code>tests</code>（不区分大小写）</li> <li>项目文件（.csproj）中包含 <code><IsTestProject>true</IsTestProject></code>（大小写与空白不敏感）</li> </ul> <h2 id="系统要求¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#系统要求¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>系统要求<a href="#%5F12" title="Permanent link">¶</a></h2><ul> <li>运行环境：.NET 10 SDK（单文件执行依赖 .NET 10 特性）</li> <li>被分析项目的目标框架：支持 <code>net8.0</code>、<code>net9.0</code> 和 <code>net10.0</code></li> <li>被分析项目必须引用 <code>NetCorePal.Extensions.CodeAnalysis</code> 包（包含源生成器）</li> </ul> <h2 id="输出内容¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#输出内容¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>输出内容<a href="#%5F13" title="Permanent link">¶</a></h2><p>工具生成包含以下内容的交互式 HTML 文件：</p> <ul> <li><strong>统计信息</strong>：各类型组件的数量统计和分布情况</li> <li><strong>架构总览图</strong>：系统中所有类型及其关系的完整视图</li> <li><strong>处理流程图集合</strong>：每个独立业务链路的流程图（如命令处理链路）</li> <li><strong>聚合关系图集合</strong>：每个聚合根相关的关系图</li> <li><strong>交互式导航</strong>：左侧树形菜单，支持图表类型切换</li> <li><strong>Mermaid Live 集成</strong>：每个图表右上角的"View in Mermaid Live"按钮</li> <li><strong>📊 版本历史功能</strong>（如果存在快照）：</li> <li><strong>版本选择器</strong>：交互式下拉框切换不同快照版本</li> <li><strong>历史趋势图表</strong>（2个或更多快照）： <ul> <li>总体趋势图（总元素和总关系数量） </li> <li>元素类型趋势图（各类型元素数量变化） </li> <li>关系类型趋势图（各类型关系数量变化）</li> </ul> </li> <li><strong>交互式图例</strong>：点击显示/隐藏特定指标</li> <li><strong>Chart.js 可视化</strong>：专业的响应式图表</li> <li><strong>过滤一致性</strong>：趋势图与统计信息使用相同的过滤规则</li> </ul> <h2 id="与构建过程集成¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#与构建过程集成¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>与构建过程集成<a href="#%5F14" title="Permanent link">¶</a></h2><h3 id="msbuild-集成¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#msbuild-集成¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>MSBuild 集成<a href="#msbuild" title="Permanent link">¶</a></h3><p>添加到 <code>.csproj</code> 文件：</p> <p><code><Target Name="GenerateArchitectureVisualization" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'"> <Exec Command="netcorepal-codeanalysis generate --project <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo stretchy="false">(</mo><mi>M</mi><mi>S</mi><mi>B</mi><mi>u</mi><mi>i</mi><mi>l</mi><mi>d</mi><mi>P</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi><mi>F</mi><mi>u</mi><mi>l</mi><mi>l</mi><mi>P</mi><mi>a</mi><mi>t</mi><mi>h</mi><mo stretchy="false">)</mo><mo>−</mo><mo>−</mo><mi>o</mi><mi>u</mi><mi>t</mi><mi>p</mi><mi>u</mi><mi>t</mi></mrow><annotation encoding="application/x-tex">(MSBuildProjectFullPath) --output </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mopen">(</span><span class="mord mathnormal" style="margin-right:0.05017em;">MSB</span><span class="mord mathnormal">u</span><span class="mord mathnormal">i</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">d</span><span class="mord mathnormal" style="margin-right:0.13889em;">P</span><span class="mord mathnormal">ro</span><span class="mord mathnormal" style="margin-right:0.05724em;">j</span><span class="mord mathnormal">ec</span><span class="mord mathnormal" style="margin-right:0.13889em;">tF</span><span class="mord mathnormal">u</span><span class="mord mathnormal" style="margin-right:0.13889em;">llP</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">h</span><span class="mclose">)</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.8095em;vertical-align:-0.1944em;"></span><span class="mord">−</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">tp</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span></span></span></span>(OutputPath)architecture-visualization.html" ContinueOnError="true" /> </Target> </code></p> <h3 id="github-actions¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#github-actions¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>GitHub Actions<a href="#github-actions" title="Permanent link">¶</a></h3><p>添加到工作流程：</p> <p><code>- name: Generate Architecture Visualization run: | dotnet tool install -g NetCorePal.Extensions.CodeAnalysis.Tools cd MyApp netcorepal-codeanalysis generate \ --output docs/architecture-visualization.html \ --title "MyApp 架构图" </code></p> <h2 id="故障排除¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#故障排除¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>故障排除<a href="#%5F15" title="Permanent link">¶</a></h2><h3 id="常见问题¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#常见问题¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>常见问题<a href="#%5F16" title="Permanent link">¶</a></h3><ol> <li><strong>找不到项目/解决方案</strong>：确保路径正确且文件存在</li> <li><strong>无分析结果</strong>：确保项目引用了 <code>NetCorePal.Extensions.CodeAnalysis</code> 包并能正常编译</li> <li><strong>权限错误</strong>：检查输出目录的写入权限</li> <li><strong>构建失败</strong>：确保项目可以正常构建，检查依赖项</li> </ol> <h3 id="详细输出¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#详细输出¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>详细输出<a href="#%5F17" title="Permanent link">¶</a></h3><p>使用 <code>--verbose</code> 标志获取分析过程的详细信息：</p> <p><code>netcorepal-codeanalysis generate --verbose </code></p> <p>这将显示：</p> <ul> <li>发现的文件和项目</li> <li>递归依赖收集信息</li> <li>单文件执行过程日志</li> <li>分析统计信息</li> <li>文件生成详情</li> <li>发生问题时的错误详情</li> </ul> <h2 id="相关包¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#相关包¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>相关包<a href="#%5F18" title="Permanent link">¶</a></h2><ul> <li><a href="../code-flow-analysis.md" title="null" rel="noopener noreferrer">NetCorePal.Extensions.CodeAnalysis</a>：核心分析框架</li> <li>源生成器：用于自动分析的源生成器</li> </ul> <h2 id="历史记录特性（类似-ef-core-迁移）¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#历史记录特性（类似-ef-core-迁移）¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>历史记录特性（类似 EF Core 迁移）<a href="#ef-core" title="Permanent link">¶</a></h2><p>工具提供了版本快照功能，可以追踪架构的演进历史，类似于 Entity Framework Core 的迁移机制。</p> <p><strong>快照以C#代码文件形式保存</strong>，类似EF Core的迁移快照，便于版本控制和代码审查。</p> <h3 id="创建快照¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#创建快照¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>创建快照<a href="#%5F19" title="Permanent link">¶</a></h3><p>`# 在当前目录创建项目架构快照（自动发现项目） netcorepal-codeanalysis snapshot add --description "初始版本"</p> <h1 id="指定项目文件创建快照"><a class="anchor" aria-hidden="true" tabindex="-1" href="#指定项目文件创建快照"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>指定项目文件创建快照</h1><p>netcorepal-codeanalysis snapshot add --project MyProject.csproj --description "添加订单模块"</p> <h1 id="指定快照名称（ef-core-风格）"><a class="anchor" aria-hidden="true" tabindex="-1" href="#指定快照名称（ef-core-风格）"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>指定快照名称（EF Core 风格）</h1><p>netcorepal-codeanalysis snapshot add --project MyProject.csproj --name "AddedPaymentFeature" --description "添加支付功能" `</p> <p><strong>快照文件命名规则</strong>： - 格式：<code>Snapshot_{Version}_{Name}.cs</code>- Version：时间戳格式 <code>YYYYMMDDHHmmss</code>- Name：可选，从 <code>--name</code> 或 <code>--description</code> 派生（sanitized为有效标识符） - 示例：<code>Snapshot_20260116120000_AddedOrderModule.cs</code></p> <p><strong>生成的快照类</strong>：</p> <p>`// <auto-generated /> // Snapshot created: 2026-01-16 12:00:00 // Description: 添加订单模块</p> <p>using NetCorePal.Extensions.CodeAnalysis.Snapshots; using NetCorePal.Extensions.CodeAnalysis.Attributes;</p> <p>namespace CodeAnalysisSnapshots { public partial class Snapshot_20260116120000_AddedOrderModule : CodeFlowAnalysisSnapshot { public Snapshot_20260116120000_AddedOrderModule() { Metadata = new SnapshotMetadata { Version = "20260116120000", Timestamp = "2026-01-16 12:00:00", Description = "添加订单模块", // ... };</p> <pre><code class="notranslate"> MetadataAttributes = new MetadataAttribute[] { new EntityMetadataAttribute("MyApp.Domain.Order", true, new string[] { "OrderItem" }, new string[] { "Create" }), // ... 所有其他元数据 }; } }</code></pre><p>} `</p> <h3 id="生成带历史记录的html¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#生成带历史记录的html¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>生成带历史记录的HTML<a href="#html%5F1" title="Permanent link">¶</a></h3><p>`# 默认生成包含历史快照的交互式HTML（自动通过反射发现快照） netcorepal-codeanalysis generate</p> <h1 id="禁用历史记录功能"><a class="anchor" aria-hidden="true" tabindex="-1" href="#禁用历史记录功能"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>禁用历史记录功能</h1><p>netcorepal-codeanalysis generate --no-history `</p> <p><strong>快照发现机制</strong>（反射based）： - ✅ 自动从项目程序集中发现所有快照类（继承自 <code>CodeFlowAnalysisSnapshot</code>） - ✅ 只有代码变化时才会添加新快照（基于 hash 比较） - ✅ 快照按版本自动排序（最新的在前） - ✅ 无需手动指定快照目录</p> <p><strong>生成的HTML功能</strong>：</p> <ol> <li><strong>版本选择器</strong>（多个快照时显示）</li> <li>交互式下拉框，显示快照描述和时间戳</li> <li>切换版本时自动刷新所有图表和统计</li> <li>专业深色主题样式</li> <li><strong>历史趋势图表</strong>（2个或更多快照时显示）</li> <li><strong>总体趋势图</strong>：总元素和总关系数量随时间变化</li> <li><strong>元素类型趋势图</strong>：Aggregate、Command、DomainEvent等各类型数量变化</li> <li><strong>关系类型趋势图</strong>：CommandToHandler、AggregateToDomainEvent等关系变化</li> <li><strong>交互式图例</strong>：点击图例项显示/隐藏对应指标</li> <li><strong>响应式图表</strong>：基于 Chart.js，支持缩放和详细提示</li> <li><strong>时间轴顺序</strong>：X轴从左到右按时间顺序排列（最早→最新）</li> <li><strong>过滤一致性</strong>：使用与统计信息页面相同的过滤规则</li> <li><strong>版本间同步</strong></li> <li>所有视图（统计、架构图、流程图）在不同快照间自动同步</li> <li>保持一致的用户体验</li> </ol> <h3 id="典型工作流程¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#典型工作流程¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>典型工作流程<a href="#%5F20" title="Permanent link">¶</a></h3><p>`# 1. 初始架构快照 netcorepal-codeanalysis snapshot add --project MyProject.csproj --description "项目初始版本"</p> <h1 id="2-开发新功能"><a class="anchor" aria-hidden="true" tabindex="-1" href="#2-开发新功能"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>2. 开发新功能...</h1><h1 id="3-创建新快照"><a class="anchor" aria-hidden="true" tabindex="-1" href="#3-创建新快照"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>3. 创建新快照</h1><p>netcorepal-codeanalysis snapshot add --project MyProject.csproj --description "添加支付功能"</p> <h1 id="4-生成可视化html（默认包含历史，通过反射自动发现所有快照）"><a class="anchor" aria-hidden="true" tabindex="-1" href="#4-生成可视化html（默认包含历史，通过反射自动发现所有快照）"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>4. 生成可视化HTML（默认包含历史，通过反射自动发现所有快照）</h1><p>netcorepal-codeanalysis generate --project MyProject.csproj --output architecture.html</p> <h1 id="5-打开生成的html文件查看："><a class="anchor" aria-hidden="true" tabindex="-1" href="#5-打开生成的html文件查看："><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>5. 打开生成的HTML文件查看：</h1><h1 id="--版本选择器下拉框（切换不同快照）"><a class="anchor" aria-hidden="true" tabindex="-1" href="#--版本选择器下拉框（切换不同快照）"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>- 版本选择器下拉框（切换不同快照）</h1><h1 id="--历史趋势图表（2个或更多快照时显示）"><a class="anchor" aria-hidden="true" tabindex="-1" href="#--历史趋势图表（2个或更多快照时显示）"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>- 历史趋势图表（2个或更多快照时显示）</h1><h1 id="--完整的架构分析和统计信息"><a class="anchor" aria-hidden="true" tabindex="-1" href="#--完整的架构分析和统计信息"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>- 完整的架构分析和统计信息</h1><h1 id="6-提交快照到版本控制（推荐）"><a class="anchor" aria-hidden="true" tabindex="-1" href="#6-提交快照到版本控制（推荐）"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>6. 提交快照到版本控制（推荐）</h1><p>git add Snapshots/ git commit -m "Add architecture snapshot: 添加支付功能" `</p> <h3 id="版本控制集成¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#版本控制集成¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>版本控制集成<a href="#%5F21" title="Permanent link">¶</a></h3><p>快照以 C# 代码文件形式保存，建议将其提交到版本控制系统：</p> <p><code># 将快照目录添加到版本控制 git add Snapshots/ git commit -m "Add architecture snapshot: [描述]" </code></p> <p><strong>优势</strong>： - ✅ 类型安全，编译时检查 - ✅ 易于代码审查和diff - ✅ 自然集成到Git工作流 - ✅ 遵循EF Core迁移的最佳实践 - ✅ 支持多人协作（合并冲突可见且易于解决）</p> <h3 id="快照命令参考¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#快照命令参考¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>快照命令参考<a href="#%5F22" title="Permanent link">¶</a></h3><h4 id="主要命令¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#主要命令¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>主要命令<a href="#%5F23" title="Permanent link">¶</a></h4><table> <thead> <tr> <th>命令</th> <th>说明</th> </tr> </thead> <tbody><tr> <td>netcorepal-codeanalysis snapshot</td> <td>管理分析快照（类似 EF Core 迁移）</td> </tr> <tr> <td>netcorepal-codeanalysis snapshot add</td> <td>创建当前分析的新快照</td> </tr> </tbody></table> <h4 id="snapshot-add-命令参数¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#snapshot-add-命令参数¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a><code>snapshot add</code> 命令参数<a href="#snapshot-add" title="Permanent link">¶</a></h4><table> <thead> <tr> <th>选项</th> <th>别名</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody><tr> <td>--project <project></td> <td>-p</td> <td>文件路径</td> <td>自动发现</td> <td>要分析的项目文件（.csproj）</td> </tr> <tr> <td>--name <name></td> <td>-n</td> <td>字符串</td> <td>无</td> <td>快照名称（可选，用于文件名，建议使用英文标识符，如：InitialCreate）</td> </tr> <tr> <td>--description <description></td> <td>-d</td> <td>字符串</td> <td>"Snapshot created"</td> <td>快照描述（可使用中文）</td> </tr> <tr> <td>--snapshot-dir <dir></td> <td>—</td> <td>目录路径</td> <td>Snapshots</td> <td>快照存储目录</td> </tr> <tr> <td>--verbose</td> <td>-v</td> <td>开关</td> <td>false</td> <td>启用详细输出</td> </tr> <tr> <td>--include-tests</td> <td>—</td> <td>开关</td> <td>false</td> <td>包含测试项目</td> </tr> </tbody></table> <p><strong>命令用法</strong>：</p> <p>`# 创建带描述的快照 netcorepal-codeanalysis snapshot add --description "初始版本"</p> <h1 id="为特定项目创建快照"><a class="anchor" aria-hidden="true" tabindex="-1" href="#为特定项目创建快照"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>为特定项目创建快照</h1><p>netcorepal-codeanalysis snapshot add --project MyProject.csproj --description "添加订单模块"</p> <h1 id="创建带自定义名称和目录的快照"><a class="anchor" aria-hidden="true" tabindex="-1" href="#创建带自定义名称和目录的快照"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>创建带自定义名称和目录的快照</h1><p>netcorepal-codeanalysis snapshot add <br> --project MyProject.csproj <br> --name "AddedPaymentFeature" <br> --description "添加支付功能" <br> --snapshot-dir ./MySnapshots `</p> <p><strong>注意</strong>： - <code>snapshot add</code> 仅支持单个项目文件（不支持解决方案） - 如果当前目录只有一个 <code>.csproj</code> 文件，可以省略 <code>--project</code>- 快照文件保存在项目目录中（相对路径相对于项目目录解析） - 快照以 C# 代码文件形式保存 - <code>--name</code> 参数建议使用英文标识符，<code>--description</code> 可使用中文描述</p> <h3 id="查看快照历史¶"><a class="anchor" aria-hidden="true" tabindex="-1" href="#查看快照历史¶"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a>查看快照历史<a href="#%5F24" title="Permanent link">¶</a></h3><p>快照历史无需通过CLI命令查看，而是通过生成的HTML可视化文件查看：</p> <p><code># 生成包含所有快照历史的HTML netcorepal-codeanalysis generate --project MyProject.csproj --output architecture.html </code></p> <p>生成的HTML文件提供了更好的快照查看体验： - <strong>版本选择器下拉框</strong>：交互式切换不同快照版本 - <strong>历史趋势图表</strong>：可视化展示架构演进（2个或更多快照时显示） - 总体趋势图（元素和关系数量变化） - 元素类型趋势图（各类型元素数量变化） - 关系类型趋势图（各类型关系数量变化） - <strong>交互式图例</strong>：点击显示/隐藏特定指标 - <strong>完整统计信息</strong>：每个快照的详细元数据和统计数据</p> <p><strong>快照自动发现</strong>： - 工具通过反射自动从项目程序集中发现所有快照类 - 无需手动指定快照目录或版本号 - 只有代码实际变化（hash不同）时才会创建新快照</p> |