Nuget Packages 101: Including a README


When you publish a Nuget package there are two ways to include a README file. You can author one on Nuget when uploaded or include one in the package. This covers the inclusion.

Besides links to a blog post about the package and/or the link the its repository, it is useful to include a brief outline of package as well as a simple HowTo in a README.md Markdown file. You can generate one when the package is uploaded and go back and make subsequent modifications there as part of updates. Alternatively you can include the README in the package and have it uploaded as part of the package. Updates to the README require local edits, regeneration of the package and upload. You can’t edit the README on Nuget in this manner.

In this discussion, the example, DNETCoreGPIO, as per the previous post is used.

Files and folder to include:

In the library project folder place the files in the folders indicated:

  • images/image.jpg
  • docs/README.md

Edit the project file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Figgle" Version="0.4.0" />
    <PackageReference Include="Iot.Device.Bindings" Version="2.1.0" />
    <PackageReference Include="System.Device.Gpio" Version="2.1.0" />
  </ItemGroup>

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

</Project>

Note the reference to the README and image files above and below.

  • Rebuild the project as a RELEASE.
  • Run .\nuget spec, a .nuspec file is generated including the version in the filename.
  • For this example, the .nuspec file was edited as below
<?xml version="1.0" encoding="utf-8"?>
<package >
  <metadata>
    <id>DNETCoreGPIO</id>
    <version>1.0.4</version>
    <title>.NET GPIO on RPi</title>
    <authors>David Jones</authors>
    <owners>David Jones</owners>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <license type="expression">MIT</license>
    <icon>images\image.jpg</icon>
    <projectUrl>https://davidjones.sportronics.com.au</projectUrl>
    <repository type="git" url=https://github.com/djaus2/DNETCoreGPIO branch="main" />
    <description>Implements the various GPIO functionality .NET on a RPi such as LED, temperature sensor, relay and motor H-Bridge</description>
    <releaseNotes>First release on Nuget.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>dotnet rpi gpio</tags>
    <readme>docs\README.md</readme>
  <dependencies>
    <group targetFramework="NET5.0">
      <dependency id="Figgle" version="0.4.0" />
      <dependency id="Iot.Device.Bindings" version="2.1.0" />
      <dependency id="System.Device.Gpio" version="2.1.0" />
    </group>
  </dependencies>
  </metadata>
  <files>
    <file src="bin\Release\net5.0\DNETCoreGPIO.dll" target="lib\net5.0"/>
    <file src="images\image.jpg" target="images\" />
    <file src="docs\README.md" target="docs\" />
  </files>
</package>

The modified .nuspec file

  • Then run .\nuspec pack <.nuspec file name>
  • Then upload the .nupkg file file to Nuget.

The README will now be readable there.

 TopicSubtopic
  Next: > Google Home Windows Bridge
   
 This Category Links 
Category:Coding Index:Coding
  Next: >  
<  Prev:   Nuget Packages 101