ITPub博客
首页 博客 专栏 学院 社区 IT新媒体评选
发博

首页 > IT职业 > IT生活 > 容器环境下如何将NuGet包XML文档添加到Swagger

容器环境下如何将NuGet包XML文档添加到Swagger

IT生活 作者：silverhoof 时间：2021-09-09 08:52:50 0 删除 编辑

容器环境下将NuGet包XML文档添加到Swagger

在.NET Core项目开发过程中，为了实现代码复用，我们将可以重复使用的部分拆分成一个个小的NuGet包。这些NuGet包可以在其他系统中复用，这样我们只需要实现系统特定的代码，其余部分的就可以重用了，包括功能、文档等。使用过程中，功能复用没有遇到任何问题，但是文档复用却遇到了问题。我们使用SwashBuckle生成Swagger定义和Swagger UI。Swashbuckle需要XML文档，才能显示控制器和模型的文档说明。不幸的是，Swagger中不能正常显示NuGet包的模型文档说明。

我们可以用在项目文件.csproj的PropertyGroup中添加true的方式，将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中添加true，作用是设置.csproj文件构建NuGet包时包含XML文档。

PropertyGroup>
      TargetFramework>netstandard2.0/TargetFramework>
      GenerateDocumentationFile>true/GenerateDocumentationFile>
/PropertyGroup>

2、定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径

ICH.NetCore2.Test.WebApi的项目文件.csproj的PackageReference中添加libnetstandard2.0*.xml，作用是定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径。

ItemGroup>
      PackageReference Include="ICH.Common" Version="$(ICHCoreFXVersion)">
             CopyToOutputDirectory>libnetstandard2.0*.xml/CopyToOutputDirectory>
      /PackageReference>
/ItemGroup>
  • 在.NET Core中，我们的NuGet包位于：
    %USERPROFILE%.nugetpackages{PackageName}{PackageVersion}
  • XML文档文件位于：
    %USERPROFILE%.nugetpackages{PackageName}{PackageVersion}libnetcoreapp2.1{PackageName}.xml

3、设置构建后从NuGet包中复制XML文档

ICH.NetCore2.Test.WebApi的项目文件.csproj添加，作用是设置构建后从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添加，作用是设置发布后从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>libnetstandard2.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"]

作者：福禄网络技术团队
出处：https://www.cnblogs.com/fulu/p/14807710.html

来自 “ ITPUB博客 ” ，链接：https://blog.itpub.net/1528/viewspace-2797180/ ，如需转载，请注明出处，否则将追究法律责任。

0
0
上一篇： MindSpore：不用摘口罩也知道你是谁
下一篇： webpack解析(1)
请登录后发表评论 登录
全部评论
silverhoof

注册时间：2019-04-15

  • 博文量
    81
  • 访问量
    903

最新文章

支持我们 作者招募 用户协议 FAQ Contact Us

北京盛拓优讯信息技术有限公司. 版权所有  京ICP备16024965号-8 北京市公安局海淀分局网监中心备案编号：11010802021510 niuxiaotong@pcpop.com 17352615567 未成年人举报专区

广播电视节目制作经营许可证(京) 字第1234号 中国互联网协会会员

违法和不良信息举报电话:18101376593