容器环境下如何将NuGet包XML文档添加到Swagger
在.NET Core项目开发过程中，为了实现代码复用，我们将可以重复使用的部分拆分成一个个小的NuGet包。这些NuGet包可以在其他系统中复用，这样我们只需要实现系统特定的代码，其余部分的就可以重用了，包括功能、文档等。使用过程中，功能复用没有遇到任何问题，但是文档复用却遇到了问题。我们使用SwashBuckle生成Swagger定义和Swagger UI。Swashbuckle需要XML文档，才能显示控制器和模型的文档说明。不幸的是，Swagger中不能正常显示NuGet包的模型文档说明。 我们可以用在项目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>的方式，将XML文档添加到NuGet包中，然后将XML文档手动拷贝到项目里，作为内容输出。Swagger中就能正常显示NuGet包的模型文档说明了。但是这样做，如果NuGet包版本更新，就需要重新手动拷贝XML文档，感觉不太优雅。是否有更优雅的方式呢？ Google到几篇文章，方案大同小异，不知道可不可行。试试吧！期待可以成功！ 实战 我们涉及到两个项目： ICH.NetCore2.Test.WebApi：ASP.NET Core WebApi 主项目 ICH.Common：可重用的公共组件NuGet包 我们按照以下几个步骤分布实施 。 1、设置.csproj文件构建NuGet包时包含XML文档 ICH.Common的项目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>，作用是设置.csproj文件构建NuGet包时包含XML文档。 <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> 2、定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径 ICH.NetCore2.Test.WebApi的项目文件.csproj的PackageReference中添加<CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory>，作用是定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径。 <ItemGroup> <PackageReference Include="ICH.Common" Version="$(ICHCoreFXVersion)"> <CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory> </PackageReference> </ItemGroup> 在.NET Core中，我们的NuGet包位于： %USERPROFILE%\.nuget\packages\{PackageName}\{PackageVersion} XML文档文件位于： %USERPROFILE%\.nuget\packages\{PackageName}\{PackageVersion}\lib\netcoreapp2.1\{PackageName}.xml 3、设置构建后从NuGet包中复制XML文档 ICH.NetCore2.Test.WebApi的项目文件.csproj添加<Target Name="AfterTargetsBuild" AfterTargets="Build">，作用是设置构建后从NuGet包中复制XML文档。 <Target Name="AfterTargetsBuild" AfterTargets="Build"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)\%(PackageReference.Identity)\%(PackageReference.Version)\%(PackageReference.CopyToOutputDirectory)" /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(OutDir)" /> </Target> 4、设置发布后从NuGet包中复制XML文档 与上一步类似，ICH.NetCore2.Test.WebApi的项目文件.csproj添加<Target Name="AfterTargetsPublish" AfterTargets="Publish">，作用是设置发布后从NuGet包中复制XML文档。 <Target Name="AfterTargetsPublish" AfterTargets="Publish"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)\%(PackageReference.Identity)\%(PackageReference.Version)\%(PackageReference.CopyToOutputDirectory)" /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" /> </Target> 5、添加XML文档到Swagger定义中 ICH.NetCore2.Test.WebApi的项目Startup设置options.IncludeXmlComments(xmlFile, true)，作用是添加XML文档到Swagger定义中。 public static void ConfigureSwagger(this IServiceCollection) { services.AddSwaggerGen(c => { string[] xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml"); foreach (var xmlFile in xmlFiles) options.IncludeXmlComments(xmlFile, true); }); } 6、测试 现在是见证奇迹的时候了。 首先本地构建一下试试，心情忐忑！ 可以看到XML文档从NuGet包中复制到输出目录了，奈斯！ 然后本地发布一下试试，心情依然忐忑！ 可以看到XML文档从NuGet包中复制到输出目录了， 外瑞奈斯！ 最后再看看Swagger效果，Swagger中也能正常显示NuGet包的模型文档说明。 7、遇坑 就这么简单？有一个声音告诉我，图样图森破！ 我们生产环境是采用DockerFile的CICD方式自动发布到K8S集群，发布之后，在生产环境Swagger中并不能正常显示NuGet包的模型文档说明。 Why？Why？Why？另一个声音告诉我，不要慌，冷静思考！ 我们的Dockerfile内容如下： FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base WORKDIR /app EXPOSE 80 FROM microsoft/dotnet:2.1-sdk AS build WORKDIR /src COPY . . WORKDIR /src/src/ICH.NetCore2.Test.WebApi RUN dotnet publish ICH.NetCore2.Test.WebApi.csproj -c Release -o /app FROM base AS final WORKDIR /app COPY --from=build /app . RUN ls RUN rm -rf appsettings.Development.json RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo 'Asia/Shanghai' >/etc/timezone ENTRYPOINT ["dotnet", "ICH.NetCore2.Test.WebApi.dll"] 看了一下CICD日志，发现输出目录并没有ICH.Common.xml文件。 这就存在两种可能： 要么缓存的NuGet包中不存在XML文档 要么缓存的NuGet包中存在XML文档，主项目发布时却没有从NuGet包中复制XML文档。 我们一个个来测试。先看看缓存的NuGet包中到底存不存在XML文档。参考本地NuGet包路径，在Dockerfile中添加RUN ls /root/.nuget/packages/ich.common/3.0.0-ci.63367-beta/lib/netstandard2.0，打印NuGet包中的文件。 注意：Windows和Mac/Linux的global‑packages位置不一致 具体可以参考微软官方文档 FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base WORKDIR /app EXPOSE 80 FROM microsoft/dotnet:2.1-sdk AS build WORKDIR /src COPY . . WORKDIR /src/src/ICH.NetCore2.Test.WebApi RUN dotnet publish ICH.NetCore2.Test.WebApi.csproj -c Release -o /app RUN ls /root/.nuget/packages/ich.common/3.0.0-ci.63367-beta/lib/netstandard2.0 #打印NuGet包中的文件 FROM base AS final WORKDIR /app COPY --from=build /app . RUN ls RUN rm -rf appsettings.Development.json RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo 'Asia/Shanghai' >/etc/timezone ENTRYPOINT ["dotnet", "ICH.NetCore2.Test.WebApi.dll"] 再试试！ 惊，为什么缓存的NuGet包中不存在XML文档呢？不应该啊，本地测试不是好好的吗？难道跟平台有关系？本地是Windows，生产环境是Docker。 Google到微软官方文档，关注NuGet CLI environment variables中有一个环境变量NUGET_XMLDOC_MODE。 NUGET_XMLDOC_MODE Determines how assemblies XML documentation file extraction should be handled. Supported modes areskip(do not extract XML documentation files),compress(store XML doc files as a zip archive) ornone(default, treat XML doc files as regular files). 定义如何处理程序集XML文档文件提取， 不管怎么样，试试吧！ 在Dockerfile中添加ENV NUGET_XMLDOC_MODE none，设置环境变量NUGET_XMLDOC_MODE值为none，也就是 NuGet将XML文档文件视为常规文件。 FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base WORKDIR /app EXPOSE 80 FROM microsoft/dotnet:2.1-sdk AS build WORKDIR /src COPY . . WORKDIR /src/src/ICH.NetCore2.Test.WebApi ENV NUGET_XMLDOC_MODE none # 设置环境变量NUGET_XMLDOC_MODE RUN dotnet publish ICH.NetCore2.Test.WebApi.csproj -c Release -o /app RUN ls /root/.nuget/packages/ich.common/3.0.0-ci.63367-beta/lib/netstandard2.0 #打印NuGet包中的文件 FROM base AS final WORKDIR /app COPY --from=build /app . RUN ls RUN rm -rf appsettings.Development.json RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo 'Asia/Shanghai' >/etc/timezone ENTRYPOINT ["dotnet", "ICH.NetCore2.Test.WebApi.dll"] 再试试！ 奈斯，可以看到ICH.Common.xml文件静静的躺在那！ 再看看输出目录，居然...居然...没有ICH.Common.xml文件。 静静思考，会不会是第4步设置发布后从NuGet包中复制XML文档的路径问题。 修改ICH.NetCore2.Test.WebApi的项目文件.csproj。 <Target Name="AfterTargetsPublish" AfterTargets="Publish"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="/root/.nuget/packages/ich.common/3.0.0-ci.63367-beta/lib/netstandard2.0/*.xml" /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" /> </Target> 再试试！输出目录可以看到ICH.Common.xml文件了。 果然是路径问题，也就是说$(NugetPackageRoot)\%(PackageReference.Identity)\%(PackageReference.Version)不等于/root/.nuget/packages/ich.common/3.0.0-ci.63367-beta。 为什么，难道是大小写的问题？ 修改ICH.NetCore2.Test.WebApi的项目文件.csproj，将PackageReference.Identity转为小写。 <Target Name="AfterTargetsPublish" AfterTargets="Publish"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)\$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())\%(PackageReference.Version)\lib\%(PackageReference.CopyToOutputDirectory)\*.xml" /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" /> </Target> 再试试！输出目录可以看到ICH.Common.xml文件了。 最后再看看Swagger效果，Swagger中也能正常显示NuGet包的模型文档说明。完美！ 总结 填坑的过程是曲折的，收获是颇丰的，结局是圆满的。 最后贴出完整的ICH.NetCore2.Test.WebApi的项目文件.csproj和Dockerfile <Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.1</TargetFramework> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> <ItemGroup> <PackageReference Include="ICH.Common" Version="$(ICHCoreFXVersion)"> <CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory> </PackageReference> </ItemGroup> <Target Name="AfterTargetsBuild" AfterTargets="Build"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)\$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())\%(PackageReference.Version)\%(PackageReference.CopyToOutputDirectory) /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(OutDir)" /> </Target> <Target Name="AfterTargetsPublish" AfterTargets="Publish"> <ItemGroup> <PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)\$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())\%(PackageReference.Version)\%(PackageReference.CopyToOutputDirectory)" /> </ItemGroup> <Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" /> </Target> </Project> FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base WORKDIR /app EXPOSE 80 FROM microsoft/dotnet:2.1-sdk AS build WORKDIR /src COPY . . WORKDIR /src/src/ICH.NetCore2.Test.WebApi ENV NUGET_XMLDOC_MODE none # 设置环境变量NUGET_XMLDOC_MODE RUN dotnet publish ICH.NetCore2.Test.WebApi.csproj -c Release -o /app FROM base AS final WORKDIR /app COPY --from=build /app . RUN ls RUN rm -rf appsettings.Development.json RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo 'Asia/Shanghai' >/etc/timezone ENTRYPOINT ["dotnet", "ICH.NetCore2.Test.WebApi.dll"] 最后 感谢几篇文章的作者给与我的启发，同时也希望这篇文章可以帮助大家解决类似的问题。 <div style="display: none;"> <span id="fulu-org">福禄ICH·架构组</span> <span id="fulu-author">福小皮</span> </div>
