.NET 8 から、リフレクションなしでアクセシビリティを無視した(private や internal なメンバーにアクセス可能な)仕組みとして UnsafeAccessor というものが追加されました。

用途が狭いですし、unsafe と付く名前通り割とデメリットもある機能なので、使い心地はそれほどよくありません。 「全くできないと困るので口だけは用意した」系の機能になります。 例えば、フィールド1個にアクセスするだけでも以下のような書き方になります。

using System.Runtime.CompilerServices;

A a = new();

X.RefValue(a) = 1; // private であることを無視して a._value = 1; 相当の処理を実行。
Console.WriteLine(a); // A(1)

static class X
{
    // A._value にアクセスするためのメソッド。
    [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_value")]
    public static extern ref int RefValue(A @this);
}

class A
{
    private int _value;
    public override string ToString() => $"A({_value})";
}

UnsafeAccessor 属性(System.Runtime.CompilerServices)を付けた extern メソッドを書くと、.NET Runtime が静的に(JIT 時に) _value フィールド直参照と同等のコードを生成します。

アクセシビリティ無視とリフレクション

これまでアクセシビリティを無視したい場合、 たとえ型情報が静的に既知であってもリフレクションを使っていました。 例えば冒頭の例同様に a._value = 1; するためだけに、以下のようなコードが必要になっていました。

A a = new();

// a._value = 1; 相当のコードをリフレクションでやるとこうなる。
typeof(A)
    .GetField("_value", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!
    .SetValue(a, 1);

// Type 型インスタンスが作られて、
// FieldInfo 型インスタンスが作られて、
// 動的な処理で a._value = 1; 相当のコードを実行。
// しかも、int 型の 1 は object にボックス化されるコストもかかる。

Console.WriteLine(a); // A(1)

class A
{
    private int _value;
    public override string ToString() => $"A({_value})";
}

コード中のコメントに書きましたが、この処理には様々なオーバーヘッドがかかります。 本当に動的な処理がしたい(本当に実行時まで型に関する情報を知らない)なら必要なコストですが、 この例の A のように型が既知の場合だいぶもったいないです。

すなわち、リフレクションの持つ以下の2つの側面があるわけですが、

1. 実行時までわからない型のメンバーを読み書きする
2. 本来アクセスできないメンバーを読み書きする

このうち後者だけを切り出したものが UnsafeAccessor です。

UnsafeAccessor を使った冒頭のコードなら、 パフォーマンス的には a._value = 1; と同水準になります。

余談: 「unsafe」

名前に unsafe の文字が入っていますが、 メモリ安全性や型安全性の保証はあります(この意味では普通に safe)。 バッファー オーバー ランのようなメモリ脆弱性を起こせるような機能ではないですし、 型が合わないようなコードを書くと JIT 時にエラーになります。

UnsafeAccessor の「unsafe」は「private や internal な物に触れるので変更されても文句が言えない」くらいの意味です。

また、C# コンパイラーのレベルでは型チェックできない(JIT 時チェックになるので実行してみる必要はある)という不利益もあります。

利用場面

UnsafeAccessor の主な用途は以下のようなものです。

1. シリアライザーや DI などをリフレクションから Source Generator に移行したい
2. 元々あった大きなアセンブリを複数に分ける際などにやむを得ず使う
3. 単体テスト用途

元々の想定利用場面は 1. になります。 シリアライザーでは private なフィールドへの読み書きをリフレクションで行うことが多かったです。 ところがこれは、 リフレクションを避けたい実行環境 (AOT や、Web Assembly など)で困りました。 シリアライザーの場合まさに「型は静的に既知」な場合が多く、 リフレクションを使った動的コード生成から、 Source Generator を使った静的なコード生成への移行が進んでいます (例: System.Text.Json のソース生成利用)。 これがまさに UnsafeAccessor で想定する場面になります。

ただ、多くの人にとって、 Source Generator は使う側にはなる一方で、作る側になることは希少です。 そのため 1. の用途では、UnsafeAccessor も「ライブラリで内部的に使われている」であって、直接の利用はあまりないでしょう。

続いて 2. ですが、 これもよほど大規模でよほど歴史のあるコードでしか見られないものです。 例えば .NET の標準ライブラリ内で、 System.Net.Security から System.Net.Http 内の internal 型への参照が残っています。 元々大きな1つのアセンブリとして提供していたものを「Http」と「Security」で分けたときに困ったものと思われます。

結局のところ、多くの人にとっては 3. の単体テスト用途で使うことが多くなると思われます。 「private メンバー、internal メンバーの単体テストはすべきかどうか」ということ自体議論が分かれる問題ですが、まあ「private アクセスしたくなったことがある」くらいであれば多くの人が通ったことがある道だと思います。

例えば以下のようなライブラリ コードがあったとして、 「Dispose 後は中身が null になっていてほしい」というテストを書くみたいな用途が考えられます。

namespace Lib;

public class Class1(object? resource) : IDisposable
{
    private object? _someResource = resource;

    public void Dispose()
    {
        _someResource = null;
    }
}

using Lib;
using System.Runtime.CompilerServices;

namespace TestProject1;

public class UnitTest1
{
    [Fact]
    public void Dispose後は中身がnull()
    {
        var x = new Class1("");

        using (x)
        {
        }

        Assert.Null(GetSomeResourceRef(x));
    }

    [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_someResource")]
    private static extern ref object? GetSomeResourceRef(Class1 class1);
}

こういう単体テストがいいのかどうかという話はありますが… (仕様に応じて「Dispose 後に何らかの操作をしても何も起きない」とか「ObjectDisposedException が出る」とか、別の形でのテストが望ましい可能性あり。) 「やりたいことは時々ある」の範疇かと思われます。

単体テストの場合、ライブラリと単体テストでプロジェクトは分かれているものの、同じ人がコードを書くことが非常に多いです。 そのため「private なものは変更されても文句が言えない」問題が軽微(変更して単体テストが失敗するようになっても、修正する義務を同じ人が負うのですぐに直すことになるだけ)なので、UnsafeAccessor とは相性がいいです。

UnsafeAccessor の書き方

すでにいくつかの例を書いていますが、UnsafeAccessor を使うには UnsafeAccessor 属性(System.Runtime.CompilerServices 名前空間)を付けた extern メソッドを書きます。

UnsafeAccessor 属性の第1引数に渡す UnsafeAccessorKind には以下の5つの値があります (ほぼ名前通り):

• Constructor: コンストラクター
• Method: インスタンス メソッド
• StaticMethod: 静的メソッド
• Field: インスタンス フィールド
• StaticField: 静的フィールド

プロパティ、インデクサーや演算子などは「.NET の型システム上はメソッドになっている」という仕様があるので、Method か StaticMethod を使ってそのメソッドを呼び出すことになります。

ちなみに、型自体は public という場面では A Accessor() とか void Accessor(A x) みたいな素直な書き方で A の private メンバーにアクセスできるんですが、 型自体が internal の時はさらにちょっと面倒な書き方が必要になります。 この場合は、UnsafeAccessorType というもう1つの属性を使って、文字列で型名を指定することになります。

コンストラクター

コンストラクターへのアクセスは以下のように書きます。

using System.Runtime.CompilerServices;

Console.WriteLine(X.CreateA());
Console.WriteLine(X.CreateA(1));

static class X
{
    // new A() 相当。
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    public static extern A CreateA();

    // new A(value) 相当。
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    public static extern A CreateA(int value);
}

class A
{
    private A() { }
    private A(int value) => Value = value;

    private int Value { get; }
    public override string ToString() => $"A({Value})";
}

「何の型のコンストラクターを呼ぶか」は戻り値の型を見ます。 メソッドの引数の型はアクセス先のコンストラクターの引数と一致させます。 (引数名は違っていても平気です。一致の必要があるのは型のみ。)

この機能は構造体に対しても使えます。

static class X
{
    // 構造体に対しても使えて、書き方はクラスの場合と同じ。
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    public static extern A CreateA(int value);
}

struct A
{
    private A(int value) => Value = value;
    private int Value { get; }
    public override string ToString() => $"A({Value})";
}

インスタンス メソッド

インスタンス メソッドへのアクセスは以下のように、 「先頭に1つ引数を足す」書き方をします。

using System.Runtime.CompilerServices;

var a = new A();
X.Add(a, 1);
Console.WriteLine(a); // A(1)

var b = new B();
X.Add(ref b, 1);
Console.WriteLine(b); // B(1)

static class X
{
    // 第1引数をアクセス先の型にする。
    // (拡張メソッドと同じ感覚。)
    [UnsafeAccessor(UnsafeAccessorKind.Method)]
    public static extern void Add(A a, int value);

    // 構造体のインスタンス メソッドを呼びたい場合は ref 引数にする。
    // このメソッドの名前とアクセス先のメソッドの名前が違う場合は、Name で明示的に指定する。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "PrivateAdd")]
    public static extern void Add(ref B a, int value);
}

class A
{
    private int _value;
    private void Add(int value) => _value += value;
    public override string ToString() => $"A({_value})";
}

struct B
{
    private int _value;
    private void PrivateAdd(int value) => _value += value;
    public override readonly string ToString() => $"B({_value})";
}

2つ目以降の引数の型はアクセス先のメソッドの引数と一致させます。 (コンストラクター同様、型のみの一致で OK。) また、戻り値の型が一致している必要もあります。

アクセス先の型が構造体の場合、第1引数は ref もしくは in でないとアクセスできなくなります。 (実行時エラーを起こします。)

また、UnsafeAccessor 属性をつけるメソッドの名前とアクセス先のメソッドの名前が異なる場合には Name プロパティの明示が必要になります。

フィールド

インスタンス フィールドへのアクセスは以下のように、 「ref 戻り値、引数なしのメソッド」で書きます。

using System.Runtime.CompilerServices;

var a = new A();
X.Value(a) = 1;
Console.WriteLine(a); // A(1)

static class X
{
    // 引数なし、ref 戻り値なメソッドでアクセス。
    [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_value")]
    public static extern ref int Value(A a);
}

class A
{
    private int _value;
    public override string ToString() => $"A({_value})";
}

フィールドとメソッドでは命名規約が違う(_value と Value になる)ので、 自然な書き方をしようとすると Name の明示が必要になるかと思いますが、 メソッド名が変でもいいなら以下のように Name の省略もできます。

static class X
{
    // あまりメソッドに _ 始まりの名前を付けないものの、気にしないのであればこれでも OK。
    [UnsafeAccessor(UnsafeAccessorKind.Field)]
    public static extern ref int _value(A a);
}

静的メソッド、静的フィールド

静的メソッド、静的フィールドへのアクセスには UnsafeAccessorKind の StaticMethod と StaticField を使います。 インスタンス メソッド、インスタン フィールドの時と同様、引数の先頭にアクセス先の型を足します(静的メンバーなのでこの第1引数は使われず、ダミー引数になります)。

using System.Runtime.CompilerServices;

X.Value(null) = 2;

Console.WriteLine(X.M(null, 3));

static class X
{
    [UnsafeAccessor(UnsafeAccessorKind.StaticField, Name = "_value")]
    public static extern ref int Value(A? _);

    [UnsafeAccessor(UnsafeAccessorKind.StaticMethod)]
    public static extern int M(A? _, int x);
}

class A
{
    private static int _value;
    private static int M(int x) => x * _value;
}

プロパティ

UnsafeAccessorKind にはプロパティを指定する方法はありませんが、 C# のプロパティは内部的にはメソッドになっているので、 そのメソッドに対する UnsafeAccessor を作ることでプロパティにアクセスできます。

プロパティ T P があったとすると、 get/set アクセサーにはそれぞれ T get_P()、 void set_P(T value) というメソッドが対応します。 (元のプロパティ名 + get_/set_ 接頭辞。)

using System.Runtime.CompilerServices;

var a = new A();
X.SetValue(a, 1);

Console.WriteLine(a); // A(1)
Console.WriteLine(X.GetValue(a)); // 1

static class X
{
    // Value プロパティの get アクセサーは get_Value。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "get_Value")]
    public static extern int GetValue(A a);

    // Value プロパティの set アクセサーは set_Value。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "set_Value")]
    public static extern void SetValue(A a, int value);
}

class A
{
    private int Value{ get; set; }
    public override string ToString() => $"A({Value})";
}

ちなみにこの「プロパティ名 + get_/set_ 接頭辞」ルールは C# の言語仕様で決まっています。 少なくとも C# コンパイラーで作ったプロパティの場合は必ずこのルールに基づくメソッド名になっています。 (IL アセンブラーを使えばこのルールを破れるはずですが、そんなことをやっている人は見たことがありません。)

インデクサー

プロパティ同様です。 C# の仕様上、インデクサーからは get_Item / set_Item というメソッドが作られているはずなので、これを経由してアクセスします。

using System.Runtime.CompilerServices;

var a = new A(2);
X.SetValue(a, 0, 1);
X.SetValue(a, 1, -1);

Console.WriteLine(a); // A([1, -1])
Console.WriteLine(X.GetValue(a, 0)); // 1
Console.WriteLine(X.GetValue(a, 1)); // -1

static class X
{
    // インデクサーの get アクセサーは get_Item。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "get_Item")]
    public static extern int GetValue(A a, int i);

    // インデクサーの set アクセサーは set_Item。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "set_Item")]
    public static extern void SetValue(A a, int i, int value);
}

class A(int length)
{
    private readonly int[] _items = new int[length];
    private int this[int i]{ get => _items[i]; set => _items[i] = value; }
    public override string ToString() => $"A([{string.Join(", ", _items)}])";
}

(ちなみにこの Item の部分は IndexerName 属性を使って変更できたりします。 実際、string 型のインデクサーは Chars という名前です。 この場合、作られているメソッドの名前も get_Chars です。)

演算子

C# のユーザー定義の演算子は public でないといけない仕様なので、わざわざ UnsafeAccessor を使う場面はより一層少ないですが、一応触れておきます。 (後述する型自体が internal な場合に対して使えなくはないです。)

ユーザー定義の演算子も、内部的にはただのメソッドになります。 + 演算子の場合は op_Addition など、演算子ごとに名前が決まっています。 (参考: 演算子とメソッド名の対応関係)

using System.Runtime.CompilerServices;

var a = new A(1);

X.Add(a, 1); // a += 1;

Console.WriteLine(a); // A(2)

a = X.Add(null, a, 1); // a = a + 1;

Console.WriteLine(a); // A(3)

static class X
{
    // + は op_Addition。
    // 静的メソッドなのでダミーの第1引数が必要。
    [UnsafeAccessor(UnsafeAccessorKind.StaticMethod, Name = "op_Addition")]
    public static extern A Add(A? _, A a, int x);

    // += は op_AdditionAssignment。
    [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "op_AdditionAssignment")]
    public static extern void Add(A a, int x);
}

class A(int value)
{
    private int _value = value;

    public static A operator +(A a, int x) => new(a._value + x);

    public void operator +=(int x) => _value += x;

    public override string ToString() => $"A({_value})";
}

拡張メンバーを UnsafeAccessor にする

UnsafeAccessor の「静的メソッドにして第1引数を足す」という仕様が拡張メソッドと相性がよく、 拡張メソッドをそのまま UnsafeAccessor にすることができます。

using System.Runtime.CompilerServices;

var a = new A(1);

// 拡張メソッド X.Add(A, int) を通して private な A.Add(int) を呼ぶ。
a.Add(1);

Console.WriteLine(a); // A(2)

static class X
{
    [UnsafeAccessor(UnsafeAccessorKind.Method)]
    public static extern void Add(this A a, int x);
}

class A(int value)
{
    private int Value { get; set; } = value;
    private void Add(int x) => Value += x;
    public override string ToString() => $"A({Value})";
}

これは C# 14 で入る extension ブロック形式の拡張メンバーでもできて、 以下のような書き方で UnsafeAccessor を書けたりします。

using System.Runtime.CompilerServices;

var a = new A(1);

// 拡張メソッド X.Add を経由して、private な A.Add を呼ぶ。
a.Add(1);

Console.WriteLine(a); // A(2)

// 拡張プロパティ X.Value を経由して、private な A.Value を取得・設定する。
a.Value = 3;
Console.WriteLine(a.Value); // 3

static class X
{
    extension(A a)
    {
        // コンパイル結果は void Add(this A, int x) と一緒。
        // そのまま UnsafeAccessor にできる。
        [UnsafeAccessor(UnsafeAccessorKind.Method)]
        public extern void Add(int x);

        // 拡張プロパティも通常のプロパティと同じ get_ / set_ という名前でメソッドを作る仕様で、
        // int get_Value(A) / void set_Value(A, int) というメソッドができてる。
        // 属性も伝搬されてて、 A.Value の UnsafeAccessor にできる。
        public extern int Value
        {
            [UnsafeAccessor(UnsafeAccessorKind.Method)]
            get;

            [UnsafeAccessor(UnsafeAccessorKind.Method)]
            set;
        }
    }
}

class A(int value)
{
    private int Value { get; set; } = value;
    private void Add(int x) => Value += x;
    public override string ToString() => $"A({Value})";
}

ジェネリックな型やメンバーへのアクセス

.NET 9 からはジェネリックな型に対して UnsafeAccessor を書けるようになりました。 型引数は以下のように「型は型に、メソッドはメソッドに」というルールで書けば大丈夫です。

using System.Runtime.CompilerServices;

var a = new A<int>(1);

X<int>.M(a); // 1
X<int>.M(a, "abc"); // 1 abc

// 型の型引数は型に。
// A<T> の T はここに書く。
static class X<T>
{
    [UnsafeAccessor(UnsafeAccessorKind.Method)]
    public static extern void M(A<T> a);

    // メソッドの型引数はメソッドに。
    // A<T>.M<U> の U はここに書く。
    [UnsafeAccessor(UnsafeAccessorKind.Method)]
    public static extern void M<U>(A<T> a, U x);
}

class A<T>(T value)
{
    private void M() => Console.WriteLine(value);
    private void M<U>(U x) => Console.WriteLine($"{value} {x}");
}

型引数の付け方は制限がかかっていて、 上記の例とは違う書き方、 例えば「クラス X にメソッド M<T> や M<T, U> を書く」みたいなことをすると実行時エラーになります。

型自体が internal な場合

.NET 10 から「型自体が internal で参照できない」という場合に対して UnsafeAccessor を使う手段が提供されるようになりました。

これまでの例で A 型の引数や戻り値を書いていた場所をとりあえず object 型にして、 その代わり、引数・戻り値に UnsafeAccessorType 属性を付けます。 UnsafeAccessorType 属性の引数に文字列で型名を書くことで、internal な型を参照できます。

例えばまず、ClassLibrary1 という名前のプロジェクトに以下のようなクラスを用意したとします。

namespace Lib;

// ClassLibrary1 というプロジェクト内にあるものとする。
internal class A
{
    private int _value;
    public override string ToString() => $"A({_value})";
}

この型を別プロジェクトから参照するには以下のように書きます。

using System.Runtime.CompilerServices;

var a = X.CreateA(); // var a = new A();
X._value(a) = 1;   // a._value = 1;

Console.WriteLine(a);

static class X
{
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    [return: UnsafeAccessorType("Lib.A, ClassLibrary1")]
    public static extern object CreateA();

    [UnsafeAccessor(UnsafeAccessorKind.Field)]
    public static extern ref int _value([UnsafeAccessorType("Lib.A, ClassLibrary1")] object @this);
}

型名はフルネーム(Lib.A)で書き、 , でつなげて アセンブリ名(通常、プロジェクト名がそのままアセンブリ名になります。今回は ClassLibrary1)を書きます。

UnsafeAccessorType 属性は拡張メンバーでも使えます。 (object 型インスタンスに対する拡張になってしまって誤用が怖いという問題はあり。)

using System.Runtime.CompilerServices;

var a = X.CreateA(); // var a = new A();

// 拡張メソッド呼び。
a._value() = 1;   // a._value = 1;

Console.WriteLine(a);

// 拡張プロパティ呼び。
a.Value = 2;   // a._value = 2;

Console.WriteLine(a);

static class X
{
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    [return: UnsafeAccessorType("Lib.A, ClassLibrary1")]
    public static extern object CreateA();

    // 拡張メソッドでも使える。
    [UnsafeAccessor(UnsafeAccessorKind.Field)]
    public static extern ref int _value([UnsafeAccessorType("Lib.A, ClassLibrary1")] this object @this);

    // extension ブロックでも使える。
    extension([UnsafeAccessorType("Lib.A, ClassLibrary1")] object @this)
    {
        public extern ref int Value
        {
            [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "_value")]
            get;
        }
    }
}

ジェネリックな型の場合は `1 みたいな語尾をつける必要があります。 例として ClassLibrary1 側のクラス A を以下のようにジェネリック クラスにしてみます。

namespace Lib;

// ClassLibrary1 というプロジェクト内にあるものとする。
internal class A<T>
{
    private T _value;
    public override string ToString() => $"A({_value})";
}

これを参照するためには以下のような書き方になります。

using System.Runtime.CompilerServices;

var a = X<int>.CreateA(); // var a = new A();
X<int>._value(a) = 1;   // a._value = 1;

Console.WriteLine(a);

static class X<T>
{
    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
    [return: UnsafeAccessorType("Lib.A`1, ClassLibrary1")]
    public static extern object CreateA();

    [UnsafeAccessor(UnsafeAccessorKind.Field)]
    public static extern ref T _value([UnsafeAccessorType("Lib.A`1, ClassLibrary1")] object @this);
}

UnsafeAccessor 定義側のクラス(この例だと X<T>)の書き方は前節と同じです。 一方、 UnsafeAccessorType 属性に渡す型名は、 Type 型 の FullName プロパティで得られる文字列と同じです。 A<T> であれば Lib.A`1 になります。 ` はバッククオートで、日本語キーボードの場合 shift + @ で入力するやつです。 また、1 の部分は型引数の個数で、 これが A<T1, T2> の場合だと `2、 A<T1, T2, T3> の場合だと `3 になります。

コンパイラー生成のフィールド

ここからは C# の言語仕様にはない話になります。 (現在の Roslyn と呼ばれる C# コンパイラーの実装ではそうなっているけども、 将来もずっと同じ実装が続くかとかの保証はない話です。)

自動プロパティ (field キーワードを使ったものも含む)からはフィールドが生成されています。 現在の Roslyn の場合、このフィールドの命名ルールは「プロパティ P に対して <P>k__BackingField」みたいになります。 この挙動を使えばプロパティのバッキング フィールドを読み書きすることができます。

using System.Runtime.CompilerServices;

var a = new A();
X.RefValue(a) = 1;

Console.WriteLine(a); // A(1)

static class X
{
    // これで Value プロパティのバッキング フィールドを参照できる。
    [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "<Value>k__BackingField")]
    public static extern ref int RefValue(A a);
}

