容器環境下如何將NuGet包XML文檔添加到Swagger

時間  2021-05-25
標籤 json 緩存 架構 app 測試 this url spa .net 欄目 XML 简体版
原文   原文鏈接

在.NET Core項目開發過程當中，爲了實現代碼複用，咱們將能夠重複使用的部分拆分紅一個個小的NuGet包。這些NuGet包能夠在其餘系統中複用，這樣咱們只須要實現系統特定的代碼，其他部分的就能夠重用了，包括功能、文檔等。使用過程當中，功能複用沒有遇到任何問題，可是文檔複用卻遇到了問題。咱們使用SwashBuckle生成Swagger定義和Swagger UI。Swashbuckle須要XML文檔，才能顯示控制器和模型的文檔說明。不幸的是，Swagger中不能正常顯示NuGet包的模型文檔說明。json

咱們能夠用在項目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>的方式，將XML文檔添加到NuGet包中，而後將XML文檔手動拷貝到項目裏，做爲內容輸出。Swagger中就能正常顯示NuGet包的模型文檔說明了。可是這樣作，若是NuGet包版本更新，就須要從新手動拷貝XML文檔，感受不太優雅。是否有更優雅的方式呢？緩存

Google到幾篇文章，方案大同小異，不知道可不可行。試試吧！期待能夠成功！架構

實戰

咱們涉及到兩個項目：app

  • ICH.NetCore2.Test.WebApi：ASP.NET Core WebApi 主項目
  • ICH.Common：可重用的公共組件NuGet包

咱們按照如下幾個步驟分佈實施 。測試

一、設置.csproj文件構建NuGet包時包含XML文檔

ICH.Common的項目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>，做用是設置.csproj文件構建NuGet包時包含XML文檔。ui

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

二、定義從NuGet包文件夾的根目錄到XML文檔所在位置的相對路徑

ICH.NetCore2.Test.WebApi的項目文件.csproj的PackageReference中添加<CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory>，做用是定義從NuGet包文件夾的根目錄到XML文檔所在位置的相對路徑。this

<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

三、設置構建後從NuGet包中複製XML文檔

ICH.NetCore2.Test.WebApi的項目文件.csproj添加<Target Name="AfterTargetsBuild" AfterTargets="Build">，做用是設置構建後從NuGet包中複製XML文檔。url

<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>

四、設置發佈後從NuGet包中複製XML文檔

與上一步相似，ICH.NetCore2.Test.WebApi的項目文件.csproj添加<Target Name="AfterTargetsPublish" AfterTargets="Publish">，做用是設置發佈後從NuGet包中複製XML文檔。spa

<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>

五、添加XML文檔到Swagger定義中

ICH.NetCore2.Test.WebApi的項目Startup設置options.IncludeXmlComments(xmlFile, true)，做用是添加XML文檔到Swagger定義中。.net

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);
    });
}

六、測試

如今是見證奇蹟的時候了。 首先本地構建一下試試，心情忐忑！ 1619667623 能夠看到XML文檔從NuGet包中複製到輸出目錄了，奈斯！

而後本地發佈一下試試，心情依然忐忑！ 1619667701 能夠看到XML文檔從NuGet包中複製到輸出目錄了， 外瑞奈斯！

最後再看看Swagger效果，Swagger中也能正常顯示NuGet包的模型文檔說明。

七、遇坑

就這麼簡單？有一個聲音告訴我，圖樣圖森破！ 咱們生產環境是採用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文件。 1619667764 這就存在兩種可能：

  • 要麼緩存的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。 1619667812 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文件靜靜的躺在那！ 1619667846 再看看輸出目錄，竟然...竟然...沒有ICH.Common.xml文件。 1619667893

靜靜思考，會不會是第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文件了。 1619668003 果真是路徑問題，也就是說$(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文件了。 1619668003 最後再看看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>

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程