容器环境下如何将NuGet包XML文档添加到Swagger
容器环境下将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 80FROM 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 /appFROM 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 80FROM 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 80FROM 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 80FROM 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 /appFROM 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文档添加到Swagger相关推荐
- Xml文档添加节点和属性
在实际的应用开发中需要我们对xml进行添加节点和属性,动态的去完成,在这之前,先看看XmlNode和XmlElement之间的关系 1.XmlElement继承XmlLinkedNode又继承XmlN ...
- .NET 容器环境下创建应用 dump 文件
.NET 容器环境下创建应用 dump 文件 Intro 有时候我们的应用会出现一些异常的情况,比如内存飙升,线程死锁等等,通过一些 metrics 我们可能大概的了解内存是增长了,但是具体是哪里增长 ...
- Docker容器环境下ASP.NET Core Web API应用程序的调试
本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Docker容器环境下,对ASP.NET Core Web API应用程序进行调试.在 ...
- wireshark linux远程,如何在SSH连接Linux的环境下使用wireshark抓包云边端架构?
原标题:如何在SSH连接Linux的环境下使用wireshark抓包云边端架构? TSINGSEE青犀视频云边端架构EasyNVR.EasyDSS.EasyGBS等都是有两种操作系统的版本,一种是li ...
- 视角 | 多容器环境下的日志管理难?有人做起了这个生意
本文讲的是视角 | 多容器环境下的日志管理难?有人做起了这个生意, [编者的话]本文介绍了一个新的工具SPM,它用于解决在多容器环境下日志管理所遇到的问题,同时它整合了多种功能,避免了以往需要安装多种 ...
- ssis导入xml_使用SSIS包将XML文档导入SQL Server表
ssis导入xml This article guides you through importing XML documents into SQL tables using SSIS package ...
- qt xml组包_Qt 利用XML文档,写一个程序集合 二
XML文档的读写 一个根节点,下面每一个子节点代表一个子程序,内容为子程序名字,图标路径,exe路径 /* * 读取XML配置文档 */ static int count_flag = 0; void ...
- DOM4J解析XML文档、Document对象、节点对象节点对象属性、将文档写入XML文件(详细)...
Dom4j是一个简单.灵活的开放源代码的库.Dom4j是由早期开发JDOM开发的.与JDOM不同的是,dom4j使用接口和抽象的人分离出来而后独立基类,虽然Dom4j的API相对要复杂一些,但它提供了 ...
- java xml 合并_Java中合并XML文档的设计与实现
为了读写XML文件,需要导入如下JAVA包,"//"后为注释说明,笔者的环境是JDK1.3.1,在JDK 1.4.0中测试也通过. Import java.io. *; //Jav ...
最新文章
- 安装Oracle11g先决条件检查失败
- 牛客2018校招 1. 拼多多 大整数相乘
- 【C 语言】指针间接赋值 ( 直接修改 和 间接修改 指针变量 的值 | 在函数中 间接修改 指针变量 的值 | 在函数中 间接修改 外部变量 的原理 )
- Linux的软硬链接ln
- Binary String Minimizing CodeForces - 1256D(贪心)
- spring管理的类如何调用非spring管理的类
- tomcat 配置https安全认证协议报错解决方案
- java语言在线编译器的设计与实现,已获万赞
- 利用Gabor变换法分析纹理图像 matlab代码实现
- 区块链开发_比特币开发1
- Hadoop2.2伪分布式搭建步骤
- 记录成功通过CSP接口获取Ukey的X509数字证书过程
- missing privilege separation directory /var/empty/sshd问题解决
- 俞渝年轻图片_组图:2007中国职场女性榜样-俞渝
- windows 设置设置程序的起始位置
- 服务器和交换机物理连接_Brocade博科交换机 SAN存储区域网络
- 动态jsp页面转pdf项目示例
- 中国集成电路产业投资建议与十四五需求规模分析报告2022版
- 《缘起缘灭缘终尽,花开花落花归尘》
- 域名转让代码_域名转让怎么做?
热门文章
- 电机控制器培训资料-《如何快准狠的标定永磁同步电机》 品牌:车用电机控制器
- 帧同步游戏开发基础指南
- 十年阿里云存储进化史:今天最好的表现就是明天最低的要求
- EVE模拟器关联CRT与Wireshark
- c语言入门自学免费app,C语言入门学习最新版下载-C语言入门学习app手机版v1.0.2 安卓版-腾飞网...
- android 日历开发教程,android 开发教程之日历项目实践(三)
- arduino电风扇程序_Arduino实验项目:温控电风扇
- 使用笔记本的不良习惯
- Hexo博客中插入图片,在网页中无法显示:采用图床外链的方法
- Round12—Huffman 树