MSBuild の WriteLinesToFile で、改行、あるいはセミコロンを含むテキストを、ファイルに書き出す方法

ビルドスクリプト "MSBuild"

C# プログラミングなどで使われるビルドスクリプト MSBuild のお話。

すなわち、C# プログラミングなどにおいて、"プロジェクトファイル" と呼ばれる、例えば拡張子 .csproj の、XML 書式のあのファイルが、実は MSBuild (エムエスビルド) スクリプトファイルである。

最近は .NET Core の進出により、プロジェクトファイル (MSBuild スクリプトファイル) の中身が、"SDK スタイル" と呼ばれる随分とすっきりした内容に進化している。  

また、Visual Studio を使って開発中の場合、この "SDK スタイル" のプロジェクトファイルを、Visual Studio のソリューションエクスプローラからのダブルクリックで、Visual Studio 内のエディタで中身が開かれる (※Visual Studio の設定によって動作は変更可能)。

このようなこともあり、最近はプロジェクトファイル (MSBuild スクリプトファイル) をエディタで直接編集して、ビルド時のカスタム処理などを MSBuild スクリプトとして書くことも多くなった。

MSBuild スクリプトでテキストファイルを書き出す

さてそんな MSBuild スクリプトであるが、つい先日、ビルド時のカスタム処理のひとつとして、とあるテキストファイルの生成を、MSBuild スクリプト内で実装したい要件が発生した。

このようなケースで使える MSBuild スクリプトの標準タスク (プログラミング言語で言うところの標準ライブラリ関数の MSBuild 版) として、WriteLinesToFile タスクがある。

上記公式ドキュメントにあるとおり、使い方は難しくない。

書き込み先のファイルのパスと、書き込む内容の文字列を、それぞれしかるべき属性に指定してやれば良い。

例えば以下のような XML ファイルを、例えば foo.msbuild とかいうファイル名で保存しておき、

<Project>

  <Target Name="test">

    <WriteLinesToFile 

      File="foo.txt" 

      Lines="Hello World" />

  </Target>

</Project>

.NET Core SDK がインストールされている環境 (Windows でも macOS でも各種 Linux ディストリでも OK) で、この foo.msbuild ファイルがあるディレクトリ上で以下のように dotnet コマンドを実行すれば、

dotnet msbuild test.msbuild -t:test

同ディレクトリ直下に、"foo.txt" というファイル名で、中に "Hello World" と書かれたテキストファイルが生成される。

なお、既に指定されたファイル名のファイルが存在している場合は、そのファイルに行追加されるのが既定の動作。

追記ではなく上書きとしたい場合は Overwrite 属性を書き足して true を指定してやればよい。

そうすることで、追記ではなく、上書きの動作となる。

また Overrite="true" を設定している場合に、これから書き込もうとしている内容と、既に存在する書き込み先ファイルの内容とが合致している場合は何もしない、すなわち、書き込み先ファイルの最終更新日時を変更しないようにすることもできる。  

そのためには WriteOnlyWhenDifferent 属性に true を設定してやるとよい。

改行を含むテキストファイルを生成するには?

さてそんな WriteLinesToFile 標準タスクであるが、さて、内容が単一行のテキストファイルではなく、複数行の内容のテキストファイルを書き出したい場合はどうすればよいだろうか?

まずひとつめのやり方だが、そもそもとして、MSBuild スクリプトは XML 書式で記述する。

なので、WriteLinesToFile 標準タスクの Lines 属性に指定する内容に、改行を意味する文字コードを XML の文法に従ってエンコードして指定 (実体参照) することで実現可能だ。

LF での改行を行なうなら、以下のように "&#xa;" を指定するとよい。 

<WriteLinesToFile 

  File="foo.txt" 

  Lines="line1&#xa;line2&#xa;line3"

  Overwrite="true"/>

そして、他にも MSBuild 特有の方法がある。

実は、MSBuild では、「複数の項目 (リスト)」を即値で記述するには、セミコロンで区切る、という文法となっている。

強引にざっくり例えると、JavaScript であれば  "[1, 2, 3]" というように「複数の項目」を表現するところを、これを MSBuild で示すと "1;2;3" という記法になる、ということだ。

そして、WriteLinesToFile 標準タスクにおける、書き出すテキスト本文を指定する属性の名前をよくよく見ると、"Lines" というように複数形になっている。

そう、実は WriteLinesToFile 標準タスクは、書き出すテキスト本文の指定に「複数の項目 (リスト)」を渡せる仕様なのだ。

ということで、改行を含むテキストファイルの生成は以下のように記述できる。

<WriteLinesToFile 

  File="foo.txt" 

  Lines="line1;line2;line3"

  Overwrite="true"/>

※こういった MSBuild の書き方は、下記書籍で勉強させていただきました。

...じゃぁセミコロンを書き出すにはどうすれば?

さてここで注意が必要となるのは、「改行がしたいんじゃなくて、セミコロンを含むテキストを書き出したい」場合だ。

実体参照方式で "&#x3b;" などとセミコロンの文字コードで指定しても、これは効果はない (改行になる)。

よく考えればわかることではあるが、実体参照方式で記述しようとしまいと、その XML を読み込んだ側、すなわち MSBuild エンジンの身にしてみれば、セミコロンはセミコロンである。  

つまり、元の XML 側での表現方法が違っても、パース (読み込み) した結果には違いがない訳だ。

このケースで必要なのは XML の書き方の知識ではなく、MSBuild における特殊文字のエスケープ表記方法の知識だ。

幸い、その方法は公式ドキュメントに明記されている。

上記にあるとおり、「% に続く、ASCII 文字コードを意味する16進数表記」という記法で、MSBUild 上における特殊文字、すなわち今回のケースではセミコロンを、表現可能だ。

セミコロンについては、具体的には `%3b` と記述すればよい。

ということで、下記のような C# ソースコードを生成することも可能である。

<WriteLinesToFile 

  File="foo.cs" 

  Lines="var foo = &quot;bar&quot;%3b"

  Overwrite="true"/>

おわり

以上。

XML の実体参照による特殊文字の記述と、MSBUild 固有の特殊文字をエスケープする記法とで、つい頭の中がこんがらがってしまうことがあったので、改めて本記事にまとめてみた次第。

MSBuild スクリプトで、ビルド時に同時に C# ソースファイルを自動生成しようとして、「行末のセミコロンが書き出されない!」と焦っていたのは内緒だ。