@jsakamoto

(エディタのXML自動整形でレイアウトが崩れてしまわないよう) プロジェクトファイル外に NuGet パッケージリリースノートを書く

プロジェクトファイルをエディタで編集するのは容易

昨今の C# プログラミングにおける話。
とくに Windows OS 上で Visual Studio を使っての開発場面を想定している。

最近では、XML 形式である C# プロジェクトファイル (.csproj) を、Visual Studio のプロジェクトのプロパティ表示 GUI 経由ではなく、テキストエディタで直接 XML を編集する機会が増えているように思う。

というのも、"SDK スタイル" と呼ばれる今風の形式のプロジェクトファイルであれば、その内容はきわめて簡素だからだ。

加えて既定の設定だと、Visual Studio のソリューションエクスプローラにてプロジェクトのノードをダブルクリックしたときに、そのプロジェクトが "SDK スタイル" であるならば、プロジェクトのプロパティ GUI ではなく、XML テキストエディタで開かれたりもする。

しかしリリースノートの編集は酷いことに...

さてところで、NuGet パッケージライブラリを開発しているような場合は、パッケージに記載されるリリースノートを記述することと思う。

パッケージのリリースノートを、Visual Studio のプロジェクトプロパティ GUI にて編集している間は何の問題もない。

しかしひとたび、Visual Studio のテキストエディタにて、プロジェクトファイルの XML を直接編集し始めると状況は一転する。

というのも、Visual Studio は親切にも、XML 形式であるプロジェクトファイルを保存するたびに、その書式を自動整形してくれるからだ。

そしてこの自動整形が、なんと、プロジェクトファイル内に記載された、改行を含むリリースノートのレイアウトをぶち壊してくれるのである!

ご覧のとおり自動整形が適用されることで、リリースノートに、無用な空白や改行が大量に追加されてしまうのだ。

もちろん、自動整形の機能を無効に設定すれば、このような悲劇は防ぐことが出来る。
とはいえ、今度は、自動整形なしでプロジェクトファイルの編集 (例えば、カスタムビルド処理を書く場合とか) が厄介なことになってしまう。

さてどうしたものか。

解決策

こんなことで悩んでいたある日、ようやく解決策を思いついた。

その方法は、リリースノートをプロジェクトファイル外に記述し、代わりにプロジェクトファイル内からその外部リリースノートファイルを取り込む、というものだ。

以下、その手順を記す。

Step 1. プロジェクトファイル外にリリースノートを記述

まず始めに、"RELEASE-NOTES.txt" といったファイル名のテキストファイルとして、パッケージリリースノートを記述する。

例えばこんな感じ。

v.1.0.1

- Support to Blazor v.3.2 Preview 3.

v.1.0.0

- Initial release.

"RELEASE-NOTES.txt" はどこに配置しても構わないが、以降の説明では、ソリューションがあるフォルダに配置したものとする。

Step 2. プロジェクトファイルからこれを取り込む

次の手筈として、数ステップの MSBuild スクリプトをプロジェクトファイル内に実装し、"RELEASE-NOTES.txt" ファイルの内容を取り込むようにする。

この目的で、MSBuild ターゲットをひとつ作成し (ターゲット名は既存のターゲットと衝突しなければ何でも良い)、"GenerateNuspec" ターゲットよりも前に実行されるようにする。

"GenerateNuspec" ターゲットが実行される直前は、パッケージリリースノートの準備をするのに最適なエントリポイントとなっている。

この MSBuild ターゲットでは、MSBuild に標準で備え付けの "ReadLinesFromFile" タスクを使って "RELEASE-NOTES.txt" ファイルの各行を読み出し、適当なアイテム名 (ここでは "ReleaseNoteLines" とした) の MSBuild アイテムに、読み込んだ各行を出力する。

そしてこれら読み込んだ結果の MSBuild アイテムを使って、"PackageReleaseNotes" MSBuild プロパティを上書き設定すればよい。

なお、既定では、MSBuild はアイテムの連結時、区切り文字をセミコロン (";") で連結する。

しかしここでは、リリースノートを改行区切りで連結する必要がある。

なので、下記のように区切り文字として LF (ラインフィード) を明示的に指定して、MSBuild アイテムの参照を記述する必要がある。

@(ReleaseNoteLines, '%0a')

("%0a" は、MSBuild スクリプトファイル内では "LF" コードを意味する。)

MSBuild ターゲットの全体像は下記のとおりとなる。

<Target Name="BuildPackageReleaseNotes" BeforeTargets="GenerateNuspec">

<ReadLinesFromFile File="../RELEASE-NOTES.txt" >

<Output TaskParameter="Lines" ItemName="ReleaseNoteLines"/>

</ReadLinesFromFile>

<PropertyGroup>

<PackageReleaseNotes>@(ReleaseNoteLines, '%0a')</PackageReleaseNotes>

</PropertyGroup>

</Target>

Step 3. 同僚や他の開発者に向けて、コメントを残す

最後に仕上げとして、もとのリリースノート記述場所に、「パッケージリリースノートは "RELEASE-NOTES.txt" に書いて下さい」というコメントを記載して完成だ。

おわり

こうしてようやく、プロジェクトファイルをバリバリと直接エディタで編集もしつつ、安心してパッケージリリースノートも記述できる環境を整えることができた。

空のフォルダをコンテンツに含む NuGet パッケージのソースコードを Git でバージョン管理する

何を言っているのかわからないかもしれないが、とにかく記す。

こんな感じの、空のフォルダをコンテンツに含む NuGet パッケージを作ったとする。

