曦寒开发框架文档

主题

XiHan.Framework.Analyzers ​

基于 Roslyn 的编译期规范分析器：检查 C# 源文件的曦寒标准版权文件头，并提供一键修复。

  • NuGet：XiHan.Framework.Analyzers
  • 模块类：—（作为 Analyzer 引用，编译期生效，无运行时模块类）
  • 所在层：工具 / 分析器
  • 关键依赖：Microsoft.CodeAnalysis.*（Roslyn，开发期依赖，PrivateAssets="all"）

概述 ​

XiHan.Framework.Analyzers 是一套基于 Roslyn 的代码分析器与代码修复器，在编译期扫描 C# 源码是否符合框架规范，并在 IDE 中给出诊断提示和 Code Fix 一键修复。当前落地的规则是文件头版权声明检查（XHFH001）。它以 netstandard2.0 构建（Roslyn 分析器约定的目标框架），标记为开发期依赖（DevelopmentDependency），并按 analyzer 约定打包到 analyzers/dotnet/cs——因此只在开发/构建阶段生效，不进入运行时、不给消费方带来运行时依赖。

何时使用 ​

  • 想在编码/编译阶段自动强制统一的文件头规范，把问题拦在提交与 CI 之前。
  • 希望 IDE 直接给出诊断提示，并提供自动修复而不必手工补写文件头。
  • 团队协作下保证所有 .cs 文件的版权/作者/GUID/创建时间声明一致。

安装与启用 ​

作为分析器引用，引用后编译期自动生效，无需 [DependsOn] 或任何运行时接入。

发布后可通过 NuGet 包接入：

bash
dotnet add package XiHan.Framework.Analyzers

开发期也可通过项目引用以 analyzer 形式接入（推荐显式声明为 analyzer，避免把它当普通程序集引用）：

xml
<ProjectReference Include="..\XiHan.Framework.Analyzers\XiHan.Framework.Analyzers.csproj"
                  OutputItemType="Analyzer"
                  ReferenceOutputAssembly="false"
                  PrivateAssets="all" />

启用后你得到：一个 DiagnosticAnalyzer（逐文件语法树扫描并产出诊断）与一个 CodeFixProvider（一键补写/替换文件头，支持 IDE 的 Fix All 批量修复）。

工作原理 ​

  • 分析器注册 SyntaxTree 级动作，逐个 C# 源文件检查，并启用并发执行；不分析生成代码（GeneratedCodeAnalysisFlags.None）。
  • 跳过规则：非 .cs 文件、bin/obj 目录下的文件、*.g.cs / *.generated.cs / *.designer.cs、以及文件开头含 <auto-generated 标记的文件都会被跳过。
  • 校验规则：文件必须以固定的两行版权与 MIT 授权声明开头；比对前会归一化行尾并剥离 BOM，再逐字符匹配。不满足即报 XHFH001。
  • 修复行为：Code Fix 会把文件顶部以 // Copyright 起始的连续注释行（含其后的一个空行）整体替换为标准两行文件头；若识别不到既有版权头，则直接在文件开头插入。

规则 ​

规则 ID标题类别默认级别说明
XHFH001缺少曦寒标准版权文件头XiHan.FileHeaderWarning（默认启用）C# 源文件必须以标准的两行版权与 MIT 授权声明开头；缺失或不合规即触发，消息为「文件 '{0}' 缺少或未正确声明曦寒标准版权文件头」。

目前源码中仅定义此一条规则（XiHanFileHeaderRule.cs）。

主要 API / 类型 ​

类型说明
XiHanFileHeaderAnalyzerpublic sealed，[DiagnosticAnalyzer(LanguageNames.CSharp)]，注册语法树动作产出 XHFH001 诊断
XiHanFileHeaderCodeFixProviderpublic sealed，[ExportCodeFixProvider] + [Shared]，提供「添加曦寒标准版权文件头」修复，GetFixAllProvider() 返回 BatchFixer 支持批量修复

XiHanFileHeaderRule（诊断描述符/ID/类别）与 XiHanFileHeader（文件头校验、解析、生成的内部工具）均为 internal，不属于对外 API。

配置 ​

分析器无 Options / 配置节。诊断级别通过 .editorconfig 的 dotnet_diagnostic.<ID>.severity 逐条调整，支持按目录/文件模式覆盖：

ini
# 默认作为警告
[*.cs]
dotnet_diagnostic.XHFH001.severity = warning

# 需要在 CI 阻断时改为 error
# dotnet_diagnostic.XHFH001.severity = error

# 对生成/迁移目录关闭
[**/Migrations/*.cs]
dotnet_diagnostic.XHFH001.severity = none

标准文件头格式 ​

XHFH001 校验并由 Code Fix 生成的文件头就是固定的两行，不含任何逐文件字段：

csharp
// Copyright (c) 2021-Present XiHanFun and contributors.
// Licensed under the MIT License. See LICENSE in the project root for license information.

扩展点 / 自定义 ​

  • 增加新规则：新增一个 DiagnosticAnalyzer（及可选 CodeFixProvider），沿用 XiHanFileHeaderRule 的模式定义唯一 DiagnosticId 与 DiagnosticDescriptor。因项目启用了 EnforceExtendedAnalyzerRules，需遵循分析器编写的扩展规则（如 SupportedDiagnostics 使用不可变数组、避免在分析器中做 I/O 等）。
  • 消费方无需扩展即可用；调级别/排除目录一律通过 .editorconfig，不改分析器源码。

注意事项与最佳实践 ​

  • 只针对 C# 源文件；bin/obj、生成文件（*.g.cs / *.generated.cs / *.designer.cs、含 <auto-generated 标记）会被自动跳过。
  • 校验是严格匹配：两行内容完全固定，不含 FileName / Guid / CreateTime 等逐文件字段；比对前会归一化行尾并剥离 BOM，因此跨平台换行与 BOM 不影响判定。
  • 项目以 netstandard2.0 构建、IncludeBuildOutput=false + SuppressDependenciesWhenPacking=true 打包为 analyzer，Roslyn 相关 PackageReference 全部 PrivateAssets="all"，不会外泄给引用方，也不进入运行时。
  • 引用它是开发期能力；要在 CI 阻断构建，请把 XHFH001 的严重级别调为 error。

依赖模块 ​

无框架内部依赖。开发期依赖（均 PrivateAssets="all"，不外泄给消费方）：

  • Microsoft.CodeAnalysis.Analyzers
  • Microsoft.CodeAnalysis.CSharp.Workspaces
  • System.Composition.AttributedModel

相关模块 ​

Released under The MIT License

Copyright ©2021-Present XiHanFun and contributors.