wiprog

C#, .NET, Scala ... について勉強したことのメモ

dotnet pack で XML Document つきのパッケージを作成する

.NET Core では dotnet pack コマンドで簡単に nuget パッケージを作ることができます。
ただデフォルトでは XML document が出力されなくてちょっと困ったので対策を書いておきます。

忙しい人のために

csproj に下記の行を追加すれば XML Document が出力されます

<GenerateDocumentationFile>true</GenerateDocumentationFile>

まずふつうに dotnet pack してみる

こんなてきとうなプロジェクトをつくります。
サンプルなので省略しますがほんとうは PackageId などいろいろ指定します。

docs.microsoft.com

XmlDocSample.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>
</Project>

Sample.cs

using System;

namespace XmlDocSample
{
    public static class Sample
    {
        /// <summary>
        /// 文字列をコンソールに出力します
        /// </summary>
        /// <param name="s">出力する文字列</param>
        public static void Print(string s)
        {
            Console.WriteLine(s);
        }
    }
}

これでいったん pack してみます。

dotnet pack XmlDocSample.csproj -c Release

XML Doc がない。。

できあがった nuget パッケージを参照できるようにソリューションのディレクトリに nuget.config を置きます。

dotnet new nugetconfig

コマンドで nuget.config を作成して、以下のように書き換えます

<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <packageSources>
    <add key="local" value="nuget パッケージのパス" />
 </packageSources>
</configuration>

てきとうなプロジェクトを作って nuget パッケージの管理を開くと、こんな感じで作成した nuget パッケージがでてきます。

f:id:wipiano:20180408114644p:plain

パッケージをインストールして使ってみると・・・

f:id:wipiano:20180408114927p:plain

ほんとうはここにさっき書いたコメントが出てきてほしいのですが、表示されません。

展開された nuget パッケージを見てみると、xml が出力されていないことがわかります。

f:id:wipiano:20180408115509p:plain

XML Document を出力するおまじない

いろいろ調べると、 csproj に 1 個おまじないを書けば XML が出力されることがわかりました。

wmpratt.com

<GenerateDocumentationFile>true</GenerateDocumentationFile>

これを csproj に追加して、もう一度 pack してみます。

すると、ビルド時に XML doc が書かれてないものは警告も出るようになりました。

Sample.cs(5,25): warning CS1591: 公開されている型またはメンバー 'Sample' の XML コメントがありません。

これで作成されたパッケージをインストールして使ってみると・・・

f:id:wipiano:20180408120503p:plain

ちゃんと intellisense にも表示されています。