この NuGet パッケージを作るための .nuspec ファイルはこんな感じで、

<?xml version="1.0" encoding="utf-8"?>

<!-- 例えばファイル名は Foo.nuspec とか。-->

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">

<metadata>

<id>Foo</id>

<version>0.1.0</version>

<authors>(authors)</authors>

<description>(description)</description>

</metadata>

<files>

<file src="Content\" target="Content" />

</files>

</package>

上記、file 要素で指定している Content フォルダの中に、収録の目的である空のフォルダ "Controllers" を設けてある (下図)。

これで、(nuget.exe が PATH 上にある前提で) "nuget.exe pack Foo.nuspec" を実行することで、空のフォルダをコンテンツに含む NuGet パッケージ "Foo.0.1.0.nupkg" ができあがる。

めでたしめでたし、なのだが...

Git では空のフォルダはバージョン管理下に登録されない

このような NuGet パッケージ作成プロジェクトを Git のバージョン管理下においたとする。

ところがである。

Git はその仕様上、空のフォルダはバージョン管理のリポジトリに登録できないのだ。

なので、このプロジェクトの Git リポジトリを clone すると、空のフォルダ (この例では "Content"、及びそのサブフォルダの "Controllers") が復元されない。

その結果、clone した先の作業フォルダで NuGet パッケージ生成を実行しても、下記のようなエラーになってしまう。

Attempting to build package from 'Foo.nuspec'.

Could not find a part of the path '...\Content'.

Git で空のフォルダをバージョン管理に含める方法

自分が知る限り、Git で空のフォルダをバージョン管理に含める直接的な方法は存在しない 。

その代わり、".gitignore" や ".gitkeep" など、何かしらのファイルを配置し、そのファイルを Git バージョン管理に含める事をもって、clone 先でも確実に当該フォルダが作成されるようにする、という回避策が一般的かと思う。

ということで、この NuGet パッケージ作成プロジェクトでも、"Content\Controllers" フォルダに ".gitkeep" を配置し、これを Git バージョン管理に追加してみる (下図)。

そうすると、当然のことながら、このリポジトリの clone 先でも "Content\Controllers" フォルダが再現され、nuget pack コマンドが成功するようになった。

しかし、である。

今度は、できあがった NuGet パッケージに、".gitkeep" ファイルが含まれてしまった (下図)。

これでは、この NuGet パッケージをインストールすると、本当は空っぽのフォルダができあがるのが期待値であるところ、".gitkeep"

ファイルが「ゴミ」ファイルとして配置されてしまう。

exclude 指定してみるが...

それではということで、.nuspec ファイルの指定にて、".gitkeep" を対象ファイルから除外してみた。

...

<files>

<file src="Content\" target="Content" exclude="**\.gitkeep" />

</files>

</package>

これでイケるだろうと思いきや、なんと、下記エラーとなってしまった。

Attempting to build package from 'Foo.nuspec'.

Error NU5017: Cannot create a package that has no dependencies nor content.

ぐぬぬ。

exclude 指定でもなく、".gitkeep" ファイルでもなくて...

あーでもないこーでもないと、検索しまくっているうちに、下記の NuGet の Issue にたどり着いた。

なんと、"_._" というファイルは、NuGet パッケージ作成の際に無視されるらしい。

マジか。

半信半疑で下図のとおり配置し、nuget pack コマンドを実行したところ...

ちゃんと、"_._" ファイル抜きで、空のフォルダを含むコンテンツが、.nupkg 内に再現できた！

"_._" ファイルは、Git にとっては何の変哲もない "ただのファイル" に過ぎないので、普通に Git バージョン管理に登録できる。

これで万事解決と相成った。

nuget.org の "Manage My Packages" ページのダウンロード数をバーチャートで表示

自分のパッケージのDL数の内訳、気になりません?

.NET 系の開発におけるパッケージマネージャ、NuGet。

この NuGet のパッケージを登録、公開するのが NuGet Gallery, nuget.org だ。

この nuget.org には自分が登録したパッケージを一覧で表示するページがあり、ここで各パッケージのダウンロード数を知ることができる。ただしダウンロード数は数字で書かれてるだけなので、どのパッケージがほかと比べてどの程度ダウンロードされているかが、ぱっと見た感じわかりにくい。

グラフで表示できたらいいのに、と思いつつ、たまに Excel にコピーペーストしてグラフ化してた。
だがしかし、当然のことながら毎度この作業を行うのは苦痛。

Excel には Web クエリという便利な機能があるが、この事例ではフォーム認証画面があるせいで自動更新できない。

JavaScript 注入!

しかしある日思いついた。

このページ上にグラフ（バーチャート）を描く、そんな JavaScript を実行してやればよいのではないか、と。

ということでやってみた。

nuget.org の "Manage My Packages" ページを開き、下記 JavaScript リンクをアドレスバーから実行。

javascript:(function(d){var s=d.createElement('script');s.type='text/javascript';s.src='https://goo.gl/5GS0L';d.body.appendChild(s);})(document)

Google 短縮 URL に登録してあるのは、GitHub に公開した、諸々の処理を行う JavScript ファイルへのリンク。この JavaScript をページ内に注入して実行するわけだ。

結果は上々。ブラウザのお気に入り(ブックマーク)に登録しておけば、ブックマークレットとして、ワンクリックで実行できる。

とりあえず満足。

詳しくは GitHub にて。

Visualize NuGet My Packages Download Count
https://github.com/jsakamoto/VisualizeNuGetMyPackagesDownloadCount