class A
{
    public int Value { get; set; }
    public override string ToString() => $"A({Value})";
}

また、プライマリ コンストラクター引数のキャプチャで作られるフィールドは、引数 x に対して <x>P という名前になります。

using System.Runtime.CompilerServices;

var a = new A(0);
X.RefValue(a) = 1; // 書き換え。

Console.WriteLine(a); // A(1)

static class X
{
    // プライマリ コンストラクター引数から作られるフィールドは <>P。
    [UnsafeAccessor(UnsafeAccessorKind.Field, Name = "<value>P")]
    public static extern ref int RefValue(A a);
}

class A(int value)
{
    public override string ToString() => $"A({value})";
}

ここでは、C# の言語バージョンを明示的に指定する方法について説明します。

SDK バージョンと言語バージョン

最新の C# の機能を使うためには、コンパイラー自体も最新のものを使う必要があります。 コンパイラーは .NET SDK に付属しているので、 最新バージョンの .NET SDK をインストールすると、C# コンパイラーも最新のものになります。 なので、最新の .NET SDK を使えば、C# も最新のものが使えます。

一方で、その逆は話が違って、新しいコンパイラーでもC# の「言語バージョン」をオプション指定することで、古い C# のまま維持することができます

例えば、以下のようなコード(.NET 10 以降でだけ実行できます)を書いたとします。

#:property LangVersion=11.0

// C# 12 からの機能なので、C# 11 ではエラーになる。
int[] array = [1, 2, 3];

.NET 10 だと C# の規定のバージョンは 14 になりますが、 LangVersion というものを明示しているので、このコードは C# 11 扱いでコンパイルされます。 このコードはあえて C# 12 の機能を使っているので、当然、エラーになります。

D:\src\app1> dotnet .\app1.cs
D:\src\app1\app1.cs(4,15): error CS9058: 機能 'コレクション式' は C# 11.0 では使用できません。12.0 以上の言語バージョンをお使いください。

ビルドに失敗しました。ビルド エラーを修正して、もう一度実行してください。

特に指定がない場合、基本的には「ターゲット フレームワークで指定した .NET と同世代のバージョン」になります (ターゲット フレームワークについては後述)。 例えば、 .NET 9 を使うと C# 13 になりますし、 .NET 10 を使うと C# 14 になります。

基本的に C# は破壊的変更を好まない言語^※なので、古いバージョンを維持するメリットはあまりありません。 ただ、「チーム内で .NET 10 SDK を入れた人と、9 のままの人がいる」みたいな状況では、 言語バージョンを明記しておかないと「ある人は C# 14 が使えて、他のある人は 13 のまま」みたいなことになります。 そのため、チーム内で C# のバージョンをそろえるといった意図で、バージョン明示をすることがあります。

^※ かつての C# は破壊的変更をほとんどしませんでしたし、 基準が緩くなった今でも悪影響よりもメリットが大幅に上回る場合にのみ破壊的変更を認めています。

ターゲット フレームワーク

C# は .NET 上で動く言語です。 C# で書いたプログラムを動かす環境には .NET Runtime をインストールする必要があります。

どのバージョンの .NET Runtime を対象にプログラムを動かすかを指定するのがターゲット フレームワーク(target framework) で、 プロジェクト設定上 TargetFramework という項目で指定します。 例えば、TargetFramework に net8.0 を指定すると、.NET 8.0 以降の Runtime で動くプログラムになります。

逆は真ではなく、新機能を使ったプログラムは古い .NET Runtime では動かなくなります。 互換ライブラリみたいなものを導入することで過去の .NET Runtime で新機能を動かせる場合もありますが、 公式がサポートするものではなく、 あくまで自己責任での導入になります(動かないことに文句を言われても公式は困る)。

また、一部の機能は .NET Runtime の特別なサポートが必要で、 古い環境ではどうやっても動かせないものもあります。 例えば以下のようなものがあります。

• ジェネリクス は .NET Framework 2.0 (2005年リリース)以降が必須
• インターフェイスのデフォルト実装 は .NET Core 3.0 (2019年リリース)以降が必須

そもそも言語機能に限らず、標準ライブラリとして何が使えるかによってプログラムの書き方は全然変わってきますし、 「どの .NET で動かしたいか」の指定は欠かせません。 これをターゲット フレームワーク(target framework)と言います。

ターゲットフレームワークにはモニカー(moniker: あだ名)と呼ばれる短縮名みたいなものが振られていて、 例えば以下のように書きます。

補足: .NET Framework は当初 Windows のみで動いた初期の .NET 実行環境です。 .NET Core はマルチプラットフォームで動くように作り直したもので、 バージョン番号を振りなおしたので「.NET Framework 4.8 よりも .NET Core 3.0 の方が新しい」みたいなことになっています。 .NET は単に名称の変更で中身としては .NET Core の系譜で、バージョン番号は .NET Framework 4.8 よりも .NET Core 3.0 よりも新しく見えるよう、5 から開始しています。 負の遺産として、「net10 は .NET Framework 1.0 を指して、net10.0 は .NET 10 を指す」みたいなことになっているので注意が必要です。

詳しくは公式ドキュメントである以下のページを参照してください。

• ターゲット フレームワーク

言語バージョンの指定方法

C# コンパイラーのオプションで、言語バージョンを明示的に指定することができます。 言語バージョンは、Visual Studio 上で行う場合、プロジェクトのプロパティを開いて、以下の場所から設定できます。 (※ ちょっと古いバージョンのスクショになります。最新バージョンでもプロジェクトのプロパティで設定できますが、UI は変わっています。)

プロジェクト ファイル(拡張子が csproj のファイル)を直接書き換える場合、PropertyGroupの下にLangVersionタグを書きます(タグ内に書けるオプションの種類は後述します)。

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>netcoreapp2.2</TargetFrameworks>
    <LangVersion>11</LangVersion>
  </PropertyGroup>

</Project>

.NET 10 以降であればファイル ベース実行という機能を使って C# ファイル中で直接 LangVersion 指定することもできます。

#:property LangVersion=11.0

Console.WriteLine("C# 11");

古くは(.NET Framework の時代では)、csc というコマンド名で C# コンパイラーを直接呼び出していました。 この csc を直接使う場合には、-langversionオプションを指定します (書けるオプションは上記の LangVersion タグと同じ)。

csc -langversion:11 app1.cs

LangVersion には以下の2通りのオプション指定ができます。

• 7.0 など、バージョン番号を直接指定
• preview など、後述するいくつかの文字列

前者の番号指定では、メジャー バージョンであれば 7 などというように、小数点以下は省略可能です。 (※ マイナー バージョンがあったのは 7 世代の 7.1, 7.2, 7.3 だけでそれ以降はないので、 実質的には整数値で 8, 9, 10, ... などと書くだけで充分です。)

後者は、preview、latest、latestMajor、default の4種類があります(大文字・小文字は区別しません)が、 今となっては preview 以外の利用はあまり推奨しません。 バージョン番号を明示するか、何も指定しないかのどちらかがおすすめです。

何も指定しないときの挙動

LangVersion を指定しない場合、基本的には「TargetFramework に応じて自動選択」になります。 .NET 9 (net9.0)なら C# 13、 .NET 10 (net10.0)なら C# 14 というように、 同世代の言語バージョンが選ばれます。

公式にサポートされているのはこの「同世代の組み合わせ」なので、 特に理由がない限りには「何も指定しない」をお勧めします。

最近では、「TargetFramework と C# 言語バージョンをそろえてアップデートした場合だけ破壊的変更の影響を避けれる」みたいなことを認める方針が取られたりしています。 以下のブログのように、「C# 14 では結構大きな破壊的変更があるものの、同時に .NET 10 にした場合だけエラーにならない」みたいなことがあります。

• C# 14 の破壊的変更点(First-class Span)

バージョン番号の明示

ある程度分かっている人向けですが、C# の言語バージョンを明示することができます。 主に以下のような場面で使います。

• プログラムを動かす環境には手を入れづらく TargetFramework は変えられないが、開発環境は自由にできるので .NET SDK は最新にでき、C# も新しい言語バージョンが使える
• TargetFramework を複数指定しているが、それぞれ異なる言語バージョンが選ばれるのは困る

(後述しますが、latest よりもバージョン明示の方をお勧めします。)

例えば以下のようなコードをライブラリ配布することを考えます。

public class Class1
{
    private static string _rawData = "example data some words with space separation";

    // field キーワードを使いたいから C# 14 にしたい。
    public IEnumerable<KeyValuePair<int, int>> Counts => field ??= GetCounts(_rawData.Split(' '));

    private static IEnumerable<KeyValuePair<int, int>> GetCounts(IEnumerable<string> items)
    {
#if NET9_0_OR_GREATER
        // .NET 9 以降ならこれが速い。
        return items.CountBy(x => x.Length);
#else
        // .NET 8 以前でも動くようにしたいから残すけど、
        // このコードだと長いしだいぶ遅い。
        return items.GroupBy(x => x.Length).Select(g => KeyValuePair.Create(g.Key, g.Count()));
#endif
    }
}

このコードには以下のような意図があります。

• 極力多くの人に使ってもらいたいので、極力古い .NET をターゲットにしたい(最低ラインを .NET 5 にする)
• でも、新しい .NET で使う場合には高速になるように最新機能を使いたい(.NET 9 からの新機能を使えるなら使いたい)
• ターゲットによらす、C# の機能は新しいものを使いたい(C# は 14 にしたい)

この意図通りのプロジェクトを書くと以下のようになります。

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

  <PropertyGroup>
    <TargetFrameworks>net9.0;net5.0</TargetFrameworks>
    <LangVersion>14</LangVersion>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

