容器环境下将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 are skip (do not extract XML documentation files), compress (store XML doc files as a zip archive) or none (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"]

最后

感谢几篇文章的作者给与我的启发，同时也希望这篇文章可以帮助大家解决类似的问题。

福禄ICH·架构组
福小皮

容器环境下如何将NuGet包XML文档添加到Swagger的更多相关文章

  1. 【HTML/XML 5】使用XSL给XML文档添加样式

    导读:上篇博客中以具体实例分析了HTML和XML在语义上的不同,但是,大家也都发现,XML表现出来的,并没有HTML那样直观或者说美观.其原因是因为XML的表现内容和表现形式被分离.它的表现形式有两种 ...

  2. Xml学习笔记（3）利用递归解析Xml文档添加到TreeView中

    利用递归解析Xml文档添加到TreeView中 private void Form1_Load(object sender, EventArgs e) { XmlDocument doc = new ...

  3. 循环对XML文档添加Attribute以及移除Element 【转】

    如下面的图片要求,需要把左边的xml文改为右边的文档. 需要添加Attribute,移除Element,但是所添加的Attribute值已经跟被移除的Element值不相同.实现方法可以参考<对 ...

  4. 循环对XML文档添加Attribute以及移除Element

    如下面的图片要求,需要把左边的xml文改为右边的文档. 需要添加Attribute,移除Element,但是所添加的Attribute值已经跟被移除的Element值不相同.实现方法可以参考<对 ...

  5. Myeclipse下不用dom4j等解析xml文档

  6. Xml文档添加节点和属性

    XmlDocument doc = new XmlDocument(); XmlElement xmlElement = doc.CreateElement("节点名称"); xm ...

  7. 文档对象模型操作xml文档

    简介 :文档对象模型(DOM)是一种用于处理xml文档的API函数集. 2.1文档对象模型概述 按照W3C的定义,DOM是“一种允许程序或脚本动态地访问更新文档内容,结构和样式的.独立于平台和语言的规 ...

  8. 添加节点至XML文档中去

    不管是<怎样创建XML文档> http://www.cnblogs.com/insus/p/3276944.html还是<泛型List<T>转存为XML文档> ht ...

  9. Docker容器环境下ASP.NET Core Web API应用程序的调试

    本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Docker容器环境下,对ASP.NET Core Web API应用程序进行调试.在 ...

随机推荐

  1. ubuntu系统编译安装OpenCV 4.4

    内容转载自我的博客 目录 前言 1. 下载源码 2. 安装各种依赖 3. 开始编译安装 4. 配置C++开发环境 5. 程序执行时加载动态库*.so 6. 测试cpp文件 7. 配置python3的o ...

  2. ON DUPLICATE KEY UPDATE作用

    ON DUPLICATE KEY UPDATE作用 先声明一点,ON DUPLICATE KEY UPDATE为Mysql特有语法,这是个坑 语句的作用,当insert已经存在的记录时,执行Updat ...

  3. 带你全面认识CMMI V2.0（五）——改进

    改进(Improving)涉及开发.管理和改进过程及其相关资产,其主要重点是提高组织绩效.保持习惯和持久性可确保过程在整个组织中是持久.习惯性地执行和维持,并有助于有效地实现业务绩效目标.治理(GOV ...

  4. badusb论述

    "BadUSB"是2014年计算机安全领域的热门话题之一,该漏洞由Karsten Nohl和Jakob Lell共同发现 攻击原理 TEENSY 攻击者在定制攻击设备时,会向USB ...

  5. C语言利用for循环打印菱形

    C语言利用for循环打印菱形(高度为奇数) 这次用的方法是上下部分分开打印,先打印上部分,再打印下部分. 先举个简单的例子打印,再改进代码,登堂入室从而理解. 例:打印一个高度(高度必须为奇数)为 5 ...

  6. Spring Cloud Alibaba(5)---Nacos(配置中心）

    Nacos(配置中心) 有关Spring Cloud Alibaba之前写过四篇文章,这篇也是在上面项目的基础上进行开发. Spring Cloud Alibaba(1)---入门篇 Spring C ...

  7. 命令行运行py文件报错

    起因 今天用ubuntu 终端运行py文件报了个错,找不到模块? 我切换回pycharm中运行,运行一切正常 解决 在报错模块中,插入绝对路径 import sys sys.path.append(' ...

  8. PHP学员分享：126个常用的正则表达式分享

    PHP学员分享:126个常用的正则表达式分享 电子邮件:/\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*/变量:/[a-zA-Z_\x7f-\xff][a-z ...

  9. 【VsCode】常用的快捷键

    查找和替换: 查找:Ctrl +F 查找和替换:Ctrl +H编辑器和窗口管理相关快捷键: 文件之间切换:Ctrl+Tab 关闭当前窗口:Ctrl+W /Ctrl +F4 切出一个新的编辑器窗口(最多 ...

  10. Thinkphp5之Bootstrap自定义BootstrapDetailed分页插件的实现

    首先,在此目录建立一个newcrm\thinkphp\library\think\paginator\driver\BootstrapDetailed.php文件,代码如下: <?php // ...