Code Analysis Tools

NetCorePal.Extensions.CodeAnalysis.Tools is a command-line tool based on the NetCorePal code analysis framework, used to generate interactive architecture visualization HTML files from .NET projects (powered by .NET 10 single-file execution).

⚠️ Important Notice

Prerequisites for the tool to work: The target project to be analyzed must reference the NetCorePal.Extensions.CodeAnalysis package. This package contains source generators that automatically generate metadata required for code analysis during compilation.

<PackageReference Include="NetCorePal.Extensions.CodeAnalysis" />

Projects without this package reference will not be able to generate analysis results.

Installation

Install as a global dotnet tool:

dotnet tool install -g NetCorePal.Extensions.CodeAnalysis.Tools

Or install locally in a project:

dotnet tool install NetCorePal.Extensions.CodeAnalysis.Tools

Usage

Quick Start

# Enter project directory
cd MyApp

# Auto-discover and analyze solution or projects in current directory
netcorepal-codeanalysis generate

# Specify solution (.sln/.slnx)
netcorepal-codeanalysis generate --solution MySolution.sln

# Specify project(s)
netcorepal-codeanalysis generate --project MyProject.csproj

# Customize output and title
netcorepal-codeanalysis generate --output my-architecture.html --title "My Architecture"

# Enable verbose logs
netcorepal-codeanalysis generate --verbose

Command Parameters

Option	Alias	Type	Default	Description
--solution <solution>	-s	File path	N/A	Solution file to analyze, .sln/.slnx
--project <project>	-p	File path (repeatable)	N/A	Project file(s) to analyze (.csproj)
--output <output>	-o	File path	architecture-visualization.html	Output HTML file path
--title <title>	-t	String	架构可视化	HTML page title
--verbose	-v	Switch	false	Enable verbose output
--include-tests	—	Switch	false	Include test projects (see rules below)

generate Command

Use generate to analyze a solution or one or more projects and produce an interactive HTML report. Inputs can be provided by auto-discovery (top-level .slnx/.sln/*.csproj) or explicitly via --solution/--project. Options: see the parameter table above.

Usage Examples

1. Auto-discovery analysis:

# Enter project directory
cd MyApp

# Auto-discover solution or projects in current directory
netcorepal-codeanalysis generate

# Auto-discover and specify output file
netcorepal-codeanalysis generate -o my-architecture.html

1. Analyze specific solution:

cd MyApp
netcorepal-codeanalysis generate \
   --solution MyApp.sln \
   --output architecture-visualization.html \
   --title "My Application Architecture"

1. Analyze multiple projects:

cd MyApp
netcorepal-codeanalysis generate \
   -p MyApp/MyApp.csproj \
   -p MyApp.Domain/MyApp.Domain.csproj \
   -o docs/architecture-visualization.html

Auto-Discovery Mechanism

When --solution and --project are not provided, the tool auto-discovers targets in the current directory (top-level only):

• Priority: .slnx > .sln > top-level *.csproj
• Non-recursive scan: only load top-level solution/project files in the current directory, then recursively analyze their dependent projects
• Test projects are excluded by default (unless --include-tests is set)
• Visibility:
• For .slnx/.sln, prints Using solution (...): <file> then prints Projects to analyze (N) listing the complete set including recursive dependencies
• For top-level *.csproj, directly prints Projects to analyze (N) listing the complete set including recursive dependencies

Note: The tool generates and executes a dynamic app.cs in an isolated temporary work directory, and runs with --no-launch-profile to avoid inheriting launchSettings.json/global.json from the current directory.

Test Project Detection Rules

• Default: test projects are excluded unless --include-tests is specified
• A project is considered a test project if any of the following is true:
• Any ancestor directory name is test or tests (case-insensitive)
• The .csproj contains <IsTestProject>true</IsTestProject> (case/whitespace-insensitive)

System Requirements

• Runtime: .NET 10 SDK (single-file execution relies on .NET 10)
• Target frameworks supported for analyzed projects: net8.0, net9.0, net10.0
• Projects must reference the NetCorePal.Extensions.CodeAnalysis package (includes source generators)

Output Content

The tool generates interactive HTML files containing:

• Statistics Information: Quantity statistics and distribution of various component types
• Architecture Overview Diagram: Complete view of all types and their relationships in the system
• Processing Flow Chart Collection: Flow charts for each independent business chain (such as command processing chains)
• Aggregate Relation Diagram Collection: Relationship diagrams for each aggregate root
• Interactive Navigation: Left sidebar tree menu supporting chart type switching
• Mermaid Live Integration: "View in Mermaid Live" button in the upper right corner of each chart

Build Process Integration

MSBuild Integration

Add to .csproj file:

<Target Name="GenerateArchitectureVisualization" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
   <Exec Command="netcorepal-codeanalysis generate --project $(MSBuildProjectFullPath) --output $(OutputPath)architecture-visualization.html" 
            ContinueOnError="true" />
</Target>

GitHub Actions

Add to workflow:

- 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 Architecture"

Troubleshooting

Common Issues

1. No projects discovered: Ensure the current directory contains a .slnx, .sln, or top-level *.csproj, or pass --solution/--project explicitly
2. No analysis results: Ensure analyzed projects reference NetCorePal.Extensions.CodeAnalysis
3. Build failures: Ensure projects build successfully and dependencies restore correctly
4. Permission errors: Verify write permission for the output directory

Verbose Output

Use the --verbose flag to get detailed information about the analysis process:

netcorepal-codeanalysis generate --verbose

This will display:

• Discovery details and chosen input (solution/projects)
• Project filtering (tests excluded unless --include-tests)
• Full recursive dependency list (Projects to analyze)
• Temporary work directory and single-file execution details
• Analysis statistics and output file path
• Error details when issues occur

Related Packages

• NetCorePal.Extensions.CodeAnalysis: Core analysis framework
• Source Generators: Used for automatic analysis