この時 LangVersion を書かないと、 「.NET 5 向けには C# 9、.NET 9 向けには C# 13 でコンパイル」みたいなことになります。 この状態だと、「うっかり C# 13 で書ける気になって書いちゃうけど、実際は C# 9 でないとコンパイルできない」とか、 「C# 9 のときと 13 以降で解釈の違うコードを書いてしまうとどうやってもコンパイルできない」とか、 いろいろな問題を起こす可能性があります。

プレビュー機能の利用

LangVersion に preview を指定すると、正式リリース前の C# の最新機能を先行して試すことができます。

2020年(.NET 5, C# 9 の世代)から、.NET は年に1回(毎年11月に)正式リリース版を出しています。 それとは別に、月に1回程度の頻度でプレビュー版を出していて、 C# の最新機能も少しずつ実装されています。 この最新機能を先行して試したい場合に LangVersion preview を指定します。

後述する latest と同じく、使っている .NET SDK のバージョン依存です。 (TargetFramework が実行環境(どこでプログラムを動かすか)依存なのに対して、これは開発環境依存です。) .NET 9 SDK Preview なら C# 13 (に入る予定の当時の新機能)でしたし、 .NET 10 SDK Preview なら C# 14 (予定)でした。

開発環境依存なのは latest と同じく問題を起こしえるんですが、 そもそも preview で最新の C# 言語機能を試そうという人は「相当詳しい人」のはずなので特に問題視はされません。

その他のバージョン指定

latest、latestMajor、default の3つはおおむね「過去の名残」です。 これから新規プロジェクトを作る場合、あまり利用はお勧めしません。

latest は .NET SDK バージョン依存で最新の C# 言語バージョンになります。 .NET SDK バージョン依存 = 開発環境依存なので、例えば以下のような状況で問題を起こします。

• チーム開発していて、うっかり1人だけ .NET SDK のバージョンを上げてしまった
  • 自動的にその1人だけ C# の言語バージョンが変わる
• CI 環境を更新せず、手元の開発環境だけを更新してしまった
  • 手元ではコンパイルできているのに、GitHub などに Push するとチェックが通らない

こういう問題を避けるため、バージョン未指定にできない場合でも極力、 バージョン番号の明示にした方が安全です。

latestMajor は latest に似ているんですが、メジャー バージョンしか選ばれないというものです。 C# 7.1, 7.2, 7.3 時代の遺物で、 この時代は latest だと 7.1～7.3、latestMajor だと 7.0 になっていました。 当時は .NET Framework から .NET Core への移行期間で、 7.1 や 7. 2 のサポートが間に合っていなかったという開発体制の都合です。 C# 8 以降、マイナー バージョンアップなリリースはないので、今となっては実質 latest と差がありません。

default は意味通りにとらえるなら「未指定時と同じ」になるはずなんですが、以下のような事情で少し複雑です。

• プロジェクト(csproj ファイル)中
  • 未指定は前述のとおり TargetFramework に応じた自動選択
  • <LangVersion>default</LangVersion> は後述のコンパイラー オプションの -langversion:default と同じ意味
    • 結果、-langversion:latest と同じ意味
• C# コンパイラーのオプション
  • 未指定 = -langversion:default = -langversion:latest
  • 開発環境依存の「最新」
  • (ただし、C# 7.1～C# 7.3 の時代に限り、-langversion:default = -langversion:latestMajor)

C# コンパイラー自体にはプロジェクト ファイル(csproj)を解釈する機能がなく、 TargetFramework がわからないのでこういうことになっています。 とりあえず default は使わない方が無難でしょう。

(ちなみに、プロジェクト中で1度設定されてしまった LangVersion も再度 <LangVersion> タグを書くことで上書きできますが、 バージョン未指定挙動にしたい場合は <LangVersion></LangVersion> というように空タグを書きます。 <LangVersion>default</LangVersion> と書いてしまうとここで説明したように latest 挙動になります。)

概要

.NET 10 (C# 14 と同世代)で単独の .cs ファイルだけで C# プログラムを実行できるようになりました。 例えば、app1.cs という名前で保存した C# ファイルを dotnet app1.cs という1コマンドだけで実行できます。 それに伴って、C# 14 で #! と #: (無視ディレクティブ)という機能が追加されています。

(C# 言語の新文法というよりは、C# コンパイラーの1機能という感じのものです。 バージョン的にも C# 14 である必要はなくて、.NET 10 以降付属の C# コンパイラーであれば言語バージョン問わず #! と #: を認識します。)

本項ではこの「単独のファイルでの実行」(ファイル ベース実行)の話と、 C# 14 の #! と #: (無視ディレクティブ)について説明します。

サンプル コード: FileBaseApp

ファイル ベース実行

改めて、 .NET 10 で C# ファイルを直接1コマンドで実行できるようになりました。 例えば、以下の1行だけ書いたファイル app1.cs を用意して、

Console.WriteLine("🐈");

以下のようなコマンドを打つと、この C# ファイルを単独で実行できます。

> dotnet app1.cs
🐈

これはスクリプト実行ではなく、通常の^※脚注 C# 実行になります。 この仕組みをファイル ベース実行(file-based execution) と言い、これを使って書かれた C# プログラムをファイル ベース アプリ(file-based app)と言ったりします。

この機能の追加に伴い、これまでであればプロジェクト (実体は拡張子 .csproj の XML ファイル)に書いていた設定の類を C# 中に直接書けるようになりました。 以下の2つが追加されています。

• #! : いわゆる shebang
• #: : プロジェクト設定の類を書くためのディレクティブで、C# コンパイラーにとっては「単に無視」になる

ちなみに、普通に .csproj ファイルを使って C# プロジェクトをコンパイルする際には、#! や #: があるとコンパイル エラーになります。 ただし、.csproj ファイル中に <Features>FileBasedProgram</Features> オプションを書いておくとコンパイルでき、この場合、#! や #: から始まる行は単に無視されます。 C# コンパイラーからすると「単に無視するもの」なので、無視ディレクティブ(ignored directive)と呼ばれます。

^※ スクリプト実行が「それ専用の構文がいくつかある」状態なのに対して、 ファイル ベース実行は本当に普通の C# です。 スクリプト実行みたいに「1行1行追加で実行」みたいなことができない一方で、 「コードが多くなってきたから .csproj 形式の通常の C# プロジェクトに切り替えたい」というときにスムーズに移行できます。 移行を自動化するための dotnet project convert というコマンドも用意されています。

shebang

#! (通称 shebang。 sharp + bang が由来)は主に Unix のスクリプト言語で使われるもので、 ソースコードの先頭にこの記号から始まる行を入れると「何を使ってこのスクリプトを実行するか」を指定できます。

C# 14 で、C# にもこの1行を入れることができるようになりました。 例えば前節の app1.cs ファイルにちょっと手を加えて以下のような内容にします。

#!/usr/bin/env dotnet
Console.WriteLine("🐈");

このファイルは bash などの Unix 系シェルで ./app1.cs みたいに直接実行できるようになります。 (実行権限が必要なので、最初に1回 chmod +x などの操作が必要。)

$ ls
app1.cs
$ chmod +x app1.cs
$ ./app1.cs
🐈

用途的に、#! はファイルの先頭にのみ書けます。 #! の前には改行はもちろんのこと、空白文字や BOM を入れることもできません。

: 無視ディレクティブ

#: から始まる行は dotnet コマンドがプロジェクト設定として解釈するために使い、 C# 上は単に無視されます。

例えば、以下のような .cs ファイルをファイル ベース実行するのは、

#:property InvariantGlobalization=true
Console.WriteLine(new DateTime(2000, 1, 2, 3, 4, 5));

以下のような2ファイルを使って既存の .csproj ベースの dotnet run をするのとほぼ同じ意味になります。

app1.csproj:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    </PropertyGroup>
    <InvariantGlobalization>true</InvariantGlobalization>
</Project>

app1.cs:

Console.WriteLine(new DateTime(2000, 1, 2, 3, 4, 5));

(ちなみに InvariantGlobalization を指定すると書式が北米フォーマットになるので、出力される結果は 01/02/2000 03:04:05 (MM/dd/yyyy)になります。)

#: で始まる無視ディレクティブは shebang とコメントを除いて、ファイルの先頭に置く必要があります。 例えば以下のコードでは、5行目(LangVersion の行)は問題なく、 9行目(ImplicitUsings の行)でだけコンパイル エラーを起こします。

#!/usr/bin/env dotnet

// コメントはあってもいい。

#:property LangVersion=13

Console.WriteLine("🐈");

#:property ImplicitUsings=disable

.NET 10 時点で、dotnet コマンドは以下のディレクティブを解釈できます。

sdk ディレクティブ

#:sdk は、 .csproj では <Project Sdk="Identifier"> と書いていたものです。 省略した場合は Microsoft.NET.Sdk (ライブラリやコンソール プログラムで使う一番シンブルな SDK)になります。 実質的には「ASP.NET プログラムを書きたいときに Microsoft.NET.Sdk.Web にするもの」です。

例えば、以下のようなコードで ASP.NET なコードをファイル ベース実行できます。

#:sdk Microsoft.NET.Sdk.Web

var app = WebApplication.CreateBuilder(args).Build();
app.MapGet("/", () => "Hello World!");
app.Run();

property ディレクティブ

#:property は、 .csproj では <PropertyGroup> の子要素として書いていたものです。 .csproj の <Tag>Value</Tag> 要素が #:property Tag=Value という書き方になります。

無視ディレクティブの節の冒頭の InvariantGlobalization の例もこれになります。 その他、例えば unsafe ブロックはオプションを指定しないと使えない構文なわけですが、以下のように書くことでそのオプションを指定できます。

#:property AllowUnsafeBlocks=true

// unsafe ブロックはオプションをつけないと使えない構文。
unsafe
{
    int n = 1;
    int* pn = &n;
    Console.WriteLine($"{(nint)pn:x}");
}

package ディレクティブ

#:package は、 .csproj では <PackageReference> 要素で書いていたものです。 .csproj の <PackageReference Include="PackageName" Version="x.y.z" /> 要素が #:package PackageName@x.y.z という書き方になります。

例として Microsoft.CodeAnalysis.CSharp パッケージ(C# 中から C# コンパイラー自身を呼ぶためのライブラリ)を参照したコードを書くと以下のようになります。 (ちなみに、4.14.0 は C# 13 当時のバージョンです。)

#:package Microsoft.CodeAnalysis.CSharp@4.14.0

using Microsoft.CodeAnalysis.CSharp;

var tree = CSharpSyntaxTree.ParseText("class Class1;");
var root = await tree.GetRootAsync();
Console.WriteLine(root.GetFirstToken().Text);

project ディレクティブ

#:project は、 .csproj では <ProjectReference> 要素で書いていたものです。 .csproj の <ProjectReference Include="path" /> 要素が #:project path という書き方になります。

例えば以下のような書き方で、.cs のある場所からの相対パスで Lib/Lib.csproj プロジェクトを参照できます。

#:project Lib/Lib.csproj
Console.WriteLine(Lib.Class1.Name);

未対応のディレクティブ

未対応の #: ディレクティブは、ファイル ベース実行するとエラーを起こします。 例えば以下のようなコードを書いて dotnet app1.cs コマンド実行すると、 「認識されないディレクティブ ' aaa' です。」というエラーが出ます。

#:aaa
Console.WriteLine("🐈");

ちなみにこのエラーを出すのはあくまで dotnet コマンドであって、 C# コンパイラー的には「#: で始まるディレクティブはすべて無視」という挙動になっています。 <Features>FileBasedProgram</Features> オプションを書いた .csproj ファイルを用意して、 旧来方式でコンパイルすると #:aaa の行のエラーは出ません。

執筆予定: C# 14.0 トラッキング issue

field キーワード

field という文脈キーワードが追加されました。 プロパティの get/set の中に field と書くと、 バッキング フィールドを生成した上で、そのフィールドの読み書きができます。 例えば前述の例を field を使って書き直すと以下のようになります。

using System.ComponentModel;
using System.Diagnostics.CodeAnalysis;

class FieldBackedProperties : INotifyPropertyChanged
{
    // 遅延初期化: 最初のプロパティ アクセス時にインスタンスを生成。
    public string X => field ??= "";

    // set 側だけ null 許容(get 側で ?? で非 null 化)。
    [AllowNull]
    public string Y
    {
        get => field ?? "";
        set;
    }

    // INotifyPropertyChanged の実装: get 側だけ素通し。
    public string? Z
    {
        get;
        set
        {
            if (field != value)
            {
                field = value;
                PropertyChanged?.Invoke(this, new(nameof(Z)));
            }
        }
    }

    public event PropertyChangedEventHandler? PropertyChanged;
}

詳しくは「field キーワード」で説明します。

null 条件代入

代入演算の左側で ?. や ?[] を書くことで「null じゃないときだけ代入」ができるようになりました。 これを null 条件代入(null conditional assignment)といいます。

static void M(A? a)
{
    // if (a != null) a.X = 10; とほぼ同じ。
    a?.X = 10;

    // if (a != null) a[0] = 10; とほぼ同じ。
    a?[0] = 10;

    // if (a != null) a.Event += () => { }; とほぼ同じ。
    a?.Event += () => { };
}

class A
{
    public int X { get; set; }

    public int this[int index]
    {
        get => 0;
        set { }
    }

    public event Action? Event;
}

詳しくは「null の取り扱い - null じゃないときだけ代入」で説明します。

First-class Span

Span<T>/ReadOnlySpan<T> 構造体を言語構文的に特別扱いするようなりました。

詳しくは「First-class Span」で説明します。

複合代入演算子のオーバーロード

複合代入演算子を直接オーバーロードできるようになりました。

record struct X(int Value)
{
    public void operator +=(int value) => Value += value;
    public void operator -=(int value) => Value -= value;
    public void operator *=(int value) => Value *= value;
    public void operator /=(int value) => Value /= value;
    public void operator %=(int value) => Value %= value;
    public void operator &=(int value) => Value &= value;
    public void operator |=(int value) => Value |= value;
    public void operator ^=(int value) => Value ^= value;
    public void operator <<=(int value) => Value <<= value;
    public void operator >>=(int value) => Value >>= value;
    public void operator >>>=(int value) => Value >>>= value;
    public void operator checked +=(int value) { checked { Value += value; }; }
    public void operator checked -=(int value) { checked { Value += value; }; }
    public void operator checked *=(int value) { checked { Value += value; }; }
    public void operator checked /=(int value) { checked { Value += value; }; }
    public void operator ++() => Value++;
    public void operator --() => Value--;
    public void operator checked ++() { checked { Value++; } }
    public void operator checked --() { checked { Value--; } }
}

以前から二項演算子(+ など)のオーバーロードをすることで、それに対応する複合代入(+= など)ができていましたが、この実装だとコピーのコストが不可避でした。 複合代入演算子を直接オーバーロードすることでこのコストを削減できます。

詳しくは「複合代入演算子のオーバーロード」で説明します。

修飾子付きの引数の型名省略

ref や out などの修飾子が必須の引数でも、ラムダ式引数の型名を省略できるようになりました。

// C# 13 までは型名省略不可で、(string text, out int result) のように書く必要があった。
TryParse<int> m = (text, out result) => { result = 0; return true; };

delegate bool TryParse<T>(string text, out T result);

詳しくは「修飾子付きの引数の型名省略」で説明します。

その他

部分イベントと部分コンストラクター

部分プロパティ (C# 13)に続いて、 C# 14 ではイベントとコンストラクターも部分定義できるようになりました。

// 元コード(手書き想定)。
partial class PartialClass
{
    // 部分イベント。
    public partial event Action<int>? PartialEvent;

    // 部分コンストラクター。
    public partial PartialClass();
}

// コード生成で作ってもらう前提のコード。
partial class PartialClass
{
    private Action<int>? _partialEvent;
    public partial event Action<int>? PartialEvent
    {
        add => _partialEvent += value;
        remove => _partialEvent -= value;
    }

    public partial PartialClass() { }
}

unbound な型に対する nameof

T<> みたいに型引数を埋めていないジェネリック型(これを unbound (未束縛)とか open (開きっぱなし) な型といいます)に対して nameof 演算子を使えるようになりました。

Console.WriteLine(nameof(List<>)); // "List"
Console.WriteLine(nameof(Dictionary<,>.Keys)); // "Keys"
Console.WriteLine(nameof(List<>.Enumerator.MoveNext)); // "MoveNext"

詳しくは「unbound な型に対する nameof」で説明します。

ファイル ベース実行

.NET 10 (C# 14 と同世代)で単独の .cs ファイルだけで C# プログラムを実行できるようになりました。

それに伴って、C# 的にも #! と #: (無視ディレクティブ)という機能が追加されています。 例えば以下のようなコードが書けて、 Unix 系シェルの shebang を書けたり、これまでであればプロジェクト(.csproj ファイル中)に書いていた設定の類を C# ソースコード中に書けるようになっています。

#!/usr/bin/env dotnet
#:sdk Microsoft.NET.Sdk.Web

var app = WebApplication.CreateBuilder(args).Build();
app.MapGet("/", () => "Hello World!");
app.Run();

詳しくは「ファイル ベース実行」で説明します。

関数で説明しましたが、 C# では関数メンバーに対して、 同名で引数リストだけが違う物を定義でき、これをオーバーロードと呼びます。

同名の関数がいくつかあるので、M(0) などと書いた時、実際には「どのMが呼ばれるか」という検索処理が必要になります。 このような同名の関数のうちどれを呼ぶか探す処理をオーバーロード解決(overload resolution)と呼びます。

本項では、C# がどういうルールでオーバーロード解決を行っているのかについて説明して行きます。

「より一致度の高いものを選ぶ」ルール

引数の型

• ぴったり一致する型
• ジェネリックな型
• 親クラス
  • 多段に派生している場合、近い方ほど優先
• 暗黙的に変換できる型
  • その型が実装しているインターフェイス
  • ユーザー定義の型変換がある場合
• object

型変換なしで渡せるものほど「一致」、 いろんな型を受け付けるものほど「不一致」です。

例えば以下のようなメソッド M を書いた場合、 上の方に書いたものほど優先的に呼ばれます。

using System;

// A → B → C の型階層
// IDisposable インターフェイスを実装
// C には int への暗黙的型変換あり
class A : IDisposable { public void Dispose() { } }
class B : A, IDisposable { }
class C : B, IDisposable
{
    public static implicit operator int(C x) => 0;
}

class Program
{
    static void Main()
    {
        // M のオーバーロードがいくつかある中、C を引数にして呼び出す
        M(new C());
    }

    // 上から順に候補になる。
    // 上の方を消さないと、下の方が呼ばれることはない。

    // 「そのもの」が当然1番一致度高い
    static void M(C x) => Console.WriteLine("C");

    // 次がジェネリックなやつ。型変換が要らないので一致度が高いという扱い。
    static void M<T>(T x) => Console.WriteLine("generic");

    // 基底クラスは、階層が近い方が優先。この場合 B が先で、A が後
    static void M(B x) => Console.WriteLine("B");

    static void M(A x) => Console.WriteLine("A");

    // 次に、インターフェイス、暗黙的型変換が同率。
    // (構造体の時の ValueType と違って、クラスは明確に基底クラスが上。)
    // この2つが同時に候補になってると ambiguous エラー
    static void M(IDisposable x) => Console.WriteLine("IDisposable");
    static void M(int x) => Console.WriteLine("int");

    // 最後が object。
    static void M(object x) => Console.WriteLine("object");
}

型変換に関しては、候補が複数ある場合は、どちらを呼ぶべきか不明瞭なためコンパイル エラーになります。 例えば以下のコードはコンパイルできません。

using System;

// インターフェイス実装とユーザー定義の型変換を持つ
class A : IDisposable
{
    public void Dispose() { }
    public static implicit operator int(A x) => 0;
}

class Program
{
    static void M(IDisposable x) => Console.WriteLine("IDisposable");
    static void M(int x) => Console.WriteLine("int");

    static void Main()
    {
        // インターフェイスへの変換と、ユーザー定義の型変換は同列
        // どちらを呼ぶべきか、このコードでは解決できない
        M(new A());

        // 明示的にキャストを書けば大丈夫
        M((IDisposable)new A());
        M((int)new A());
    }
}

型の派生に関してはクラスのみです。 C# では、任意の値型は System.ValueType クラスから派生、任意の列挙型はSystem.Enumクラスから派生しているように振る舞いますが、 これらはあくまで「それっぽく振る舞うようにコンパイラーが特殊対応している」というだけで、 実際には型変換の一種です。 そのため、以下のようなコードはコンパイル エラーになります。

using System;

struct S : IDisposable
{
    public void Dispose() { }
}

class Program
{
    static void Main()
    {
        // S は ValueType から派生しているかのように振る舞うものの、これはあくまで ValueType への型変換になる
        // インターフェイスへの変換と同列なので、以下の呼び出しは不明瞭
        M(new S());
    }

    static void M(IDisposable x) => Console.WriteLine("IDisposable");
    static void M(ValueType x) => Console.WriteLine("ValueType");
}

ジェネリック メソッド

using System;

class Program
{
    static void Main()
    {
        // M(string) の方が呼ばれる
        M("abc");

        // M<T>(string) の方が呼ばれる
        M<int>("abc");
    }

    static void M(string x) => Console.WriteLine("M");
    static void M<T>(string x) => Console.WriteLine("M<T>");
}

オプション引数・可変長引数

C# にはオプション引数と可変長引数という、引数を省略できる仕組みが2つあります。 この場合、以下のリストの上の方ほど「一致度が高い」と判断されます。

• 省略なくぴったり引数の数が一致しているもの
• オプション引数による省略
• 可変長引数による省略

using System;

class Program
{
    static void Main()
    {
        M();
    }

    // これが最優先
    static void M() => Console.WriteLine("void");

    // 次がこれ。既定値を与えたもの
    static void M(int x = 0) => Console.WriteLine("int x = 0");

    // 最後がこれ。params
    static void M(params int[] x) => Console.WriteLine("params int[]");
}

インスタンス メソッド優先

C# には拡張メソッドという、 インスタンス メソッドと同じ書き方で静的メソッドを呼べます。 正確にはオーバーロードとは言わないんですが、 インスタンス メソッドと同名の拡張メソッドも定義できるので、 オーバーロードと同種の「解決」が必要になります。

この場合、インスタンス メソッドの方が優先です。 拡張メソッドの方を呼びたければ、本来の静的メソッドとして呼ぶ必要があります。

using System;

class A
{
    public void M() => Console.WriteLine("instance");
}

static class Extensions
{
    public static void M(this A a) => Console.WriteLine("extension");
}

class Program
{
    static void Main()
    {
        // instance の方が呼ばれる
        new A().M();

        // A 自身が M を持っている以上、↑の書き方で拡張メソッドの方は呼べない
        // 以下のように、普通に静的メソッドとして呼ぶ必要がある
        Extensions.M(new A());
    }
}

型推論とオーバーロード解決

• ラムダ式
  • どのデリゲート型かの決定
  • デリゲートと、式ツリー
• 文字列補間
• default 式

推論に推論を重ねることになるので、これらの型を引数にした場合、オーバーロード解決ができない場合が増えます。

using System;

// 引数が完全に一致しているデリゲート型を2個用意
delegate int A(int x);
delegate int B(int x);

class Program
{
    static void Main()
    {
        // 2個以上候補があるときに default は使えない
        M(default);

        // 型推論とはちょっと違うものの、null (型がない。どの型にでも代入可)でも同様
        M(null);

        // 型指定ありの default なら大丈夫
        M(default(A));

        // A なのか B なのか区別がつかない
        M(x => x);

        // キャストがあれば大丈夫
        // new でも可
        M((A)(x => x));
        M(new A(x => x));
    }

    static void M(A x) => Console.WriteLine("A");
    static void M(B x) => Console.WriteLine("B");
}

文字列補完では、string型で受け取る場合とFormattableStringで受け取る場合で異なる挙動になりますが、 varを使った暗黙的変数宣言では自動的にstring扱いされます。 そのため、オーバーロード解決でも特にキャストがない場合、stringが優先されます。

using System;

class Program
{
    static void Main()
    {
        var (a, b) = (1, 2);

        // M(string) の方が呼ばれる
        M($"{a}, {b}");

        // こう書けば M(FormattableString) の方
        M((FormattableString)$"{a}, {b}");
    }

    static void M(string x) => Console.WriteLine("string");
    static void M(FormattableString x) => Console.WriteLine("FormattableString");
}

同様に、ラムダ式は、デリゲート型で受け取る場合と式ツリーで受け取る場合で異なる挙動になります。 こちらは推論は効かず、オーバーロード解決もできなくなります。

using System;
using System.Linq.Expressions;

class Program
{
    static void Main()
    {
        M(x => x);
    }

    static void M(Func<int, int> f) => Console.WriteLine("Func");
    static void M(Expression<Func<int, int>> f) => Console.WriteLine("Expression");
}

ただし、次節で説明しますが、ラムダ式の型推論は結構優秀で、 ちゃんと推論が働きつつ、オーバーロード解決できる場合も多いです。

ラムダ式

using System;

class Program
{
    static void Main()
    {
        // x の素通し = 引数と戻り値が一致 = Fucn<int, int> の方だけなのでそっちが選ばれる
        // x の型は int に
        M(x => x);

        // 明示的に double を返すと Func<int, double> の方が選ばれる
        // x の型は int に
        M(x => (double)x);

        // この場合、引数と戻り値が一致してるという条件では int なのか string なのか区別できなくてエラー
        N(x => x);
    }

    static void M(Func<int, int> x) => Console.WriteLine("int → int");
    static void M(Func<int, double> x) => Console.WriteLine("int → double");

    static void N(Func<int, int> x) => Console.WriteLine("int → int");
    static void N(Func<string, string> x) => Console.WriteLine("int → int");
}

using System;
using System.Linq.Expressions;

class Program
{
    static void Main()
    {
        // M(() => { }) だと Action か Expression<Action> か区別つかないものの
        // 匿名メソッド式の場合は式ツリー化できない仕様なので、M(Action) で確定
        // なのに以前はこれもエラーになってた(C# 6.0 からは M(Action) が呼ばれる)
        M(delegate () { });

        // 以下のような、多段のラムダ式でちゃんとオーバーロード解決できるのは C# 6.0 から
        // Func<int, Func<int>> の方
        M(() => () => 1);
        // Func<int, Func<double>> の方
        M(() => () => 1.0);
    }

    // ラムダ式だと区別できないものの、匿名メソッド式なら Action で確定
    static void M(Actionx) => Console.WriteLine("Action");
    static void M(Expression<Action> x) => Console.WriteLine("Expression");

    // () => () => 1 みたいな、多段のラムダ式
    static void M(Func<Func<int>> x) => Console.WriteLine("() → () → int");
    static void M(Func<Func<double>> x) => Console.WriteLine("() → () → int");
}

オーバーロード候補の絞り込み

• 静的メソッドかインスタンス メソッドかの違いで解決できるようになった
• ジェネリック型制約の違いで解決できるようになった
• メソッド グループを引数にするとき、メソッドの戻り値を見るようになった

実のところ、これらの改善は「処理手順の順序変更」だそうです。 (今までも、これからも)オーバーロード解決に際して、C# コンパイラーは以下の2つの処理を行っていますが、 この順序を入れ替えることで上記のような区別がつくようになります。

1. 前述のような、引数の数や型の一致度を調べて最も一致するものを探す
2. 本当にそのメソッドを呼べるかどうかを調べる(上記の、静的/インスタンスの差や、型制約を調べる)

例えば、以下のコードを見てください。 同名の静的メソッドとインスタンス メソッドを1つずつ定義していますが、 間違った引数で呼び出しています。

using System;

struct Static { }
struct Instance { }

class Program
{
    // 同名で、片方は静的メソッドで、もう片方はインスタンス メソッド。
    static void M(Static x) => Console.WriteLine("Static");
    void M(Instance x) => Console.WriteLine("Instance");

    static void Main()
    {
        // 型名.M() で呼べるのは静的メソッドだけのはず。
        // でも、エラー メッセージとしては「M(Instance) を呼ぶにはインスタンスが必要」の類。
        Program.M(new Instance());

        // インスタンス.M() で呼べるのはインスタンス メソッドだけのはず。
        // でも、エラー メッセージとしては「M(Static) を呼ぶにはインスタンス越しじゃダメ」の類。
        new Program().M(new Static());

        // つまり、引数の型でのオーバーロード解決を先にやって、その後、静的/インスタンスの区別を調べてる。
    }
}

静的かインスタンスかの差をよりも先に、引数の型だけでオーバーロード解決しています。 なので、Program.M(new Instance())と呼ぼうが、M(Instance x)の方がまず選ばれます。 そして、「M(Instance x)はインスタンス メソッドなので、型名.Mでは呼べない」というエラーになります。

C# 7.3でこの順を逆にして、引数の型でオーバーロード解決をする前に、静的かインスタンスかなどの条件を先に見るようになりました。 呼べないことがわかるんだったら最初からオーバーロード解決候補から外して欲しいわけで、 ある意味当然の変更でしょう。

静的メソッドかインスタンス メソッドか

using System;

struct Static { }
struct Instance { }

class Program
{
    // 既定値が入っているのでどちらも M() で呼べる。
    // 片方は静的メソッドで、もう片方はインスタンス メソッド。
    static void M(Static x = default) => Console.WriteLine("Static");
    void M(Instance x = default) => Console.WriteLine("Instance");

    static void Main()
    {
        // 型名.M() で呼べるのは静的メソッドだけのはず。
        // でも、これまでは、M(Static) か M(Instance) かの区別がつかなかった。
        // C# 7.3 では M(Static) が選ばれるように。
        Program.M();

        // インスタンス.M() で呼べるのはインスタンス メソッドだけのはず。
        // 同上。
        // C# 7.3 では M(Instance) が選ばれるように。
        new Program().M();

        // Main が静的メソッドなので、何もつけない場合、この M() も静的な方が呼ばれる。
        M();
    }

    void InstanceMethod()
    {
        // でも、これはダメ。
        // 静的な方もインスタンスの方も M() で呼べるので不明瞭。
        M();

        // これなら OK。
        // this. が付いているのでインスタンス メソッドに絞られる。
        this.M();
    }
}

余談: Color Color 問題

using System;

struct Color
{
    public byte R;
    public byte G;
    public byte B;

    // どちらも M() で呼べるメソッド。
    public void M(int x = 0) => Console.WriteLine("Instance");
    public static void M(Color c = default) => Console.WriteLine("static");

    // 参考までに、オーバーロードがない場合。
    public void Instance() { }
    public static void Static() { }
}

class Program
{
    // C# では、型名とプロパティ名が同じプロパティを作れる。
    static Color Color { get; set; }

    static void Main()
    {
        // これは「プロパティのColor」(C# 7.2以前でも行ける)。
        Color.Instance();

        // これが「型のColor」(C# 7.2以前でも行ける)。
        Color.Static();

        // これだと、この Color が型名かプロパティかが区別できない。
        // C# 7.3 でも不明瞭エラー。
        Color.M();

        // C# 7.3 なら、以下の書き方で呼び分け可能(これまでは不明瞭エラー)。
        // 「プロパティのColor」。
        Program.Color.M();
        // 「型のColor」。
        global::Color.M();
    }
}

ジェネリック型制約

using System;

// オーバーロード用のダミー型
struct A { }
struct B { }

// IDisposable, IComparable な型を用意
struct Disposable : IDisposable { public void Dispose() { } }
struct Comparable : IComparable { public int CompareTo(object x) => 0; }

class Program
{
    // M(x) で呼べるメソッドが2つ。
    // 差は、T の型制約のみ。
    static void M<T>(T x, A _ = default) where T : IDisposable { }
    static void M<T>(T x, B _ = default) where T : IComparable { }

    static void Main()
    {
        // C# 7.3 からこの呼び出し方ができるように。
        M(new Disposable());
        M(new Comparable());

        // この書き方も C# 7.3 から。
        M(new Disposable(), default); // default は default(A) に推論される
        M(new Comparable(), default); // default は default(B) に推論される

        // C# 7.2 以前の場合、こう書くのが必須。
        M(new Disposable(), default(A));
        M(new Comparable(), default(B));
    }
}

特に、参照型(class)か値型(struct)かによるオーバーロード解決は便利そうです。 例えば、「条件を満たさなければnullを返す」みたいなメソッドを書きたい場合、 値型の時だけnull許容型にして、?を付ける必要があります。 この呼び分けが、これまでだとなかなか難しかったですが、C# 7.3ではできるようになります。

using System.Collections.Generic;
using System.Linq;

static class ClassExtensions
{
    // クラスの場合は LINQ の FirstOrDefault そのまま。
    public static T FirstOrNull<T>(this IEnumerable<T> source)
        where T : class
        => source.FirstOrDefault();
}

static class StructExtensions
{
    // 構造体の場合は null 許容型に変える必要がある。
    public static T? FirstOrNull<T>(this IEnumerable<T> source)
        where T : struct
        => source.Select(x => (T?)x).FirstOrDefault();
}

class Program
{
    static void Main()
    {
        // ClassExtensions の方のが呼ばれる。
        new[] { "a", "b", "c" }.FirstOrNull();

        // StructExtensions の方のが呼ばれる。
        new[] { 1, 2, 3 }.FirstOrNull();
    }
}

メソッドの戻り値

C# (というか、.NET)のメソッドは、戻り値の型をシグネチャに含みません。 基本的に、戻り値だけが違うメソッドは定義できませんし、呼び分けもできません。

ただ、これまでの例でもたびたび出てきたように、引数の規定値を与えることで戻り値だけが違う「っぽく見える」メソッド オーバーロードはできます。 また、以下のように、「戻り値違いのデリゲートを受け取るメソッド」は作れます。

static void M(Func<int> f) => Console.WriteLine("int");
static void M(Func<string> f) => Console.WriteLine("string");

前述の通り、 ラムダ式であれば、ラムダ式の型推論が賢くて、この2つのメソッドの呼び分けができました。

M(() => 0); // int の方
M(() => "abc"); // string の方

しかし、メソッド グループを引数に渡した場合、これまではオーバーロード解決できませんでした。 それが、以下のように、C# 7.3からはオーバーロード解決できるようになります。

using System;

class Program
{
    static void M(Func<int> f) => Console.WriteLine("int");
    static void M(Func<string> f) => Console.WriteLine("string");

    static int IntReturn() => 0;
    static string StringReturn() => "";

    static void Main()
    {
        // ラムダ式賢い。
        M(() => 0); // int の方
        M(() => "abc"); // string の方

        // こういう書き方なら C# 7.2 まででもできた。
        M(() => IntReturn());
        M(() => StringReturn());

        // なのに、以下のような書き方はこれまでできなかった。
        // C# 7.3 からできるように。
        M(IntReturn);
        M(StringReturn);
    }
}

余談: 同一シグネチャのメソッド オーバーロード

// 以下の2つは呼び分けできるようになった。
// なのに、定義はできない(C# コンパイラーだけの問題じゃないので直せない)。
static void M<T>(T x) where T : struct { }
static void M<T>(T x) where T : class { }

1つはオプション引数(引数の規定値)や可変長引数を使う方法で、以下のような書き方で「違うオーバーロードなんだけど、実質的には同じ呼び方ができる」と言うようなメソッドを定義できます。

class Program
{
    // 呼び分け用のダミー型
    struct Struct { }
    struct Class { }

    // ダミー引数を足すことでオーバーロードする。
    static void M<T>(T x, Struct _ = default) where T : struct { }
    static void M<T>(T x, Class _ = default) where T : class { }

    static void Main()
    {
        M(1);     // M(T, Struct) が呼ばれる
        M("abc"); // M(T, Class) が呼ばれる
    }
}

もう1つは拡張メソッドを使う方法です。 拡張メソッドであれば、別のクラス中で定義してやれば、同じ型を対象とした全く同じシグネチャのメソッドを定義できます。

using System.Collections.Generic;
using System.Linq;

static class ClassExtensions
{
    public static T FirstOrNull<T>(this IEnumerable<T> source)
        where T : class
        => source.FirstOrDefault();
}

static class StructExtensions
{
    public static T? FirstOrNull<T>(this IEnumerable<T> source)
        where T : struct
        => source.Select(x => (T?)x).FirstOrDefault();
}

また、refの有無が違うだけの拡張メソッドでもオーバーロード可能です。

static class Extensions
{
    // ref の有無の差 + 型制約
    public static void M<T>(this ref T x) where T : struct { }
    public static void M<T>(this T x) where T : class { }
}

class Program
{
    static void Main()
    {
        "abc".M();

        var x = 123;
        x.M();
        // ただ、ref 拡張メソッドの性質上、123.M() とは呼べない(リテラルがダメ)
        // また、DateTime.Now.M() とかもダメ(プロパティ越しがダメ)
    }
}

いずれも疑似的なもので、ダミーなしのオーバーロードと比べると利便性は下がりますが、 C# 7.3で呼び分けができるようになったことで、少し使い勝手はよくなりました。

OverloadResolutionPriority 属性

C# 13 で、オーバーロードの解決優先度を属性を付けて明示できる機能が入りました。 OverloadResolutionPriority 属性(System.Runtime.CompilerServices 名前空間)を使います。 名前通り優先度を指定できて、正の整数を指定すると優先度が上がって、負の整数なら下がります。

using System.Runtime.CompilerServices;

// IEnumerable<char> の方が選ばれる。
C.M1("");
C.M2("");

class C
{
    // 通常、インターフェイスよりも具体的な型の方が優先。
    public static void M1(string _) { }

    // 属性を付けて優先度を上げる。
    [OverloadResolutionPriority(1)]
    public static void M1(IEnumerable<char> _) { }

    // 属性を付けて優先度を下げる。
    [OverloadResolutionPriority(-1)]
    public static void M2(string _) { }

    public static void M2(IEnumerable<char> _) { }
}

ちなみに、オーバーロードできないメンバーにこの属性を付けるとコンパイル エラーになります。

using System.Runtime.CompilerServices;

namespace System.Runtime.CompilerServices
{
    // .NET 標準ライブラリ中の OverloadResolutionPriorityAttribute には
    // AttributeTargets.Method | Constructor | Property がついてる。
    // ここではあえてターゲットの制限を外した同名・同名前空間の型を定義。
    public sealed class OverloadResolutionPriorityAttribute(int priority) : Attribute
    {
        public int Priority => priority;
    }
}

class C
{
    [OverloadResolutionPriority(0)]
    static C() { }

    [OverloadResolutionPriority(0)]
    ~C() { }

    [OverloadResolutionPriority(0)]
    public int X { get; }

    [OverloadResolutionPriority(0)]
    public static implicit operator int(C x) => default!;
}

互換性問題

C# の言語機能が増えるにつれて、例えば「IEnumerable<T> よりも、ReadOnlySpan<T> 引数を使いたい」みたいなことが多々あります。 しかし、以前からあるメソッドを消すことができなくて、それは残したまま新しいオーバーロードを追加することになったりします。 (ライブラリ作者、特に、プラグイン提供するような場合、バイナリ互換(ソースコードの再コンパイルなしでも動く保証)を残すため、メソッドの削除はできなくなります。) ところが、互換性のために消すに消せない方のメソッドが、優先度が高すぎて困ったり、 オーバーロード解決できなくなって困るということが起こるようになってきました。

IEnumerable<T> と ReadOnlySpan<T> の場合、C# 13 時点ではオーバーロード解決できなくなって困ります。 (この2者の問題であれば、C# 14 で Span<T>/ReadOnlySpan<T> の特別扱いが入って問題解消する予定です。)

// C# 13 時点だと IEnumerable と ReadOnlySpan を選べなくてコンパイル エラーになる。
C.M(new int[1]);

class C
{
    public static void M(IEnumerable<int> _) { }

    // ReadOnlySpan は C# 7.2 / .NET Core 2.1 / 2017年頃に入った。
    // パフォーマンス的に有利なので IEnumerable を置き換えたいことがある。
    public static void M(ReadOnlySpan<int> _) { }
}

他に、デフォルト引数が絡んだ場合に困ったりします。 具体的には、Debug.Assert や文字列がらみで困っているみたいです。

Debug.Assert は、C# 10 で導入された CallerArgumentExpression を使いたいものの、既存のオーバーロードに阻害されて呼びようがないという問題が出ています。

var x = int.Parse(Console.ReadLine());

// Debug.Assert(x > 0, "x > 0") になってほしいのに、1引数の方が呼ばれちゃう。
Debug.Assert(x > 0);

// System.Diagnostics.Debug からの抜粋
class Debug
{
    // 元々 bool 1引数のオーバーロードがある。
    public static void Assert(bool condition) { }

    // C# 10 で導入された CallerArgumentExpression を使いたい。
    // けど、 Assert(condition) では1引数オーバーロードの方が優先されて、CallerArgumentExpression が役に立たない。
    public static void Assert(bool condition, [CallerArgumentExpression(nameof(condition))] string? message = null) { }
}

文字列がらみは、 .NET の負の遺産として有名なカルチャー依存問題(参考: 遅い、環境依存)への対処として、IndexOf などのメソッドにデフォルト引数 StringComparison comparisonType = StringComparison.Ordinal を付けて、無指定の時の挙動を Ordinal に変えたいという話があります。 しかしこれも、1引数オーバーロードの方が優先度が高くてうまく働きません。

// IndexOf(value, StringComparison.Ordinal) で呼ばれてほしいけど、
// 残念ながら IndexOf(value) にしかならない。
String.IndexOf("àèò", "a");

// 本来は string クラスのインスタンスメソッド。デモ用に静的メソッド。
static class String
{
    // 1引数オーバーロードがいるので…
    public static void IndexOf(this string s, string value) => s.IndexOf(value);

    // デフォルト引数を付けたところで IndexOf(string value) の方が優先される。
    public static void IndexOf(
        this string s, string value,
        StringComparison comparisonType = StringComparison.Ordinal) // Ordinal をデフォルトに変えたい。
        => s.IndexOf(value, comparisonType);
}

これらの問題に OverloadResolutionPriority 属性が使えます。

using System.Runtime.CompilerServices;

C.M(new int[1]); // 無事、ReadOnlySpan の方が選ばれる。

class C
{
    [OverloadResolutionPriority(-1)]
    public static void M(IEnumerable<int> _) { }

    public static void M(ReadOnlySpan<int> _) { }
}

using System.Runtime.CompilerServices;

var x = int.Parse(Console.ReadLine());

// 無事、 Debug.Assert(x > 0, "x > 0") で呼ばれる。
Debug.Assert(x > 0);

class Debug
{
    [OverloadResolutionPriority(-1)]
    public static void Assert(bool condition) { }

    public static void Assert(bool condition, [CallerArgumentExpression(nameof(condition))] string? message = null) { }
}

using System.Runtime.CompilerServices;

// 無事、IndexOf(value, StringComparison.Ordinal) で呼ばれる。
String.IndexOf("àèò", "a");

static class String
{
    [OverloadResolutionPriority(-1)]
    public static void IndexOf(this string s, string value) => s.IndexOf(value);

    public static void IndexOf(
        this string s, string value,
        StringComparison comparisonType = StringComparison.Ordinal) // Ordinal をデフォルトに変えたい。
        => s.IndexOf(value, comparisonType);
}

ちなみに、OverloadResolutionPriority で優先度を下げたメソッドを呼び出すのはかなり困難になったりします。 場合によっては真っ当な方法で呼ぶ手段がなく、リフレクションや unsafe な手段でしか呼べなくなります。

using System.Runtime.CompilerServices;

// OverloadResolutionPriority(-1) のせいで、真っ当な方法ではどうやっても M(string) の方を呼べない。
C.M((string)"");

// リフレクションとか Unsafe な手段を使えば一応呼べなくはない。
[UnsafeAccessor(UnsafeAccessorKind.StaticMethod, Name = nameof(C.M))]
static extern void M(C? c, string _);
M(default, "");

class C
{
    public static void M(object _) => Console.WriteLine("object");

    [OverloadResolutionPriority(-1)]
    public static void M(string _) => Console.WriteLine("string");
}

同一クラス内でのみ有効

OverloadResolutionPriority 属性による優先度の変更は、同一クラス内においてのみ有効です。 なので、以下のようなことはできません。

• 拡張メソッドでインスタンス メソッドを乗っ取り
• 自作の拡張メソッドで他人の拡張メソッドを乗っ取り
• 派生クラス内のオーバーロードで基底クラスのメソッドを乗っ取り

例えば以下のような所業はできません。

using System.Runtime.CompilerServices;

// わざと System.Linq.Enumerable と競合するようにして、
namespace System.Linq;

static class FakeLinq
{
    // 優先度を最大限引き上げ。
    [OverloadResolutionPriority(int.MaxValue)]
    public static IEnumerable<TResult> Select<TSource, TResult>(
        this IEnumerable<TSource> source, Func<TSource, TResult> selector)
        => throw new Exception("Select は乗っ取った");
}

// FakeLinq の方が優先されたりはしない。
// 単に「Enumerable と FakeLinq 間で不明瞭」エラーに。
"abc".Select(c => (int)c);

また、OverloadResolutionPriority を付けることで逆にオーバーロード解決できなくなるようなこともありえます。

例えば、以下のように複数のクラスで複数の拡張メソッドが定義されていて、 全体でみれば1つだけ優先度が高くてオーバーロード解決できる場合を考えます。

// A.M(string), A.M(string, int), B.M(string, int) が同列で比較されて、
// デフォルト引数なしの A.M(string) が勝つ。
"".M();

static class A
{
    public static void M(this string s) => Console.WriteLine($"A.M({s})");
    public static void M(this string s, int i = 0) => Console.WriteLine($"A.M({s}, {i})");
}

static class B
{
    public static void M(this string s, int i = 0) => Console.WriteLine($"B.M({s}, {i})");
}

ここで、A.M のうちの1つに OverloadResolutionPriority を付けて優先度を変えてみます。 OverloadResolutionPriority は1つのクラス内でしか働かないので、A の中のどの M が選ばれるかにだけ影響します。 その結果、以下のように別のクラスの M と競合する可能性があります。

using System.Runtime.CompilerServices;

// OverloadResolutionPriority を付けたことで、A.M の中では A.M(string, int) が選ばれる。
// B.M は元々 B.M(string, int) しかない。
// A.M(string, int) と B.M(string, int) が競合してオーバーロード解決できなくなる。
"".M();

static class A
{
    public static void M(this string s) => Console.WriteLine($"A.M({s})");

    [OverloadResolutionPriority(1)]
    public static void M(this string s, int i = 0) => Console.WriteLine($"A.M({s}, {i})");
}

static class B
{
    public static void M(this string s, int i = 0) => Console.WriteLine($"B.M({s}, {i})");
}

余談: (疑似)戻り値オーバーロード

C# では戻り値だけが異なるオーバーロードを認めていません。 例えば以下のコードはコンパイル エラーになります。

class C
{
    public static async Task MAsync() { await Task.Yield(); }

    // Task を ValueTask に変更したいとして、互換性のために Task MAsync() を残すと…
    // 戻り値だけが違うオーバーロードは認められない。
    public static async ValueTask MAsync() { await Task.Yield(); }
}

ちょっと気持ち悪い回避策になりますが、デフォルト引数を悪用することでオーバーロードもどきを作れたりはします。 ところが、「引数なし」と「デフォルト引数持ち」なら前者の方が優先されるため、 追加した新しいオーバーロードもどきが呼ばれることはありません。

// 残念ながら Task MAsync() の方しか呼ばれない。
await C.MAsync();

// もちろんこうすれば ValueTask の方が呼ばれるものの、不格好すぎる。
await C.MAsync(default);

class C
{
    public static async Task MAsync() { await Task.Yield(); }

    // オーバーロードもどきとして、適当に使わないデフォルト値付きの引数を追加。
    public static async ValueTask MAsync(int _ = 0) { await Task.Yield(); }
}

これも一応、OverloadResolutionPriority 属性で解消できます。

using System.Runtime.CompilerServices;

// ValueTask 戻り値の方が呼ばれるように。
await C.MAsync();

class C
{
    [OverloadResolutionPriority(-1)]
    public static async Task MAsync() { await Task.Yield(); }

    public static async ValueTask MAsync(int _ = 0) { await Task.Yield(); }
}

Ver. 2.0

C# 2.0 で、partial 修飾子を付けることで、クラスや構造体、インターフェイスを複数のファイルに分けて型を定義できるようになりました。 この partial によるファイルの分割は、 「片方のファイルを手書き、もう片方のファイルを開発ツールなどによって自動生成」みたいな状況を想定しています。

(それ以外の用途でむやみに複数のファイル分けると、どのファイルに何のメソッドがあるのか探しにくくなるので、 通常は、むしろ、クラス定義を複数のファイルに分割しない方がいいです。)

背景: ツール生成のソースコード

Visual Studio などの統合開発環境を利用していると分かると思いますが、 ソースファイルの一部分はプログラマーの手書きではなく、 開発ツールが自動的に生成してくれる部分があります。

例えば、データベースのテーブル定義から C# のクラスを生成するみたいなツールがあります。 仮に、Id と Name の2つの列がある Entity という名前のテーブルから、以下のようなクラスをツール生成したとします。

class Entity
{
    public int Id { get; set; }
    public string? Name { get; set; }
}

これに対して、プロパティの値の書き換え時に処理を挟みたいとします。 一応、ツール生成のソースコードを書き換えれば目的を達成することは可能ではあります。

class Entity
{
    private int _id;
    public int Id { get => _id; set { if (_id != value) { _id = value; _changed = true; } } }

    private string? _name;
    public string? Name { get => _name; set { if (_name != value) { _name = value; _changed = true; } } }

    private bool _changed;
    public void Flush() => _changed = false;
}

ここで、データベースのテーブルに列 X を追加したので、ツール生成の C# コードも更新したいとします。 「手書きで書き方部分は残して新たに追加したものだけをソースコード生成」なんてことは難しく、普通はすべて上書きされます。

class Entity
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public int X { get; set; }
}

ソースコードの一部分を「ここはツール生成だから書き換えないで」領域にすることもできなくはないですが、なかなかに危険です。 例えば、WinForms (C# 1.1 時代からある GUI フレームワーク)開発がまさにそういう方式で、 WinForms アプリを作ると、ソースコード中に以下のような領域ができます。

namespace WinFormsApp1;

partial class Form1
{
    // 前略
    // この部分は手書きで書き換える想定。

    #region Windows Form Designer generated code

    /// <summary>
    ///  Required method for Designer support - do not modify
    ///  the contents of this method with the code editor.
    /// </summary>
    private void InitializeComponent()
    {
        this.components = new System.ComponentModel.Container();
        this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
        this.ClientSize = new System.Drawing.Size(800, 450);
        this.Text = "Form1";
    }

    #endregion
}

まさに「書き換えないで」(do not modify)と書かれていますし、 実際、書き換えても Visual Studio によって元に戻されたりします。 手で書き換える想定のコードとツール生成コードが1ファイルに混ざっていることで、 例えば、「ファイル内で一斉置換」みたいな作業をしたときにツール生成部分を壊したりといった事故もありました。

型の分割

このように、手書きとツール生成の混在は危険なので、別ファイルに分かれている方が安心です。 そこで、C# 2.0 では、クラス定義時に partial というキーワードを付けることで、 クラス定義を複数に分割することができるようになりました。 これを 部分クラス(partial class)と言います。

例えば前節のツール生成例に partial を付けてみましょう。

partial class Entity
{
    public int Id { get; set; }
    public string? Name { get; set; }
}

この型に手で何かコードを足したい場合、別ファイルに以下のような感じでコードを書きます。

partial class Entity
{
    private bool _changed;
    public void Flush() => _changed = false;
}

(プロパティ Id や Name の中の処理を変更したい場合の話は次節の「メソッドの実装の分離」で説明します。)

partial はクラスの他に、構造体、インターフェイスにもつけれます。

partial struct S { }
partial struct S { }

partial interface I { }
partial interface I { }

partial record R { }
partial record R { }

partial record class RC { }
partial record class RC { }

partial record struct RS { }
partial record struct RS { }

ただ、部分クラスにしたい場合、すべての型定義に partial 修飾子を付ける必要があります。 これは、「ファイルを分けるつもりがなかったのに、他の誰かに勝手に部分定義を足された」みたいなことを避けるためです。

// 片方に partial が付いてないとエラー。
class C { }

partial class C { }

ちなみに、partial 以外の修飾子に関しては、複数ある型定義についてる修飾子すべてを統合したものになります。 例えば、以下のように「片方が public、もう片方が static」な場合、この型は public static 扱いです。

// この型は public static class C 扱い。
public partial class C { }
static partial class C { }

ここで実例として、WPF アプリを紹介します。 WinForms とは違って、WPF (C# 3.0 世代の GUI フレームワーク)は partial を使ってツール生成のコードと手書きコードを分けています。 WPF アプリでは、手での書き換えを前提とした以下のようなコードを書く一方で、

using System.Windows;

namespace WpfApp1;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }
}

ツール生成で以下のようなコードが作られます(実物はだいぶ長いので一部抜粋)。

//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
//     Runtime Version:4.0.30319.42000
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

using System;
using System.Diagnostics;
using System.Windows;
// 中略

namespace WpfApp1
{
    public partial class MainWindow : System.Windows.Window, System.Windows.Markup.IComponentConnector
    {
        private bool _contentLoaded;

        public void InitializeComponent()
        {
            if (_contentLoaded)
            {
                return;
            }
            _contentLoaded = true;
            System.Uri resourceLocater = new System.Uri("/WpfApp1;V1.0.0.0;component/mainwindow.xaml", System.UriKind.Relative);

#line 1 "..\..\..\MainWindow.xaml"
            System.Windows.Application.LoadComponent(this, resourceLocater);
        }
// 中略
    }
}

こちらのツール生成のコードは、通常、どこに生成されたのかすら意識せず、中身を覗くこともほとんどありません。

メソッドの実装の分離

Ver. 3.0

C# 3.0 で 部分メソッド（partial method）という機能も追加されました。

どういうものかというと、 部分クラス内限定で、 メソッドに partial を付けることでメソッドの宣言と定義を分けれるというものです。

定義の仕方と、制限事項は以下の通り。

• partial 修飾子を付けてメソッドを宣言する。

• 必ず部分クラス内になければならない。

• アクセシビリティの指定はできない(自動的に必ず private 扱い)。

• 戻り値は void 以外不可。

• 引数は自由に取れる。ref, this, params も利用可能。ただし、out 引数は不可。

• 静的メソッド（static）でもインスタンス メソッド（非 static）でも OK。

例として、前節の Entity の例で出てきた 「プロパティ Id や Name の中の処理を変更したい場合の話」をしましょう。

用途的に、「プロパティの値が変わったときに何かはしたい」、 「ただ、何をするかはアプリごとに異なる」 みたいなことがあります。 そういった場合、「プロパティの値が変わった」のタイミングを拾えるよう、 以下のように、部分メソッドを含むコードをツール生成してもらっておきます。

partial class Entity
{
    private int _id;
    public int Id { get => _id; set { if (_id != value) { _id = value; OnIdChanged(); } } }
    partial void OnIdChanged();

    private string? _name;
    public string? Name { get => _name; set { if (_name != value) { _name = value; OnNameChanged(); } } }
    partial void OnNameChanged();
}

OnIdChanged と OnNameChanged が部分メソッドです。 このまま何も手書きコードを足さなければ、これらのメソッドは何もしません。 (空のメソッドが呼ばれるとかですらなく、メソッドを呼んだ痕跡すらも完全に消えます。) （さらにいうと、メタデータすら残さず、完全に消えます。 Conditional 属性でも似たようなことができますが、こちらは少なくともメタデータは残ります。）

一方、手書きコードで処理を足したければ以下のような感じのコードを書きます。

partial class Entity
{
    partial void OnIdChanged() => _changed = true;
    partial void OnNameChanged() => _changed = true;

    private bool _changed;
    public void Flush() => _changed = false;
}

こうすると、追加した OnIdChanged や OnNameChanged の実装が呼び出されるようになります。

部分メソッドの引数で副作用を起こす場合

「不要な場合は完全削除」という仕様には、1つ奇妙な動作を招く点があります。 問題が起こり得るのは、部分メソッドの呼び出しの際に引数で副作用を起こす場合です。

例えば、以下のコードの実行結果はどうなるでしょう。

partial class Program
{
    static void Main(string[] args)
    {
        int x = 1;
        A(x = 2);
        Console.Write("{0}\n", x);
    }

    static partial void A(int x);
}

A の実装がある場合には 2 に、ない場合には 1 になります。 部分クラスなので、当然、実装は別ファイルにあってもかまいません。 自分以外の誰かがどこか別のところで実装を書くかもしれませんし、 誰も書かないかもしれません。 要するに、自分の知らないところで実行結果が変えられてしまう可能性がある。

まあ、メソッド呼び出しの () 内で代入なんてするなよって話ではあるんですが。 こういう副作用があることも覚えておいてください。 （あるいは、この副作用を積極的に利用したトリッキーなコードも書けるでしょうが・・・。 個人的には非推奨。）

部分メソッドの拡張

Ver. 9

前節で説明した部分メソッドは「開発ツールが生成したコードが先にあって、そこに手書き処理を足したいときに使う物」です。

一方、C# 9.0 世代ではソースコード生成機能が入ったことでこの逆があり得ます。 すなわち、「ソースコード生成してもらう前提で、手書きでは不完全な C# コードを書きたい」という場面が出てきました。

C# 9.0 では、そのための「不完全なメソッド」を書く方法として partial キーワードを再利用することにしました。 旧来の部分メソッドとの文法上の差はアクセシビリティ修飾子(public とか private とか)を持つかどうかです。

// (1) ツールが事前に生成する想定のコード
partial class PartialClass
{
    public void PreGeneratedMethod()
    {
        OnPreGeneratedMethod();
 
        // ツール生成のコード
    }
 
    // ツール生成のコードの前に何か手書き処理を足したければこのメソッドの中身を書く
    partial void OnPreGeneratedMethod();
}
 
// (2) 手書き前提のコード
partial class PartialClass
{
#if DEBUG
    // ツール生成コード前に、Debug 時のみログを仕込む。
    // これを書かなければ OnPreGeneratedMethod は呼ばれる痕跡すら残らない。
    partial void OnPreGeneratedMethod()
    {
        System.Console.WriteLine(
            "PreGeneratedMethod が呼ばれた直後"
            + WantSourceGenerated());
    }
#endif
 
    // 手書き C# コードが先にあって、これを元にソースコード生成してほしいメソッド。
    private partial string WantSourceGenerated();
}
 
// (3) C# からのソースコード生成が前提のコード
partial class PartialClass
{
    private partial string WantSourceGenerated() => "手書きはしづらしくて、ソースコード生成なら楽な文字列";
}

コード解析・コード生成の利用で紹介している StringLiteralGenerator はこの新しい部分メソッドを使っています。

ちなみに、コード生成と手書きの期待される順序が逆になっただけ(しかも文法上は非常に小さな差)ですが、結果的には結構できること・できないことが変わります。 以下の表に違いをまとめます。

アクセシビリティ修飾子の有無だけでここまで差があることには少し抵抗があって、 文法をどうするかは C# チームも結構迷ったようです。 ただ、最終的には、下手にキーワードを追加したり全然違う文法を導入するよりはマシという判断が下りました。

シグネチャの一致

部分メソッドは、宣言側と実装側でシグネチャ(引数リスト、戻り値の型、修飾子)が一致している必要があります。

アクセシビリティ、static, readonly, ref の有無が違うとエラーになります。

partial class PartialClass
{
    public static partial ref readonly int M0();
    public static partial ref readonly int M1();
    public static partial ref readonly int M2();
    public static partial ref readonly int M3();
    public static partial ref readonly int M4();
    public static partial ref readonly int M5();
}

partial class PartialClass
{
    // 全部一致。これは大丈夫。
    public static partial ref readonly int M0() => throw new Exception();

    // 戻り値の型が違うのは当然ダメ。エラー。
    public static partial ref readonly byte M1() => throw new Exception();

    // 以下、修飾子のどこかが違う。全部エラー。
    private static partial ref readonly int M2() => throw new Exception();
    public partial ref readonly int M3() => throw new Exception();
    public static partial int M4() => throw new Exception();
    public static partial ref int M5() => throw new Exception();
}

タプル要素名の差もエラーになります。

partial class PartialClass
{
    public partial (int x, int y) M0((int x, int y) t);
    public partial (int x, int y) M1((int x, int y) t);
    public partial (int x, int y) M2((int x, int y) t);
}

partial class PartialClass
{
    // 全部一致。これは大丈夫。
    public partial (int x, int y) M0((int x, int y) t) => default;

    // タプル要素名が違うとエラーに。
    public partial (int x, int y) M1((int a, int b) t) => default;
    public partial (int a, int b) M2((int x, int y) t) => default;
}

引数名、null 許容参照型のアノテーションの差は警告になります。

partial class PartialClass
{
    public partial void M0(int x, string? y);
    public partial void M1(int x, string? y);
    public partial void M2(int x, string? y);
}

partial class PartialClass
{
    // 全部一致。これは大丈夫。
    public partial void M0(int x, string? y) { }

    // 引数名が違う。警告。
    public partial void M1(int a, string? y) { }

    // nullability が違う。警告。
    public partial void M2(int a, string y) { }
}

一方で、属性は統合されます。

partial class PartialClass
{
    [A] public partial void M([A] int x);
}

partial class PartialClass
{
    [B] public partial void M([B] int x) { }
}

// [A, B] public partial void M([A, B] int x) { } と書いたのと同じになる。

class A : Attribute { }
class B : Attribute { }

部分プロパティ

Ver. 13

C# 3.0 からある方の部分メソッド は「戻り値なし(void)でないとダメ」という制約があって、 メソッド以外では元々役に立ちません。

一方、C# 9.0 で拡張された方の部分メソッド は、 制約的にも用途的にも、プロパティやインデクサーでも使えるはずです。 実際、工数の問題で後回しになっていただけで、C# 13 でめでたく部分プロパティ・部分インデクサーが実装されました。

// 元コード。
partial class PartialClass
{
    // 部分プロパティ。
    public partial int PartialProprty { get; set; }

    // 部分インデクサー。
    public partial int this[int index] { get; set; }
}

// コード生成で作ってもらう前提のコード。
partial class PartialClass
{
    private int _field;
    public partial int PartialProprty { get => _field; set => _field = value; }

    private int[] _array = new int[10];
    public partial int this[int index] { get => _array[index]; set => _array[index] = value; }
}

この機能の追加で特にうれしいのは GeneratedRegex の存在でしょう。 C# 12 までは、以下のようにメソッドにする必要がありました。

using System.Text.RegularExpressions;

partial class MyPatterns
{
    [GeneratedRegex(@"\d{4}")]
    public static partial Regex FourDigits();
}

この属性を付けると、正規表現 \d{4} のマッチ処理をソースコード生成で作ってくれます。 (普通に new Regex(@"\d{4}") と書くよりもだいぶパフォーマンスがよくなります。)

ただ、生成されるコードはメソッドよりもプロパティっぽいコード (呼ぶたびに何か処理をするのではなく、最初の1回で作ったインスタンスをキャッシュして持っておいて、2回目からはほとんどノーコスト)になっています。 これまでは「部分プロパティがなかったからやむなくメソッドに付けていた」というだけで、 C# 13 と同世代の .NET 9 からはプロパティで同じことができるようになりました。

using System.Text.RegularExpressions;

partial class MyPatterns
{
    [GeneratedRegex(@"\d{4}")]
    public static partial Regex FourDigits { get; } // プロパティになった。
}

プロパティの宣言と自動実装

C# の文法上の紛らわしさなんですが、 プロパティに対して { get; set; } などと書いたときの扱いには2種類あるので注意が必要です。

普通のクラスや構造体で { get; set; } を書くとき、これは自動実装になります。

class C
{
    // 自動実装の意味。
    public int X { get; set; }

    // コンパイラーが裏でフィールドを1個作って、
    // public int X { get => field; set => field = value; }
    // みたいなコードとして扱われる。
}

一方、インターフェイスや、抽象メンバーの場合、「宣言だけある」という扱いになります。

interface I
{
    // 宣言(「このプロパティは get も set も持っていてほしい」という意思表示のみ)。
    int X { get; set; }
}

abstract class C
{
    // これも宣言のみ。
    public abstract int X { get; set; }
}

部分プロパティの場合は後者の意味になります。

partial class C
{
    // 宣言(「partial の片割れで get も set も実装してほしい」という意思表示)。
    public partial int X { get; set; }
}

「片方が宣言、片方が自動実装」みたいなことにはならないので、 以下のコードはコンパイル エラーを起こします。

partial class C
{
    // 宣言。
    public partial int X { get; set; }
}

partial class C
{
    // こっちも宣言。
    // なので、実装がいなくてエラーになる。
    public partial int X { get; set; }
}

部分イベントと部分コンストラクター

部分プロパティ (C# 13)に続いて、 C# 14 ではイベントとコンストラクターも部分定義できるようになりました。 (これも「工数の問題で後回しになっていただけ」の類です。)

// 元コード(手書き想定)。
partial class PartialClass
{
    // 部分イベント。
    public partial event Action<int>? PartialEvent;

    // 部分コンストラクター。
    public partial PartialClass();
}

// コード生成で作ってもらう前提のコード。
partial class PartialClass
{
    private Action<int>? _partialEvent;
    public partial event Action<int>? PartialEvent
    {
        add => _partialEvent += value;
        remove => _partialEvent -= value;
    }

    public partial PartialClass() { }
}

partial キーワードの位置

部分クラス・部分メソッドの仕様は C# 2.0 から追加されたものです。 partialというキーワードも 2.0 からの後付けなわけで、完全に予約語(変数などの名前に使えない単語)にしてしまうと、1.0 時代に書かれたコードを壊す可能性がありました。

そこで、partial は文脈キーワードになっています。 partialという単語がキーワード扱いされるのは、class、struct、interface、voidの直前だけです。 (前節の拡張部分メソッドの場合は戻り値の型の直前だけ。) その結果、以下のように、語順に制約があります。

// OK
public static partial class Ok1 { }
static public partial class Ok2 { }

// コンパイル エラー
public partial static class Ng1 { }
partial public static class Ng2 { }
static partial public class Ng3 { }

partial class X
{
    // OK
    static partial void Ok();

    // コンパイル エラー
    partial static void Ng();
}

執筆予定: C# 13.0 トラッキング issue

params コレクション

コレクション式で使える型であれば何でも params にできるようになりました。

static void M1(params List<int> x) { }
static void M2(params IEnumerable<int> x) { }
static void M3(params Span<int> x) { }
static void M4(params ReadOnlySpan<int> x) { }

M1(1, 2);
M2(1, 2);
M3(1, 2);
M4(1, 2);

需要が高いのは ReadOnlySpan で、 params T[] を params ReadOnlySpan<T> に変更すればそれだけでパフォーマンスの改善が見込めます。

実際、 .NET 9 では、string.Join や Task.WhenAll などのメソッドに params ReadOnlySpan<T> なオーバーロードが増えています。

// .NET 8 以前なら Join(string, string[])
// .NET 9 以降なら Join(string, ReadOnlySpan<string>)
var joiend = string.Join(",", "a", "b", "c");

このため、自分で params を使わない場合でも、 「.NET 9 にアップグレードして再コンパイルするだけでアプリのパフォーマンスがちょっと改善する」という間接的なメリットがあります。

詳しくは「params コレクション」で説明しています。

部分プロパティ

プロパティとインデクサーも partial にできるようになりました。

例えば、C# 13 と同世代の .NET 9 では、GeneratedRegex をプロパティにできるようになりました。

using System.Text.RegularExpressions;

partial class MyPatterns
{
    [GeneratedRegex(@"\d{4}")]
    public static partial Regex FourDigits { get; } // プロパティになった。
}

詳しくは「部分プロパティ」で説明します。

ref 構造体のインターフェイス実装

ref 構造体にインターフェイスを実装できるようになりました。 また、このインターフェイスのメンバーを呼び出すために、 ジェネリック型引数に ref 構造体を渡せるようにする仕組みとして allows ref struct アンチ制約が追加されました。

S x = new(); // S は IFormattable を実装してる。

// これはボックス化を起こすから C# 13 でもエラーになる。
IFormattable f = x;
f.ToString("X", null);

// allows ref struct なジェネリックメソッドを介して、
static void M<T>(T f) where T : IFormattable, allows ref struct
    => f.ToString("X", null);

// こうやって IFormattable.ToString を呼べば大丈夫になった。
M(x);

ref struct S : IFormattable
{
    public string ToString(string? format, IFormatProvider? formatProvider) => "";
}

詳しくは「ref 構造体のインターフェイス実装」で説明します。 また、「アンチ制約」という言葉については「アンチ制約」で説明しています。

OverloadResolutionPriority

C# 13 で、オーバーロードの解決優先度を属性を付けて明示できる機能が入りました。

using System.Runtime.CompilerServices;

// IEnumerable<char> の方が選ばれる。
C.M1("");
C.M2("");

class C
{
    // 通常、インターフェイスよりも具体的な型の方が優先。
    public static void M1(string _) { }

    // 属性を付けて優先度を上げる。
    [OverloadResolutionPriority(1)]
    public static void M1(IEnumerable<char> _) { }

    // 属性を付けて優先度を下げる。
    [OverloadResolutionPriority(-1)]
    public static void M2(string _) { }

    public static void M2(IEnumerable<char> _) { }
}

詳しくは「オーバーロード解決」で説明します。

トラッキングissue: #478

Lock クラスに対する lock

.NET 9 で Lock クラス(System.Threading 名前空間)という新しい lock 用の型が追加されたことに伴って、 lock ステートメントでこの Lock クラスを特別扱いするようになりました。 既存の lock (Monitor.Enter に展開される)と異なり、以下のようなコードに展開されます。

var syncObject = new Lock();

// lock (syncObject)
using (syncObject.EnterScope())
{
}

詳しくは「Lock クラス」で説明しています。

ref/unsafe をイテレーター/非同期メソッド中に書けるように

ref ローカル変数、 ref 構造体の変数、 unsafe ブロックを、 イテレーターと非同期メソッド内で使えるようになりました。

イテレーターと非同期メソッドは内部の仕組み的に非常に似ているにも関わらず、 この2者で微妙に制限のかかり方が違ったんですが、 それも C# 13 でそろいました。

以下のコードで、行末コメントで ⭕ を付けている部分が C# 13 で新たにコンパイルできるようになったコードです。

IEnumerable<object?> Enumerate()
{
    unsafe { } // ⭕

    yield return null;

    Span<byte> data = [];

    yield return null;

    int x = 123;
    ref int r = ref x; // ⭕
}

async Task GetAsync()
{
    unsafe { }

    await Task.Yield();

    Span<byte> data = []; // ⭕

    await Task.Yield();

    int x = 123;
    ref int r = ref x; // ⭕
}

async IAsyncEnumerable<object?> EnumerateAsync()
{
    unsafe { } // ⭕

    await Task.Yield(); yield return null;

    Span<byte> data = []; // ⭕

    await Task.Yield(); yield return null;

    int x = 123;
    ref int r = ref x; // ⭕
}

元々、原理的にはこう書いても問題ないことはわかっていたんですが、 正しく判定するのにコストがかかる割に、需要は低いだろうということでエラーにしていました。 C# 13 で書けるようになったのは、前述のLock クラスに対する lock のついでだそうです。 (Lock クラスの EnterScope が ref 構造体を使っています。)

ただし、これは yield や await をまたがない場合に限って許されます。 例えば以下のコードは C# 13 でもコンパイル エラーを起こします。

IEnumerable<object?> Enumerate()
{
    int x = 123;
    ref int r = ref x;
    yield return null;
    r = 456;
}

async Task GetAsync()
{
    int x = 123;
    ref int r = ref x;
    await Task.Yield();
    r = 456;
}

\e (エスケープ文字のエスケープ シーケンス)

文字・文字列リテラル中のエスケープ シーケンスに \e (U+001B、エスケープ文字)が追加されました。

例えば、コンソール アプリで以下のように書くことで、文字列の色を変えたり装飾したりできます。

Console.WriteLine("\e[31mred text");
Console.WriteLine("\e[4munderlined text");
Console.WriteLine("\e[0mreset style");

機能追加の背景などについてはブログ記事「\e (エスケープ文字のエスケープ シーケンス)」で説明しています。

インターセプター

(書きかけ。予定地。)

トラッキングissue: #456

その他

その他、ほぼバグ修正レベルの機能がいくつかあります。

オブジェクト初期化子中の ^ 演算子

以下のように、オブジェクト初期化子中の [] の中でインデックスの ^ 演算子を使えるようになりました。

// これが C# 12 以前はコンパイル エラーを起こしてた。
var c = new C { [^1] = 1 };

// これなら昔からコンパイルできる。
// (オブジェクト初期化子はこれと同じコードに展開されるはずなのに。)
c[^1] = 1;

class C
{
    // インデクサーと Length さえ持っていれば c[^i] と書けるようになる。
    // c[c.Length - i] 扱い。
    public int Length => 1;
    public int this[int i] { get => i; set { } }
}

デリゲートの自然な型の改善

デリゲートの自然な型の決定の際、 メソッド グループに対する型決定がちょっと賢くなったそうです。 同名のインスタンス メソッドと拡張メソッドがあるとき、インスタンス メソッドを優先的に見るようになりました。

例えば以下のようなクラスがあったとします。

public class C
{
    public void M() { } // インスタンス メソッド M と、
}

public static class E
{
    public static void M(this C c, object o) { } // 同名の拡張メソッド。
}

この C 型のインスタンス x に対して x.M と書いたとき、 C# 12 までは自然な型を決定できなかったのに対して、 C# 13 ではインスタンスメソッドを優先的に見ます。

var x = new C();

// オーバーロード解決ではインスタンスメソッド優先。
x.M();      // C.M()
x.M(""); // E.M(C, object)

// 型の明示があると昔から大丈夫だった。
Action a = x.M;         // C.M()
Action<object> b = x.M; // E.M(C, object)

// var を使う。
// これが C# 13 から行けるように。
// インスタンス メソッド優先で、Action 型になる。
var z = x.M;

コレクション式の改善

コレクション式にも微妙な修正が2つ入っています。

1つは、Add メソッドが拡張メソッドでも大丈夫になりました。 (こちらは最新のコンパイラーにすると LangVersion 12 にしても元の挙動(= コンパイル エラー)にはなりません。)

using System.Collections;

C c = ['a'];

class C : IEnumerable
{
    public IEnumerator GetEnumerator() => throw new NotImplementedException();
}

static class Extensions
{
    // C# 12 の頃はこの拡張メソッドを見てくれずエラーになっていた。
    public static void Add(this C a, char _) { }
}

もう1つは、params コレクションとの兼ね合いで、オーバーロード解決ルールが変わっています。 以下のように、要素の型違いのオーバーロードがあるとき、要素の自然な型を見るようになりました。 (この変更は言語バージョンを見て分岐しているようで、 最新のコンパイラーでも LangVersion を12以前に戻すと古い挙動になります。)

// C# 12 では以下の2つとも解決不能(コンパイル エラー)になってた。

// C# 13 では int の方になる。
C.M([1]);

// C# 13 では string の方になる。
C.M([$""]);

class C
{
    public static void M(List<int> _) { }
    public static void M(List<byte> _) { }

    public static void M(List<string> _) { }
    public static void M(List<IFormattable> _) { }
}

ただ、この結果、ちょっとした破壊的変更も起きています。 C# 12 から C# 13 にアップデートすると、以下のような場合にオーバーロード解決先が変わります。

C.M([1, 2]);

class C
{
    // C# 12 だとこっちが呼ばれる。
    // (ReadOnlySpan 優先。)
    public static void M(ReadOnlySpan<byte> data) => Console.WriteLine("ReadOnlySpan<byte>");

    // C# 13 だとこっちが呼ばれる。
    // (中身の自然な型(整数リテラルは int になる)優先。)
    public static void M(Span<int> data) => Console.WriteLine("Span<int>");
}

前項では、C# 7.2 の新機能と深くかかわる Span<T> 構造体という型を紹介しました。 この型は、論理的には (ref T Reference, int Length) というような、「参照フィールド」と長さのペアを持つ構造体です。 「参照」を持っているので、参照戻り値や参照ローカル変数と同種の「出所の保証」が必要です。 またSpan<T> には「スタック上に置かれている必要がある」(ヒープに置けない)という制限が必要です。

さらに、Span<T> に制限が掛かっている以上、「Span<T>を持つ型」にも再帰的に制限が掛かります。 「Span<T> を持つか持たないか」だけで挙動が変わるのでは影響範囲が大きすぎるため、 「Span<T> を持ちたければ ref という修飾が必要」という制約もあります。

ここでは、これらの Span<T> の「スタック上に置かれている必要がある」という制約や、「ref 構造体」について説明していきます。 (ref構造体という機能ではありますが、主用途がSpan<T>に関するものなので、span safety ruleと呼ばれたりもします。)

ref 構造体

// Span<T> は ref 構造体になっている
public readonly ref struct Span<T> { ... }

// ref 構造体を持てるのは ref 構造体だけ
ref struct RefStruct
{
    private Span<int> _span; //OK
}

// NG。構造体以外を「ref 型」にはできない
ref class InvalidClass { }

// ref がついていない普通の構造体は ref 構造体を持てない
struct NonRefStruct
{
    private Span<int> _span; //NG
}

戻り値で返せるもの

ref 構造体を戻り値として使いたい場合、 ref 戻り値・ref ローカル変数と同様に、大元をたどって調べて(フロー解析して)、返していいものかどうかを判定します。 以下のようなルールがあります(ref戻り値と同じルールです)。

• 引数で受け取ったものは戻り値に返せます
• ローカルで確保したものは返せません
• 引数などを介して多段に参照している場合、コードをたどって大元が安全かまで調べます

// 引数で受け取ったものは戻り値で返せる
private static Span<int> Success(Span<int> x) => x;

// ローカルで確保したもの変数はダメ
private static Span<int> Error()
{
    Span<int> x = stackalloc int[1];
    return x;
}

// 多段の場合も元をたどって出所を調べてくれる
private static Span<int> Success(Span<int> x, Span<int> y)
{
    var r1 = x;
    var r2 = y;
    var r3 = r1.Length >= r2.Length ? r1 : r2;

    // r3 は出所をたどると引数の x か y
    // x も y も引数なので大丈夫
    return r3;
}

private static Span<int> Error(Span<int> x, int n)
{
    var r1 = x;
    Span<int> r2 = stackalloc int[n];
    var r3 = r1.Length >= r2.Length ? r1 : r2;

    // r2 がローカルなのでダメ
    return r3;
}

ちなみに、上記のErrorと似たようなコードでも、以下のコードはコンパイルできます。 ちゃんと「メモリ確保があったかどうか」を見ていて、「defaultであれば何も確保していない」という判定もしています。

// ちゃんと「メモリ確保」があったかどうかを見てる
// 同じようなコードでもこれは OK (default だと何も確保しない)
private static Span<int> Success1()
{
    Span<int> x = default;
    return x;
}

このルールは、ref構造体と、ref引数・ref戻り値の間でも働きます。 例えば、引数由来の Span<T>から得たref Tな参照は戻り値にできますが、ローカル由来のものはできません。

// 引数で受け取った Span 由来の ref 戻り値は返せる
private static ref int Success(Span<int> x) => ref x[0];

// ローカルで確保した Span 由来の ref 戻り値はダメ
private static ref int Error()
{
    Span<int> x = stackalloc int[1];
    return ref x[0];
}

readonly ref

C# 7.2 で追加された構造体がらみの修飾子にはreadonlyというものもあります。 readonly修飾は、一見、参照がらみの機能とは無関係に見えますが、実はこれも「参照として返せるかどうか」の判定に関係しています。

例えば以下のコードを見てください。

using System;

// ref だけ
ref struct RefToSpan
{
    private readonly Span<int> _span;
    public RefToSpan(Span<int> span) => _span = span;

    // 例え _span に readonly が付いていても、this 書き換えが可能
    public void Method(Span<int> span) { this = new RefToSpan(span); }
}

// readonly ref
readonly ref struct RORefToSpan
{
    private readonly Span<int> _span;
    public void Method(Span<int> span) { }
}

class Program
{
    public static void LocalToRef(RefToSpan r)
    {
        Span<int> local = stackalloc int[1];
        r.Method(local); // ここでエラーになる。r の中身が書き換えられることで、local が外に漏れる可能性を危惧

        // 注: この例の場合は実際には漏れはしないものの、RefToSpan の作り次第なので保証はできない
    }

    public static void LocalToRORef(RORefToSpan r)
    {
        Span<int> local = stackalloc int[1];
        r.Method(local); // readonly ref に対してなら OK
    }
}

ローカルで定義したSpan<T>を、引数で渡ってきたref構造体のメソッドに対して渡しています。 この場合、readonlyがついている場合にだけコンパイルできます。 readonlyがついていない方では、メソッドの中でrが書き換わる可能性があります。 その結果「ローカルのSpan<T>が外に漏れる可能性がある」という判定を受けるため、コンパイル エラーになります。 readonlyがついている方では「書き換えがあり得ない」ということで、「外にも漏れない」という判定になります。

余談: さすがに unsafe までは追えない

unsafe static Span<int> X()
{
    // ローカル
    int x = 10;

    // unsafe な手段でローカルなものの参照を作って返す
    // これをやってしまうとまずいものの、コンパイル時にはエラーにできない
    return new Span<int>(&x, 1);
}

「スタックのみ」制約

まず、ref 構造体以前に、参照自体がスタック上でしか使えません。 参照は、常にその参照の出所をトラッキングする必要があります。 例えば、出所がクラス(.NET のガベージ コレクションの管理下)の場合、 それを参照する方もガベージ コレクションのトラッキングの対象になります。 このトラッキング処理を低コストで行うためには、参照がスタック上になければなりません。

次に、マルチスレッド動作に関してですが、 Span<T> の中身が論理的には (ref T Reference, int Length) という2要素からなることによります。 安全に使うには、この2つがアトミックに読み書きされなければなりません。 もし、Reference だけが書き換わり、Length がまだ書き換わっていないタイミングで参照先を読み書きされてしまうと、 範囲チェックが正しく働かず、不正な領域を読み書きしてしまう危険性が出てきます。

ということで、「スタック上に置かれている必要がある」という制約が掛かります。 具体的には、以下のような制限があります。

• クラスのフィールドとして持てない(クラスに ref 修飾子を付けれない理由はこれ)
• クラスのフィールドに昇格する可能性があることができない
  • ローカル関数やラムダ式でキャプチャできない
  • イテレーターの引数には使えない
  • イテレーター内では、yield return をまたいで使えない
  • 非同期メソッドに対しては引数にもローカル変数にも使えない
    • (C# 13 で緩和。C# 13 からは、await をまたがない限り、ローカル変数に使えます)
• ボックス化できない
  • objectやdynamic、インターフェイス型の変数に代入できない
  • ToString など、object 型のメソッドを呼べない
• ジェネリック型引数として使えない

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

//❌ そもそもクラスに ref を付けれないのも stack-only を保証するため
ref class Class { }

//❌ インターフェイス実装
ref struct RefStruct : IDisposable { public void Dispose() { } }

class Program
{
    //❌ 非同期メソッドの引数
    static async Task Async(Span<int> x)
    {
        //❌ 非同期メソッドのローカル変数
        Span<int> local = stackalloc int[10];
    }

    //❌ イテレーターの引数
    static IEnumerable<int> Iterator(Span<int> x)
    {
        Span<int> local = stackalloc int[10];
        local[0] = 1; //⭕ yield return をまたがないならOK
        yield return local[0];
        //❌ yield をまたいだ読み書き
        local[0] = 2; // ダメ
    }

    static void Main()
    {
        Span<int> local = stackalloc int[1];

        //❌ box 化
        object obj = local;

        //❌ object のメソッド呼び出し
        var str = local.ToString();

        //❌ クロージャ
        Func<int> a1 = () => local[0];
        int F() => local[0];

        //❌ 型引数にも渡せない
        List<Span<int>> list;
    }
}

余談: TypedReference

「型付き参照」で説明しているTypedReference型も、内部的に参照を持っている型の1つです。 TypedReference は ref 構造体の仕様よりも古くからあって、昔はこの型だけに対して特殊対応をしていました。

その昔からある TypedReference に対する特殊対応は、本項で説明している C# 7.2 から入った ref 構造体に対する制約よりもだいぶ緩くて、実は「スタック上に置かれている必要がある」制約から割かし簡単に外れることができました。

ちなみに、C# 7.2 で ref 構造体を導入後、 .NET Core 2.1 からは TypedReference に対する特殊対応は止めて、単に TypedReference を ref 構造体に変更したようです。 結果的に元よりも制約が厳しくなっていて、昔は(バグっている可能性が非常に高いものの)一応コンパイルできていたコードがコンパイル エラーになる可能性があります。 (ただ、TypedReference 自体利用頻度が非常に低いので問題にはなっていません。)

ref フィールド

Ver. 11

C# 11 で、ref 構造体のフィールドを ref (参照渡し)で持てるようになりました。 これを ref フィールド(ref field)と言います。

ref フィールドの書き方は参照引数や参照戻り値と同じく、型の前に ref 修飾を付けます。

ref struct ByReference<T>
{
    public ref T Value;
}

C# 7.2 に頃に Span<T> 構造体の内部的な話で、「Span<T> はランタイム側で特殊処理を入れている」というような話を書いていましたが、 ref フィールドが入ったことで、通常の C# コードで同様のことができるようになりました。 実際、.NET 7 からはそういう実装に置き換わっていて、Span<T> の内部は晴れて以下のようなコードに変更されています。

ref struct Span<T>
{
    internal readonly ref T _reference;
    private readonly int _length;
}

ちなみに、ref フィールドを持てるのは ref 構造体だけです。 以下のコードはコンパイル エラーになります。

class A
{
    ref int _x; // class 中はダメ。
}

struct B
{
    ref int _x; // struct も ref がついてないものの中はダメ。
}

readonly ref

C# 7.2 の頃に ref readonly というものがありました。 これは、「参照先の値の変更不可」というものです。 一方で、ref フィールドになると、ref readonly と readonly ref の2種類の readonly ができます(あるいは両方付けて readonly ref readonly もできます)。

比較のためにまず、どちらの readonly もついていない状態ですが、 当然、「どこを参照するか変更」と「参照先の値の変更」のどちらもできます。

scoped var a = new A();

int x1 = 0;
a.X = ref x1; // どこを参照するかを変更。

a.X = 2; // 参照先の値を変更

ref struct A
{
    public ref int X;
}

で、ref readonly の方は C# 7.2 の頃からある意味と同じで、「参照先の値の変更不可」です。

scoped var a = new A();

int x1 = 0;
a.X = ref x1; // どこを参照するかを変更。

a.X = 2; // エラー: 参照先の値を変更不可。

ref struct A
{
    public ref readonly int X;
}

一方、C# 11 から書ける readonly ref は、要は、ref フィールド ref T X を readonly にするという意味なので、「どこを参照するか変更」の方ができなくなります。

int x0 = 0;

// readonly フィールドはコンストラクターでしか初期化できないので引数で渡す。
scoped var a = new A(ref x0);

int x1 = 1;
a.X = ref x1; // エラー: どこを参照するかを変更不可。

a.X = 2; // 参照先の値を変更はできる。

ref struct A
{
    public readonly ref int X;
    public A(ref int x) => X = ref x;
}

当然、両方の readonly を付けると両方不可です。

int x0 = 0;

// readonly フィールドはコンストラクターでしか初期化できないので引数で渡す。
scoped var a = new A(ref x0);

int x1 = 1;
a.X = ref x1; // エラー: どこを参照するかを変更不可。

a.X = 2; // エラー: 参照先の値を変更不可。

ref struct A
{
    public readonly ref readonly int X;
    public A(ref int x) => X = ref x;
}

エスケープ解析

参照を使う上では、「漏らしてはいけないものを漏らさない」ということが必要になります。 簡単に言うと、メソッド内のローカル変数はメソッドを抜けると消えるので、 その参照は外に漏らしてはいけません。

static ref int M()
{
    int x = 123; // メソッド内の変数はメソッド抜けると消える。
    return ref x; // エラー: 消えるものと外には漏らせない。
}

こういう「漏れている」状態を「エスケープ(escape: 脱走)している」と言います。

上記の例の場合は単純ですが、 参照変数などがあるため、間接的に何段も追いかける必要があります。

static ref int M()
{
    int x = 123; // メソッド内の変数はメソッド抜けると消える。
    ref var y = ref x;
    ref var z = ref y;
    return ref z; // エラー: 間に2段挟まっているものの、元は x なので外に漏らせない。
}

このように、間に何段か挟まっていようと、大本をたどってエスケープを避ける処理を「エスケープ解析」(escape analysis)と呼びます。

C# 7.2 で ref 構造体が、 C# 11 で ref フィールドが入ったわけですが、 エスケープ解析はこれらも考慮する必要があります。

例えばわざとちょっと複雑なことをすると、以下のように、いろいろなところに参照が伝搬するコードが書けます。

static void M(out Span<int> result)
{
    int x = 123;
    var span = new Span<int>(ref x); // x が span から参照される状態。
    scoped var r = new R();

    var ret = r.M(span, out var y); // x がいろんなところに伝搬。

    result = r.Span; // エラー: x が r.Span に伝搬してるかもしれないのでダメ。
    result = y;      // エラー: x が y に伝搬してるかもしれないのでダメ。
    result = ret;    // エラー: x が ret に伝搬してるかもしれないのでダメ。
}

ref struct R
{
    public Span<int> Span;

    public Span<int> M(Span<int> x, out Span<int> y)
    {
        Span = x; // フィールドにも、
        y = x;    // out 引数にも、
        return x; // 戻り値にも x (が持ってる参照)が伝搬。
    }
}

コスト度外視でよければ、 「どの引数・フィールドが、他のどの引数・フィールド・戻り値に伝搬するか」を事細かに指定することで厳密なエスケープ解析ができます。 (C# では採用しなかったため)仮定的なコードにはなりますが、 先ほどのコードを以下のように書けるようにするという案はなくはないです。

static void M(out Span<int> result)
{
    int x = 123;
    var span1 = new Span<int>(ref x); // x が span から参照される状態。
    var span2 = new int[1];           // こちらは配列を参照しているので外に漏らしても大丈夫。

    var r = new R { Span = span1 };

    var ret = r.M(span2, out var y); // span2 → y, span1 → r.Span → ret と伝搬。

    result = y;      // 出どころが y → span2 → 配列 なので外に漏らして大丈夫。
    result = ret;    // 出どころが ret → r.Span → span1 → x なのでダメ。
}

// 仮定的な文法: ` で、参照の伝搬先を表現。
ref struct R
{
    public Span<int>`A Span;

    public Span<int>`A M(Span<int>`B x, out Span<int>`B y)
    {
        // 伝搬先の指定が違うので、以下のコードはダメ。
        // Span = x;
        // return x;
        y = x;       // `B 間の伝搬は OK。
        return Span; // `A 間の伝搬は OK。
    }
}

scoped 修飾子

ただ、ここまで細かい指定に需要があるかというと微妙です。 そこで C# 11 では、以下の2種類だけに絞ることにしました。

• scoped: どこにも漏らさない。メソッドの中でだけ使う。
• unscoped: どこかに漏らす。

ref 構造体(Span<T> など)に関しては実際にこの2択で、 何もつかなかった場合は unscoped 扱いで、scoped という新しい修飾子を付けると scoped 扱いになります。

一方で、ref T (ref 引数・ref 変数)に関しては、 既存コードを壊さないように、何もつけないと「引数から戻り値への伝搬だけ認める」(通称 return-only)というわかりにくいルールになっています。 そして、UnscopedRef 属性(System.Diagnostics.CodeAnalysis 名前空間)を付けると unscoped 扱い、 scoped 修飾子を付けると scoped 扱いになります。 (またちょっとややこしいことに、コンストラクターの引数の場合だけ、ref T でも unscoped 扱いみたいです。)

実際のコードを見てみましょう。 まず、何もつけない場合(ref T は return-only、ref 構造体は unscoped):

ref struct Default
{
    private ref int _x;
    private Span<int> _y;

    // OK なやつ。
    public Default(ref int x) => _x = ref x;
    public ref int ReturnRef(ref int x) => ref x;
    public ref int GetRef() => ref _x;
    public void UseRef(ref int x) { }

    public Default(Span<int> y) => _y = y;
    public Span<int> ReturnSpan(Span<int> y) => y;
    public Span<int> GetSpan() => _y;
    public void SetSpan(Span<int> y) => _y = y;
    public void UseSpan(Span<int> y) { }

    // エラーになるやつ。
    // 引数 → フィールドへの伝搬だけ、ref T と Span<T> の挙動が違う。
    // ref T は「引数 → 戻り値 だけは OK」(return-only)。
    public void SetRef(ref int x) => _x = ref x;
}

続いて、scoped 修飾子を付けた場合(いずれも scoped 扱い)、たいていのものがダメになります:

ref struct Scoped
{
    private ref int _x;
    private Span<int> _y;

    // OK なやつ。
    // フィールドにも戻りにも伝搬しない場合だけ OK。
    public void UseRef(scoped ref int x) { }
    public void UseSpan(scoped Span<int> y) { }

    // エラーになるやつ。
    // たいていダメ。
    public Scoped(scoped ref int x) => _x = ref x;
    public ref int ReturnRef(scoped ref int x) => ref x;
    public void SetRef(scoped ref int x) => _x = ref x;

    public Scoped(scoped Span<int> y) => _y = y;
    public Span<int> ReturnSpan(scoped Span<int> y) => y;
    public void SetSpan(scoped Span<int> y) => _y = y;
}

最後に、UnscopedRef 属性を付けた場合、たいていのものが OK になります (ただし、ref 構造体は何も付けなくても unscoped 扱いなので、追加で属性を付けようとするとエラーになります):

using System.Diagnostics.CodeAnalysis;

ref struct Unscoped
{
    private ref int _x;
    private Span<int> _y;

    // OK なやつ。
    // UnscopedRef 属性を付けるとなんでも OK に。
    // (といっても差が出るのは SetRef だけ。)
    public Unscoped([UnscopedRef] ref int x) => _x = ref x;
    public ref int ReturnRef([UnscopedRef] ref int x) => ref x;
    public void SetRef([UnscopedRef] ref int x) => _x = ref x;
    public void UseRef([UnscopedRef] ref int x) { }

    // Span の方は「デフォルトで UnscopedRef だから属性付けるな」とエラーになる。
    public Unscoped([UnscopedRef] Span<int> y) => _y = y;
    public Span<int> ReturnSpan([UnscopedRef] Span<int> y) => y;
    public void SetSpan([UnscopedRef] Span<int> y) => _y = y;
    public void UseSpan([UnscopedRef] Span<int> y) { }
}

呼び出し元の挙動

この手の機能は、 「メソッド内でできることを制限する代わりに、呼び出し元でできることを増やす」というものです。

例えば、unscoped (何も修飾子を付けていない ref 構造体)の場合、以下のように、 Builder.Replace の中で制限がない代わり、それを呼んでいる場所でのエラーが増えます。

var builder = new Builder();

Replace(ref builder);

static void Replace(ref Builder builder)
{
    Span<char> newBuffer = stackalloc char[3];
    builder.Replace(newBuffer); // ダメ。stackalloc したものが builder 越しに外に漏れる。
}

ref struct Builder(Span<char> initialBuffer)
{
    private Span<char> _buffer = initialBuffer;

    public void Replace(Span<char> value)
    {
        // 参照先自体を書き換え。
        // 引数からフィールドに参照が伝搬。
        _buffer = value;
    }
}