C# ソースジェネレータで、対象プロジェクトの既定の名前空間を取得する方法

C# でのプログラミングにおける話。

C# の ver.9、収録される .NET SDK のバージョンでいうと .NET SDK 5.0 からになるが、"ソースジェネレータ (Source Generators)" という機能が使えるようになった。

この "ソースジェネレータ" とは何かというと、いうなれば、C# コンパイラに対するある種の "アドイン" を、我々アプリケーションプログラマが実装・配付できる、という機能だ。

"ソースジェネレータ" = "(C#) ソースコードを生成するもの" という名のとおり、ビルド時に追加の C# ソースコードを動的に作成し、対象プロジェクトに付け加える、そういう "C# コンパイラに対するアドイン" プログラムを C# で作成できる、という仕組みになる。

下記の Qiita 記事などが参考になるかもしれない。

対象プロジェクトの既定の名前空間を知りたい

さてこの C# ソースジェネレータは、いくつかの利用例があるのだが、そのひとつとして

「C# じゃないファイルから C# ソースコードを自動生成する」

というシナリオがある。

このシナリオにおいては、ソースジェネレータが生成する C# ソースコード中に記載の名前空間をどうしたものか、という問題につきあたる。

別のシナリオ、例えば

「partial な C# クラスに機能を付け加える (INotifyPropertyChanged の自動実装とか)」

といった場合は、対象の C# クラスの名前空間でソースコードを生成するしかないので、このような問題はとくには無い。

しかし前述の「C# じゃないファイルから C# ソースコードを自動生成する」というシナリオのときは、せめて対象プロジェクトの既定の名前空間を、ソースジェネレータ側で知る必要があると思う。

Compilation.GlobalNamespace というのを見つけたが...

ということで、実際にソースジェネレータを実装しながら、対象プロジェクトの既定の名前空間を取得できるようなプロパティやメソッドが、ソースジェネレータに提供されるコンテキストオブジェクトにないか、インテリセンス (※自分は Windows OS 上で Visual Studio IDE を使って C# プログラミングをしている) で眺めてみた。

そうすると、

Compilation.GlobalNamespace

などという、いかにもソレっぽいメンバーが見つかった。

そこで下記例のように、ソースジェネレータを実装して試してみた。

...

[Generator]

public class MySourceGenerator : ISourceGenerator

{

  public void Execute(GeneratorExecutionContext context)

  {

    var rootNamespace = context.Compilation.GlobalNamespace.ToDisplayString();

    ...

しかし残念ながら、この Compilation.GlobalNamespace プロパティ、どうひねくりまわしても、空文字しか返ってこない。

何か前提条件があるのかもしれないが、その点はよくわからず終いだった。

MSBuild プロパティを参照してみる

そこで作戦を変更し、対象プロジェクトの MSBuild プロパティ値を取得してみることにした。

というのも、プロジェクトの既定の名前空間は、そのプロジェクトの "RootNamespace" という名前の MSBuild プロパティ値に設定されているからだ。

プロジェクト作成後に特に何も変更していなければ、この "RootNamespace" MSBuild プロパティ値はアセンブリの出力名と同じに設定されている。

明示的に指定する場合は、当該プロジェクトの .csproj ファイル中に、以下のように MSBuild プロパティ値の記載となって現れる (下記例)。

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

  <PropertyGroup>

    ...

    <!-- 👇 こんな感じ。-->

    <RootNamespace>MyAppNameSpace</RootNamespace>

    ...

さて、まずは GitHub 上で公開されている "Source Generators Cookbook" というドキュメント (下記) を参照してみる。

すると、"Consume MSBuild properties and metadata" というセクションに、そのものズバリの手順が載っていた。

まず、ソースジェネレータ側では、なんでもかんでも、対象プロジェクトの MSBuild プロパティを取得できるわけではないらしい。

対象プロジェクト内で明示的に指定された MSBuild プロパティ値のみが取得できるようだ。

具体的には、対象プロジェクト内の "<ItemGroup>" メンバとして、"<CompilerVisibleProperty>" 項目を記載し、その "Include" 属性値に、ソースジェネレータからの参照を行ないたい MSBuild プロパティの名前を記載する。

今回のお題である、既定の名前空間は、MSBuild プロパティ "RootNamespace" に設定されているので、これをソースジェネレータから参照できるよう、対象プロジェクトに以下のようなノードを追加する。

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

  <!-- これは対象プロジェクトのプロジェクトファイル (.csproj) -->

  <!-- 👇 これを追加 -->

  <ItemGroup>

    <CompilerVisibleProperty Include="RootNamespace" />

  </ItemGroup>

  ...

こうしておくことで、ソースジェネレータ側では、以下のような実装にて、対象プロジェクトの MSBuild プロパティ、すなわち今回の例だと、既定の名前空間を取得することができた。

// これはソースジェネレータの C# ソースファイル (.cs)

...

[Generator]

public class MySourceGenerator : ISourceGenerator

{

  public void Execute(GeneratorExecutionContext context)

  {

    // 👇 これで変数 rootNamespace に既定の名前空間が入る。

    context.AnalyzerConfigOptions.GlobalOptions.TryGetValue(

        "build_property.RootNamespace", 

        out var rootNamespace);

    ...

なお、取得したい MSBuild プロパティ名をそのまま "AnalyzerConfigOptions.GlobalOptions.TryGetValue()" に渡すのではなく、"build_property.～" という前置詞を付ける必要がある。

名前空間に限らず、任意の MSBuild プロパティを取得可能

今回のお題では、ソースジェネレータの対象プロジェクトの、既定の名前空間をいかに取得するか、ということであった。

しかしこの方法は、既定の名前空間の取得に限らず、任意の MSBuild プロパティをソースジェネレータから取得可能であることを意味する。

対象プロジェクト側 .csproj ファイル内で、"<CompilerVisibleProperty Include="MSBuild プロパティ名" />" という ItemGroup 項目を記載して明示的に参照可能にする必要はあるものの、この方法で MSBuild プロパティを参照すれば、他にも以下のような情報を入手可能だ。

• 対象プロジェクトの出力アセンブリ名
• 対象プロジェクトの各種バージョン
• 対象プロジェクトがあるフォルダの絶対パス
• etc.

もちろん、上記はあくまで例なので、ソースジェネレータコンテキストの "Compilation" プロパティを参照すればわかるものもあるかもしれない (※自分は詳細は未確認)。

しかしとにかく、対象プロジェクトの MSBuild プロパティを取得できることで、ソースジェネレータの実装の幅が広がることだろう。

NuGet パッケージにして再配布するなら

なお、最終的には、開発したソースジェネレータは NuGet パッケージ化して配付する需要が発生することが多いと思う。

そうしたときには、その NuGet パッケージ内には、ソースジェネレータのビルド後の .dll のみならず、前述の "<CompilerVisibleProperty Include="MSBuild プロパティ名" />" の記載を含む .props ファイルも同梱しておくのがよいかと思う。

というのも、利用者に

「この NuGet パッケージを使うときは、"<CompilerVisibleProperty Include="MSBuild プロパティ名" />" を .csproj に記載してください」

とお願いするのはどうかと思うからだ。

このブログ記事では詳細は割愛しここまでとするが、このように、対象プロジェクト内の MSBuild プロパティ値を使用するソースジェネレータも、NuGet パッケージ化して配付できるよ、ということだ。

以上。