自分のNuGetパッケージのページにREADMEを表示する方法

こんにちは。MLBお兄さんこと松村です。ヤンキースの調子が上がりません（涙

---

自分で NuGet パッケージを作ると多くの場合は nuget.org で公開すると思います。
nuget.org で公開するページに、リポジトリで管理している README ファイルを埋め込めることができるようになりました。

devblogs.microsoft.com

これまでは別途 GitHub などを見に行く必要があったので、パッケージのインストールやセットアップ手順が nuget.org で見れるようになるのは便利ですね。

実際に試してみたので、手順と注意点をまとめておきます。

README.md はリポジトリに含める

README.md はライブラリのプロジェクトファイル (.csproj) やソースコード (.cs) と同じ Git リポジトリに含めておきましょう。

パッケージに README.md を含める

.csproj ファイルを編集し、パッケージ (.nupkg) に README.md を含めるようにします。

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

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

ちなみに <None Include="docs\README.md" に書くパスは .csproj からみた README.md のパスになります。

docs.microsoft.com

なお、同等の設定は nuspec ファイル でも行うことができます。

この状態で nuget.org で .nupkg ファイルをアップロードすれば、パッケージのページに README.md の内容が表示されるようになります。

でも、やっぱり CI/CD でやりたいですよね。

パイプライン定義の注意点

パッケージファイルの設定のドキュメントに以下の記載があります。

NuGet 5.10.0 preview 2 / .net SDK 5.0.300 以降でサポートされています

なのでプロジェクトをビルド、パッケージングする際には .NET 5 SDK や .NET 6 Preview SDK を使う必要があります。

通常 Azure Pipelines で dotnet CLI を使うと、エージェントのビルドマシンに事前インストールされた SDK が使用されます。
例えば Ubuntu 20.04 を選んだ場合、記事執筆時点では 5.0.300 の SDK バージョンが既定で使用されます。

なので Ubuntu 20.04 を使う場合はこのままビルドやパッケージングを行えば良いですね。
.NET 3.1 SDK が既定の場合は Use .NET Core task を使って、.NET 5 SDK や .NET 6 Preview SDK をインストールしましょう。

なお、.NET Core 3.1 以前の SDK でパッケージングした場合、 NuGet 5.10.0 preview 2 を使ってプッシュしても README は表示されませんでした。

azure-pipelines.yml の例

ということで、NuGet パッケージのページに README を表示するための azure-pipelines.yml を例として載せておきます。

trigger:
- main

pool:
  vmImage: ubuntu-latest

variables:
  buildConfiguration: Release

steps:
- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '5.x'
- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    arguments: '--configuration $(buildConfiguration)'
- task: DotNetCoreCLI@2
  inputs:
    command: 'pack'
    packagesToPack: '**/*.csproj'
    nobuild: true
    versioningScheme: 'off'
- task: NuGetCommand@2
  inputs:
    command: 'push'
    packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg'
    nuGetFeedType: 'external'
    publishFeedCredentials: 'nuget.org'