ASP.NET Core发布时缺失APIService.xml，如何配置使其被包含？

我之前帮朋友排查过几乎一模一样的问题，咱们一步步来定位和解决：

1. 优先检查项目文件（.csproj）的配置 #

这是最核心的环节，.NET SDK风格的项目默认不会自动将根目录下的自定义XML文件包含到输出目录。你需要手动在项目文件里添加配置，确保文件被复制到发布目录：

打开你的.csproj文件，添加以下代码块：

<ItemGroup>
  <!-- 确保APIService.xml被复制到输出目录 -->
  <None Include="APIService.xml">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

• PreserveNewest表示只有当源文件比输出目录里的文件新时才复制，节省发布时间；如果需要每次都强制复制，可以改成Always。

2. 检查发布配置文件（.pubxml） #

如果你使用了自定义的发布配置（比如在Properties/PublishProfiles下的.pubxml文件），要确保里面没有排除这个XML文件：

• 打开对应的.pubxml，检查是否存在<ExcludeFilesFromDeployment>节点，如果里面包含APIService.xml，直接删除这一行；
• 如果需要显式指定包含，也可以添加：

<ItemGroup>
  <IncludeFilesForDeployment Include="APIService.xml" />
</ItemGroup>

3. 验证Swagger的XML文件路径配置 #

既然你集成了Swagger，要确保代码里指定的XML文件名和路径是正确的。在Program.cs或Startup.cs的Swagger配置代码里，检查是否正确指向了APIService.xml：

services.AddSwaggerGen(c =>
{
    // 注意这里的文件名要和你的XML文件完全一致
    var xmlFileName = "APIService.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlPath);
});

如果之前代码里用的是程序集名称生成的文件名（比如$"{Assembly.GetExecutingAssembly().GetName().Name}.xml"），但你的XML文件名是自定义的APIService.xml，就会导致路径不匹配，需要改成固定的文件名。

4. 本地发布验证 #

修改完配置后，先做本地发布测试，确认文件是否被包含：

• 右键项目 → 选择「发布」；
• 选择「文件夹」作为发布目标，指定一个本地目录；
• 发布完成后，打开目标目录，检查是否存在APIService.xml。如果本地发布能看到文件，再推送到Azure CI/CD管道。

5. Azure DevOps CI/CD管道检查 #

虽然你本地发布也有问题，但还是要确认管道配置没有额外的排除规则：

• 检查DotNetCoreCLI任务的publish命令，有没有添加--exclude-files参数排除了XML文件；
• 检查AzureRmWebAppDeployment（或新的AzureWebApp）任务，确保没有在「文件或文件夹排除」里添加APIService.xml。

关于Kudu手动添加的补充 #

你之前用Kudu手动添加没成功，大概率是路径不对或者没重启服务：

• 登录Kudu控制台后，要把APIService.xml上传到site/wwwroot目录下（这是App Service的运行根目录）；
• 上传完成后，一定要在Kudu的「工具」→「站点重启」里重启App Service，让程序重新读取文件。

内容的提问来源于stack exchange，提问作者Urgen