XML注释怎么写才能被编译器识别
C# 编译器只认以
///开头的行，且必须紧贴在类型或成员声明上方（中间不能空行）。它不解析普通
//或
/* */注释。
常见错误是写了注释但没加第三个斜杠，或者在类定义和注释之间插了空白行——这两种情况都会导致
xml文件里对应项为空或完全缺失。
/// <summary>描述方法用途</summary>是必需的，缺了会警告 CS1591
<param name="x">中的
name必须和参数名完全一致（区分大小写）
<returns></returns>对非
void方法建议补全，否则生成文档时返回值栏为空 支持
<exception></exception>、
<remarks></remarks>、
<example></example>等标签，但只有
<summary></summary>和
<param>被大多数工具默认提取
如何让 MSBuild 输出 XML 文档文件
仅写注释没用，必须开启编译器的 XML 文档生成功能，否则
.xml文件根本不会产生。
在项目文件（
.csproj）中添加或确认以下配置项：
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
这是 .NET SDK 风格项目的推荐方式。旧式项目需手动设
<documentationfile>bin\Debug\MyApp.xml</documentationfile>，但路径容易出错。 生成的 XML 文件默认和程序集同名，放在输出目录（如
bin/Debug/net8.0/MyLib.xml） 若项目含多个 TargetFramework，每个框架都会生成独立的 XML 文件 未启用该选项时，即使写了完整注释，
dotnet build也不会输出任何 XML —— 这是新手最常卡住的点
用 DocFX 或 SharpDoc 生成 HTML API 文档
MSBuild 生成的 XML 是原始数据，要变成可浏览的网页，得靠外部工具。DocFX 是微软官方维护的主流选择；SharpDoc 更轻量，适合快速预览。
以 DocFX 为例，初始化后关键配置在
docfx.json的
metadata段落：
"metadata": [
{
"src": [{ "files": ["../MyLib.csproj"] }],
"dest": "api",
"properties": { "TargetFramework": "net8.0" }
}
]
确保 src.files指向的是
.csproj，不是 DLL 或 XML 文件——DocFX 会自己调用编译器读取 XML 如果项目依赖其他 NuGet 包，需在
properties中加
"RestoreSources"或提前运行
dotnet restore生成失败常见报错：
Unable to locate the metadata source，基本是路径写错或没生成 XML；
Could not load file or assembly多因 TargetFramework 不匹配
为什么 Visual Studio IntelliSense 不显示你的注释
即使 XML 文件已生成，IntelliSense 仍不提示，大概率是因为引用方式不对。
如果你的类库被另一个项目通过
<projectreference></projectreference>引用，那没问题：VS 自动找同目录下的
.xml文件。
但如果用的是
<packagereference></packagereference>引入 NuGet 包，则必须确保该包内包含
.xml文件，并打包进
lib/<tfm>/</tfm>目录下（例如
lib/net8.0/MyLib.xml）。 SDK 项目默认会把 XML 打进 NuGet，但需确认
<includesymbols>false</includesymbols>不影响它（符号包不影响文档） 手动打包时漏掉 XML，或用
nuget pack而非
dotnet pack，都可能导致消费者看不到注释 检查方法：解压
.nupkg文件，看里面有没有对应路径的 XML —— 这是最直接的验证手段
XML 注释本身简单，真正卡住人的永远是生成链路上某个环节没对齐：编译开关、项目引用方式、NuGet 打包结构、工具配置路径……每一步都得实打实验证输出是否存在，而不是“应该有”。
