Nuget Package 支持打包 ReadMe 了

Posted 2021-06-19 dotNET跨平台

Nuget Package 支持打包 ReadMe 了

Intro

在 3月份，我们在NuGet生态系统状态上发布了一个博客，其中讨论了过去六个月以来从数百名客户那里获得的见解。客户在我们的调查中发现的最大问题之一是，“大多数软件包的文档不足”，可以从NuGet.org 轻松访问到的。实际上，NuGet.org 调查的受访者中有 45％表示“确实存在我需要的关键软件包，但没有充分的文档说明”，这是对NuGet生态系统不满意的原因。

我们很高兴地宣布，您终于可以将 README.md 文件打包到 NuGet 包中，并将其完全呈现在NuGet.org 上了！

NuGet.org上mysqlConnecter包中的README图像

–来自MySqlConnector程序包的图像

这一新功能仍然是 preview：在.NET SDK 5.0.300 预览开始支持，NuGet 5.10 的预览2，和 Visual Studio 16.10 Preview 2. 今天尝试此功能的最简单方法是安装最新的.NET 6预览版本或将最新的Visual Studio预览版。

以前，我们对NuGet.org上的文档提供了有限的支持。但是，这种体验要求作者针对每个新软件包版本将链接粘贴到自述文件或将自述内容粘贴在NuGet.org上。我们从作者那里听说，这一额外的步骤花费了太多时间，并且感觉从软件包创建和发布的其余过程中删除了。

在新的体验中，您可以像添加任何其他嵌入式软件包文件（如图标或许可证）一样添加 README.md 文件。这意味着：

1. 您不必去 NuGet.org 即可将文档添加到您的软件包中，您可以使用喜欢用来打包 NuGet软件包的任何工具来进行处理。

2. 设置项目文件的路径后，每次都会打包最新版本的自述文件README.md。只需设置并忘记它！

3. 自述文件是不可变的，并且是特定于版本的，因此，用户也可以查看软件包较旧版本的相关自述文件！

将自述文件添加到您的包裹中

如果您已经有一个README.md文件，则将其包含在软件包中就像将两行代码添加到SDK样式项目的项目文件中，或者将 nuspec 插入非SDK样式项目的项目一样简单。如果您不熟悉创建NuGet软件包，我们建议您使用SDK风格的项目。

对于以下示例，我将README.md文件保存在“ docs”文件夹中，因此其到我的项目文件的相对路径为docs\\README.md。您还可以在存储库根目录或任何其他文件夹中使用README文件，只要您使用调整相对路径即可。此外，您可以使用任意名称命名目标文件，例如NuGet.md代替README.md

在您的项目文件中添加自述文件（推荐）

您可以在项目文件中引用自述文件，如下所示：

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        ...
        <PackageReadmeFile>README.md</PackageReadmeFile>
        ...
    </PropertyGroup>

    <ItemGroup>
        ...
        <None Include="docs\\README.md" Pack="true" PackagePath="\\"/>
        ...
    </ItemGroup>
</Project>

在您的nuspec中添加自述文件

您可以在nuspec中引用相同的自述文件，如下所示：

<package>
    <metadata>
    ...
    <readme>docs\\README.md</readme>
    ...
    </metadata>
    <files>
    ...
    <file src="..\\README.md" target="docs\\" />
    ...
    </files>
</package>

为NuGet.org编写自述文件(ReadMe)

考虑在自述(README)文件中包括以下各项：

• 您的包裹的用途和作用的简介–它可以解决什么问题？

• 如何开始使用您的包裹-是否有特定要求？

• 如果未包含在自述文件中，则链接到更全面的文档。

• 至少一些代码片段/样本或示例图像。

• 在何处以及如何留下反馈，例如链接到项目 Issue，Twitter，BUG 跟踪器或其他平台。

• 如何进行贡献（如果适用）。

请记住，高质量的自述文件可以有多种格式，形式和长度！如果您在NuGet.org上已经有可用的软件包，则很可能是您的存储库中已经有一个README.md文件，这对于NuGet.org详细信息页面将是一个很好的补充。

预览您的自述文件

要在README文件在NuGet.org上发布之前预览它，请使用NuGet.org上的Upload Package Web门户上传您的包，然后向下滚动到元数据预览的“ Readme File”部分。它看起来应该像这样：

NuGet.org包上传元数据预览页面的README文件预览部分的图像

考虑花些时间查看和预览自述文件，以确保其符合图像规范和受支持的格式，以确保它给潜在用户留下了深刻的第一印象！要纠正自述文件包发布到NuGet.org上的错误，您将需要使用修复程序推送更新的程序包版本。事先确保一切看起来都不错，这可以避免您日后头痛。

Markdown和图片支持

NuGet.org自述文件通过Markdig解析引擎支持与CommonMark兼容的Markdown 。有关受支持的Markdown功能的完整列表，请参见我们的NuGet.org自述文件。

出于安全和隐私方面的考虑，NuGet.org仅支持来自受信任的允许来源列表的徽章和图像。不幸的是，目前也不支持指向本地图像的链接。考虑将本地图像托管在我们信任的来源之一，产生一个链接，以包含在您的NuGet.org自述文件中。

例子

我们要感谢每位自愿参与 NuGet.org 软件包的作者，他们自愿提前尝试了新的README体验，以便为我们提供反馈并作为更广泛的NuGet生态系统的模型。

查看以下NuGet.org软件包以及它们如何使用README来增强其软件包详细信息页面的丰富性并改善新用户和准用户的首次体验：

• NLog.Web.AspNetCore，Julian Verdurmen

• GraphQLing.Client，Giorgi Dalakishvili

• Ben.Demystifier 和 Ben.Http，Ben Adams

• MySqlConnector, Bradley Grainger 和Caleb Lloyed

• CommonHelpers, Lance McCarthy

在哪里可以看到软件包自述文件？

将带有嵌入式README的软件包上载到NuGet.org时，可以在其NuGet.org软件包详细信息页面上找到README 。Visual Studio包详细信息窗格中还将提供自述文件的链接。

Ben.Demystifier程序包详细信息窗格的图像，在Visual Studio中包括在NuGet.org上指向其README的链接。

–图片来自Ben.Demystifier包

我们希望听到您的反馈！

您的反馈对我们来说很重要。如果您在尝试使用新的自述文件功能时遇到任何问题，请查看我们的有关提交错误和建议的文档，以找到寻找解决方案或提出新  Issue 的正确位置。

要查看NuGet接下来会发生什么，请查看我们的公开建议或创建您自己的建议。确保留下您对现有Issue 和 Pull Request 的反馈！

如果您在NuGet.org软件包中添加自述文件，请对其进行发布 Tweet 并提及 @nuget 以从我们那里获得点赞或转发，以表示对您的软件包进行支持和推广！