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

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

标签：

.NET

容器环境下将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"]

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

点击查看更多内容

为 TA 点赞

若觉得本文不错，就分享一下吧！

评论

评论

共同学习，写下你的评论

评论加载中...

展开查看更多评论

作者其他优质文章

正在加载中

Helenr

Web前端工程师

手记
篇

粉丝

14

获赞与收藏

47

关注作者，订阅最新文章

相关文章推荐

如何在 ASP.Net Core 中使用 Swagger

Swagger 搭建 API 文档管理平台

ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

ASP.NET Core Web API用Swagger提供API文档

阅读免费教程

后端通用面试教程

41个小节 30292 342

网络编程入门教程

20个小节 12503 235

Pandas 入门教程

25个小节 18402 332

推荐

评论

收藏

共同学习，写下你的评论



感谢您的支持，我会继续努力的～

扫码打赏，你说多少就多少

赞赏金额会直接到老师账户

支付方式

打开微信扫一扫，即可进行扫码打赏哦

今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与放弃机会

点击
抽奖

慕课手记新用户专享福利

恭喜你，你的运气太好了，居然抽中了 100个积分！

恭喜你，抽中了价值元的专栏！

太棒了，直接落到你账户里！

积分商城里的罗技鼠标、机械键盘、
Kindle 阅读器、小米平衡车
Apple iPad （10.2英寸）、大额优惠券
在等着你去兑换了噢

作者：

免费赠送

兑换码：1111222211 复制

优惠券可用于购买实战课、体系课
无门槛使用

先去看看，有什么好东西马上兑换我爱学习，选课去


热搜

最近搜索清空